@open-agent-toolkit/cli 0.3.16 → 0.3.17

package/dist/commands/shared/exact-path-commit.js

@@ -0,0 +1,691 @@
+import { execFile, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import * as nodeFs from 'node:fs';
+import { constants } from 'node:fs';
+import { access, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import * as nodePath from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+const defaults = {
+    attempts: 3,
+    retryDelaysMs: [100, 300],
+    sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+};
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function environment(index) {
+    const env = {
+        ...process.env,
+        LANG: 'C',
+        LC_ALL: 'C',
+        LANGUAGE: 'C',
+    };
+    for (const key of [
+        'GIT_DIR',
+        'GIT_WORK_TREE',
+        'GIT_INDEX_FILE',
+        'GIT_COMMON_DIR',
+        'GIT_OBJECT_DIRECTORY',
+        'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+        'GIT_NAMESPACE',
+    ])
+        delete env[key];
+    if (index)
+        env.GIT_INDEX_FILE = index;
+    return env;
+}
+async function git(root, args, index) {
+    const { stdout } = await exec('git', ['--literal-pathspecs', ...args], {
+        cwd: root,
+        env: environment(index),
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    return stdout.trimEnd();
+}
+async function bytes(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+// Serialized into the hook companion as well: only Git-emitted directory
+// boundaries recurse, and links remain literal. Ignored files retain Git's
+// ordinary inventory semantics; no nested metadata is refreshed or written.
+function preservationIdentity(full, boundary, dependencies) {
+    const { fs: fileSystem, path: paths, spawnSync: runCommand, createHash: hashFactory, } = dependencies;
+    const hash = (value) => hashFactory('sha256').update(value).digest('hex');
+    let info;
+    try {
+        info = fileSystem.lstatSync(full);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 'absent';
+        throw error;
+    }
+    if (info.isSymbolicLink())
+        return `symlink:${fileSystem.readlinkSync(full)}`;
+    const physical = fileSystem.realpathSync(full);
+    const confined = paths.relative(boundary, physical);
+    if (confined === '..' ||
+        confined.startsWith('../') ||
+        paths.isAbsolute(confined))
+        throw new Error(`Unowned inventory escapes repository: ${full}`);
+    if (!info.isDirectory())
+        return `${info.mode}:${hash(fileSystem.readFileSync(full))}`;
+    const env = { ...process.env, GIT_OPTIONAL_LOCKS: '0' };
+    for (const key of [
+        'GIT_DIR',
+        'GIT_WORK_TREE',
+        'GIT_INDEX_FILE',
+        'GIT_COMMON_DIR',
+        'GIT_OBJECT_DIRECTORY',
+        'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+        'GIT_NAMESPACE',
+    ])
+        delete env[key];
+    const run = (args) => runCommand('git', ['--literal-pathspecs', ...args], {
+        cwd: full,
+        env,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const top = run(['rev-parse', '--show-toplevel']);
+    if (top.status !== 0 ||
+        fileSystem.realpathSync(top.stdout.trimEnd()) !== physical) {
+        if (fileSystem.readdirSync(full).length === 0)
+            return `${info.mode}:empty-directory`;
+        throw new Error(`Directory inventory is not a nested Git boundary: ${full}`);
+    }
+    const inventory = run([
+        'ls-files',
+        '-z',
+        '--cached',
+        '--others',
+        '--exclude-standard',
+    ]);
+    const index = run(['rev-parse', '--git-path', 'index']);
+    const head = run(['rev-parse', '--verify', 'HEAD']);
+    if (inventory.status !== 0 || index.status !== 0)
+        throw new Error(`Cannot inspect nested Git inventory: ${full}`);
+    let indexBytes;
+    try {
+        indexBytes = fileSystem.readFileSync(paths.resolve(full, index.stdout.trimEnd()));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const entries = [...new Set(inventory.stdout.split('\0').filter(Boolean))]
+        .sort()
+        .map((entry) => {
+        const child = paths.resolve(full, entry);
+        const childRelative = paths.relative(full, child);
+        if (!childRelative ||
+            childRelative === '..' ||
+            childRelative.startsWith('../') ||
+            paths.isAbsolute(childRelative))
+            throw new Error(`Invalid nested Git inventory path: ${entry}`);
+        let parent = paths.dirname(child);
+        while (!fileSystem.existsSync(parent))
+            parent = paths.dirname(parent);
+        const ancestor = paths.relative(boundary, fileSystem.realpathSync(parent));
+        if (ancestor === '..' ||
+            ancestor.startsWith('../') ||
+            paths.isAbsolute(ancestor))
+            throw new Error(`Nested inventory traverses an external link: ${entry}`);
+        return [entry, preservationIdentity(child, boundary, dependencies)];
+    });
+    return `${info.mode}:git:${hash(JSON.stringify([head.status === 0 ? head.stdout.trimEnd() : '', indexBytes ? hash(indexBytes) : 'absent', entries]))}`;
+}
+function fileIdentity(full, boundary) {
+    return preservationIdentity(full, boundary, {
+        fs: nodeFs,
+        path: nodePath,
+        spawnSync,
+        createHash,
+    });
+}
+async function writeReceipt(path, receipt) {
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(receipt));
+    await rename(temporary, path);
+}
+function detail(error) {
+    const failure = error;
+    return failure.stderr?.trim() || failure.message || String(error);
+}
+async function assertNoInProgressGitOperation(root) {
+    for (const state of [
+        'MERGE_HEAD',
+        'CHERRY_PICK_HEAD',
+        'REVERT_HEAD',
+        'REBASE_HEAD',
+        'rebase-apply',
+        'rebase-merge',
+        'sequencer',
+    ]) {
+        // Resolve through Git: linked worktrees keep these markers in their own
+        // metadata directory rather than the checkout's .git file or common dir.
+        const path = resolve(root, await git(root, ['rev-parse', '--git-path', state]));
+        const exists = await lstat(path).then(() => true, (error) => {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        });
+        if (exists)
+            throw new Error(`Repository has an in-progress Git operation (${state}); resolve or abort it before retrying. No commit was launched.`);
+    }
+    if (await git(root, ['ls-files', '--unmerged']))
+        throw new Error('Repository has unmerged index entries; resolve them before retrying. No commit was launched.');
+}
+async function exactPaths(root, supplied, receiptPaths = []) {
+    if (!supplied.length)
+        throw new Error('Supply at least one exact file path.');
+    const paths = [];
+    for (const value of supplied) {
+        if (!value || value.includes('\0'))
+            throw new Error('File paths must be nonblank literal paths.');
+        const absolute = resolve(root, value);
+        const path = relative(root, absolute);
+        if (!path ||
+            path === '..' ||
+            path.startsWith('../') ||
+            isAbsolute(path) ||
+            path.split('/').includes('.git'))
+            throw new Error(`Path is outside repository ownership: ${value}`);
+        let ancestor = dirname(absolute);
+        while (!(await access(ancestor).then(() => true, () => false)))
+            ancestor = dirname(ancestor);
+        const physical = relative(root, await realpath(ancestor));
+        if (physical === '..' || physical.startsWith('../'))
+            throw new Error(`Path traverses a symlink outside the repository: ${value}`);
+        const info = await lstat(absolute).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (info?.isDirectory())
+            throw new Error(`Directories are not exact file paths: ${value}`);
+        const headEntry = !info
+            ? await git(root, ['ls-tree', '-z', 'HEAD', '--', path]).catch(() => '')
+            : '';
+        const trackedHeadFile = headEntry
+            .split('\0')
+            .some((entry) => /^(100644|100755|120000) blob [a-f0-9]+\t/.test(entry) &&
+            entry.slice(entry.indexOf('\t') + 1) === path);
+        if (!info &&
+            !receiptPaths.includes(path) &&
+            !trackedHeadFile &&
+            !(await git(root, ['ls-files', '-z', '--error-unmatch', '--', path]).then((output) => output.split('\0').includes(path), () => false)))
+            throw new Error(`Absent path is not a tracked removal: ${value}`);
+        const entry = await git(root, ['ls-files', '--stage', '--', path]);
+        if (/^160000 /m.test(entry) || / [123]\t/.test(entry))
+            throw new Error(`Unmerged paths and submodules require explicit resolution: ${value}`);
+        paths.push(path);
+    }
+    return [...new Set(paths)].sort();
+}
+/** Use an isolated index for enabled hooks; publish only owned entries under Git's lock.
+ * The real lock is held during hooks, so ordinary competing Git writers cannot lose
+ * their changes. A byte comparison also detects writers bypassing that protocol.
+ * Never restore a snapshot over current user data, and never remove a foreign lock.
+ */
+export async function commitExactPaths(input, overrides = {}) {
+    const policy = { ...defaults, ...overrides };
+    let receiptPath;
+    let commit;
+    let attempts = 0;
+    let root;
+    let indexPath;
+    let paths;
+    try {
+        if (!input.identity.trim() || !input.message.trim())
+            throw new Error('Message and operation identity must be nonblank.');
+        root = await realpath((await git(input.repoRoot, ['rev-parse', '--show-toplevel'])).trim());
+        // Refuse before creating receipt directories, index locks or temporary state.
+        await assertNoInProgressGitOperation(root);
+        indexPath = resolve(root, (await git(root, ['rev-parse', '--git-path', 'index'])).trim());
+        const receipts = join(dirname(indexPath), 'oat-exact-path-commits');
+        receiptPath = join(receipts, `${digest(input.identity)}.json`);
+        const prior = await bytes(receiptPath);
+        const priorPaths = prior
+            ? JSON.parse(prior.toString()).paths
+            : [];
+        paths = await exactPaths(root, input.paths, priorPaths);
+        await mkdir(receipts, { recursive: true });
+    }
+    catch (error) {
+        return {
+            outcome: 'failed',
+            committed: false,
+            attempts,
+            error: detail(error),
+            lockClass: 'other',
+        };
+    }
+    // Catchable termination must not strand our lock or release it while Git's
+    // enabled hooks can still write. An in-flight child is awaited normally;
+    // terminal-delivered signals may also stop Git, whose close settles its pipes.
+    // A nonterminating hook can delay this settlement indefinitely. Abrupt death
+    // is deliberately outside this operation-scoped handler.
+    let interrupted;
+    const onTerm = () => {
+        interrupted ??= 'SIGTERM';
+    };
+    const onInt = () => {
+        interrupted ??= 'SIGINT';
+    };
+    process.on('SIGTERM', onTerm);
+    process.on('SIGINT', onInt);
+    try {
+        const lockPath = `${indexPath}.lock`;
+        let firstMtime;
+        while (attempts < policy.attempts) {
+            if (interrupted)
+                return {
+                    outcome: 'failed',
+                    committed: false,
+                    attempts,
+                    receipt: receiptPath,
+                    resumable: true,
+                    error: `${interrupted} received before commit; retry the same identity.`,
+                    lockClass: 'other',
+                };
+            attempts++;
+            let lock;
+            try {
+                lock = await open(lockPath, 'wx');
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    return {
+                        outcome: 'failed',
+                        committed: false,
+                        attempts,
+                        error: detail(error),
+                    };
+                const current = await stat(lockPath).catch(() => undefined);
+                if (attempts === 1)
+                    firstMtime = current?.mtimeMs;
+                if (attempts < policy.attempts) {
+                    await policy.sleep(policy.retryDelaysMs[attempts - 1] ?? 0);
+                    continue;
+                }
+                return {
+                    outcome: 'blocked',
+                    committed: false,
+                    attempts,
+                    receipt: receiptPath,
+                    resumable: true,
+                    lockClass: firstMtime !== undefined && firstMtime === current?.mtimeMs
+                        ? 'persistent-index-lock'
+                        : 'transient-index-lock',
+                    error: `Git index lock remains at ${lockPath}. Its owner must finish; retry the same identity. No lock was removed.`,
+                };
+            }
+            const ownedLock = await lock.stat();
+            const stillOwnLock = async () => {
+                const current = await stat(lockPath).catch(() => undefined);
+                return current?.ino === ownedLock.ino && current.dev === ownedLock.dev;
+            };
+            let temporary;
+            let temporaryIdentity;
+            let operationResult;
+            let published = false;
+            let startedParent;
+            let settledCommit;
+            let storedCommittedReceipt = false;
+            let verifiedPriorCommit = false;
+            let resumable = true;
+            try {
+                if (interrupted)
+                    throw new Error(`${interrupted} received before commit; no commit was launched.`);
+                await assertNoInProgressGitOperation(root);
+                const snapshot = await bytes(indexPath);
+                const head = await git(root, ['rev-parse', '--verify', 'HEAD']).catch(() => '');
+                const receiptBytes = await bytes(receiptPath);
+                let receipt = receiptBytes
+                    ? JSON.parse(receiptBytes.toString())
+                    : undefined;
+                if (receipt &&
+                    (receipt.identity !== input.identity ||
+                        JSON.stringify(receipt.paths) !== JSON.stringify(paths)))
+                    throw new Error('Operation identity already names different owned paths; supply a distinct identity.');
+                if (receipt?.commit) {
+                    commit = receipt.commit;
+                    storedCommittedReceipt = true;
+                }
+                else if (receipt) {
+                    // Recover the window after Git wrote the commit but before receipt publication.
+                    const candidates = (await git(root, [
+                        'log',
+                        '--format=%H',
+                        '--fixed-strings',
+                        `--grep=Oat-Operation: ${digest(input.identity)}`,
+                    ]))
+                        .split('\n')
+                        .filter(Boolean);
+                    for (const candidate of candidates) {
+                        if ((await git(root, ['show', '-s', '--format=%P', candidate]).catch(() => '')) === receipt.parent) {
+                            commit = candidate;
+                            break;
+                        }
+                    }
+                    if (candidates.length && !commit) {
+                        resumable = false;
+                        throw new Error('Receipt does not positively match the committed artifact: operation-trailer candidates exist, but none matches the expected receipt parent. Preserve the receipt for inspection and explicit provenance reconciliation; an unchanged same-identity retry cannot resolve this condition.');
+                    }
+                }
+                if (commit && receipt) {
+                    // Resolution and persistence are separate: history recovery must pass
+                    // the same provenance checks without pretending metadata was stored.
+                    const tree = await git(root, ['rev-parse', `${commit}^{tree}`]);
+                    if ((await git(root, ['show', '-s', '--format=%P', commit])) !==
+                        receipt.parent ||
+                        ((storedCommittedReceipt || receipt.tree !== undefined) &&
+                            tree !== receipt.tree) ||
+                        !(await git(root, ['show', '-s', '--format=%B', commit])).includes(`Oat-Operation: ${digest(input.identity)}`))
+                        throw new Error('Receipt does not positively match the committed artifact.');
+                    await git(root, ['merge-base', '--is-ancestor', commit, head]);
+                    receipt = { ...receipt, commit, tree };
+                    verifiedPriorCommit = true;
+                }
+                const resuming = commit !== undefined;
+                temporary = await mkdtemp(join(dirname(indexPath), 'oat-commit-'));
+                temporaryIdentity = await lstat(temporary);
+                const isolated = join(temporary, 'index');
+                if (!commit) {
+                    await git(root, head ? ['read-tree', head] : ['read-tree', '--empty'], isolated);
+                    await git(root, ['add', '-A', '--', ...paths], isolated);
+                    if (!(await git(root, ['diff', '--cached', '--name-only'], isolated)))
+                        return (operationResult = {
+                            outcome: 'nothing',
+                            committed: false,
+                            attempts,
+                        });
+                    const unrelated = (await git(root, [
+                        'ls-files',
+                        '-z',
+                        '--cached',
+                        '--others',
+                        '--exclude-standard',
+                    ]))
+                        .split('\0')
+                        .filter((path) => path && !paths.includes(path));
+                    const worktree = Object.fromEntries(await Promise.all([...new Set(unrelated)].map(async (path) => [
+                        path,
+                        fileIdentity(join(root, path), root),
+                    ])));
+                    const configured = await git(root, [
+                        'config',
+                        '--path',
+                        '--get',
+                        'core.hooksPath',
+                    ]).catch(() => '');
+                    const originalHooks = configured
+                        ? resolve(root, configured)
+                        : resolve(root, await git(root, ['rev-parse', '--git-path', 'hooks']));
+                    const hooks = join(temporary, 'hooks');
+                    await mkdir(hooks);
+                    const shellQuote = (value) => `'${value.replaceAll("'", "'\"'\"'")}'`;
+                    const guardedHooks = [
+                        'pre-commit',
+                        'prepare-commit-msg',
+                        'commit-msg',
+                        'post-commit',
+                    ];
+                    const originalNames = await readdir(originalHooks).catch((error) => {
+                        // Missing directories and disabled hooksPath=/dev/null have no hooks.
+                        if (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+                            return [];
+                        throw error;
+                    });
+                    // Preserve every other executable hook Git may invoke, including ref
+                    // transactions and index notifications. Their protocols do not accept
+                    // the commit-staging guard: exec preserves argv, streams and exit status.
+                    for (const name of originalNames) {
+                        if (guardedHooks.includes(name))
+                            continue;
+                        const source = join(originalHooks, name);
+                        if (!(await access(source, constants.X_OK).then(() => true, () => false)))
+                            continue;
+                        await writeFile(join(hooks, name), `#!/bin/sh\nexec ${shellQuote(source)} "$@"\n`, { mode: 0o700 });
+                    }
+                    // Delegate original executable commit hooks, then guard the emitted
+                    // tree before Git accepts it. Keep their existing isolated-index guards.
+                    for (const name of guardedHooks) {
+                        const source = join(originalHooks, name);
+                        const executable = await access(source, constants.X_OK).then(() => true, () => false);
+                        if (!executable && name === 'post-commit')
+                            continue;
+                        const script = `#!/usr/bin/env node\nconst {spawnSync}=require('node:child_process');const fs=require('node:fs');const crypto=require('node:crypto');const path=require('node:path');\n// tsx retains inferred function names with this identity decorator.\nconst __name=(fn)=>fn;\n${preservationIdentity.toString()}\n${executable ? `const hook=spawnSync(${JSON.stringify(source)},process.argv.slice(2),{stdio:'inherit'});if(hook.error||hook.status!==0)process.exit(hook.status||1);` : ''}\n${name !== 'post-commit' ? `const owned=${JSON.stringify(paths)};const staged=spawnSync('git',['diff','--cached','--name-only','-z'],{encoding:'utf8'});if(staged.status!==0||staged.stdout.split('\\0').some(p=>p&&!owned.includes(p))){process.stderr.write('Exact-path ownership guard: hook staged an unowned path.\\n');process.exit(1);}const before=${JSON.stringify(worktree)};for(const [p,expected]of Object.entries(before)){const actual=preservationIdentity(path.resolve(p),${JSON.stringify(root)},{fs,path,spawnSync,createHash:crypto.createHash});if(actual!==expected){process.stderr.write('Exact-path preservation guard: unowned worktree path changed: '+p+'\\n');process.exit(1);}}` : ''}\n`;
+                        // Git requires extensionless hook names. Launch an explicitly CommonJS
+                        // companion so the repository's package type cannot reinterpret it.
+                        const companion = join(hooks, `${name}.cjs`);
+                        await writeFile(companion, script);
+                        await writeFile(join(hooks, name), `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(companion)} "$@"\n`, { mode: 0o700 });
+                    }
+                    if (interrupted)
+                        throw new Error(`${interrupted} received before commit; no commit was launched.`);
+                    // Recheck the real index and operation state immediately before launch.
+                    await assertNoInProgressGitOperation(root);
+                    receipt = { identity: input.identity, paths, parent: head };
+                    await writeReceipt(receiptPath, receipt);
+                    if (interrupted)
+                        throw new Error(`${interrupted} received before commit; no commit was launched.`);
+                    startedParent = head;
+                    await git(root, [
+                        '-c',
+                        `core.hooksPath=${hooks}`,
+                        'commit',
+                        '-m',
+                        `${input.message}\n\nOat-Operation: ${digest(input.identity)}`,
+                    ], isolated);
+                    commit = await git(root, ['rev-parse', 'HEAD']);
+                    if ((await git(root, ['show', '-s', '--format=%P', commit])) !== head ||
+                        !(await git(root, ['show', '-s', '--format=%B', commit])).includes(`Oat-Operation: ${digest(input.identity)}`))
+                        throw new Error('Commit identity/parent could not be verified.');
+                    for (const [path, before] of Object.entries(worktree)) {
+                        if (fileIdentity(join(root, path), root) !== before)
+                            throw new Error(`Unowned worktree path changed during hooks: ${path}; current bytes preserved for inspection.`);
+                    }
+                    receipt = {
+                        ...receipt,
+                        commit,
+                        tree: await git(root, ['rev-parse', `${commit}^{tree}`]),
+                    };
+                }
+                const emitted = (await git(root, [
+                    'diff-tree',
+                    '--root',
+                    '--no-commit-id',
+                    '-r',
+                    '--no-renames',
+                    '--name-only',
+                    '-z',
+                    commit,
+                ]))
+                    .split('\0')
+                    .filter(Boolean);
+                if (emitted.some((path) => !paths.includes(path)))
+                    throw new Error('Committed artifact contains unowned paths; manual inspection required.');
+                if (resuming && !(await bytes(receiptPath))?.equals(receiptBytes))
+                    throw new Error('Verified receipt was replaced; replacement preserved for inspection.');
+                if (resuming &&
+                    (await git(root, [
+                        'diff',
+                        '--name-only',
+                        commit,
+                        head,
+                        '--',
+                        ...paths,
+                    ])).length) {
+                    // A later owned generation cannot authorize republishing the old tree.
+                    // Only a validated receipt and the current published HEAD allow its
+                    // marker owner to retire the obsolete reservation, even when the new
+                    // producer worktree equals the old tree (prune -> recreate -> prune).
+                    const current = join(temporary, 'current');
+                    if (snapshot)
+                        await writeFile(current, snapshot);
+                    else
+                        await git(root, ['read-tree', '--empty'], current);
+                    if (verifiedPriorCommit &&
+                        !(await git(root, ['diff', '--cached', '--name-only', head, '--', ...paths], current)).length &&
+                        (await bytes(indexPath))?.equals(snapshot ?? Buffer.alloc(0)) &&
+                        (await bytes(receiptPath))?.equals(receiptBytes) &&
+                        (await git(root, ['rev-parse', '--verify', 'HEAD'])) === head &&
+                        (await stillOwnLock()))
+                        settledCommit = commit;
+                    throw new Error('Owned artifact changed since this operation committed; use a new identity.');
+                }
+                if (!storedCommittedReceipt)
+                    await writeReceipt(receiptPath, receipt);
+                // Copy current index into a disposable merge, never into the live index.
+                // Only owned entries are reset to the verified hook-final tree.
+                const merged = join(temporary, 'merged');
+                if (snapshot)
+                    await writeFile(merged, snapshot);
+                else
+                    await git(root, ['read-tree', '--empty'], merged);
+                const ownedEntriesSettled = storedCommittedReceipt &&
+                    !(await git(root, ['diff', '--cached', '--name-only', commit, '--', ...paths], merged)).length;
+                await git(root, ['reset', '--quiet', commit, '--', ...paths], merged);
+                if ((await git(root, ['diff', '--name-only', commit, '--', ...paths], merged)).length) {
+                    if (ownedEntriesSettled &&
+                        (await bytes(indexPath))?.equals(snapshot ?? Buffer.alloc(0)) &&
+                        (await bytes(receiptPath))?.equals(receiptBytes) &&
+                        (await stillOwnLock()))
+                        settledCommit = commit;
+                    throw new Error('Committed owned bytes differ from the worktree; inspect changes before retrying.');
+                }
+                if (!(await bytes(indexPath))?.equals(snapshot ?? Buffer.alloc(0)) &&
+                    (snapshot !== undefined || (await bytes(indexPath)) !== undefined))
+                    return (operationResult = {
+                        outcome: 'blocked',
+                        committed: true,
+                        commit,
+                        attempts,
+                        receipt: receiptPath,
+                        resumable: true,
+                        error: 'Concurrent real-index change detected. The verified commit exists; current index was preserved. Retry the same identity to finalize owned entries.',
+                    });
+                if (!(await stillOwnLock()))
+                    throw new Error('Owned index lock was replaced; current index and foreign lock preserved. Retry after inspection.');
+                await lock.writeFile(await readFile(merged));
+                await lock.close();
+                await rename(lockPath, indexPath);
+                published = true;
+                return (operationResult = {
+                    outcome: resuming ? 'already-matching' : 'committed',
+                    committed: true,
+                    commit,
+                    attempts,
+                    receipt: receiptPath,
+                    ...(interrupted
+                        ? {
+                            error: `${interrupted} received; committed identity and owned index were verified and settled before cleanup.`,
+                        }
+                        : {}),
+                });
+            }
+            catch (error) {
+                // A terminal signal can stop Git after its ref update. Report only a
+                // positively matched commit; the existing receipt retry owns publication.
+                if (interrupted && !commit && startedParent !== undefined) {
+                    const candidate = await git(root, [
+                        'rev-parse',
+                        '--verify',
+                        'HEAD',
+                    ]).catch(() => '');
+                    if (candidate) {
+                        const parent = await git(root, [
+                            'show',
+                            '-s',
+                            '--format=%P',
+                            candidate,
+                        ]).catch(() => undefined);
+                        const message = await git(root, [
+                            'show',
+                            '-s',
+                            '--format=%B',
+                            candidate,
+                        ]).catch(() => '');
+                        const emitted = await git(root, [
+                            'diff-tree',
+                            '--root',
+                            '--no-commit-id',
+                            '-r',
+                            '--no-renames',
+                            '--name-only',
+                            '-z',
+                            candidate,
+                        ]).catch(() => undefined);
+                        if (parent === startedParent &&
+                            message.includes(`Oat-Operation: ${digest(input.identity)}`) &&
+                            emitted !== undefined &&
+                            emitted
+                                .split('\0')
+                                .filter(Boolean)
+                                .every((entry) => paths.includes(entry)))
+                            commit = candidate;
+                    }
+                }
+                return (operationResult = {
+                    outcome: 'failed',
+                    committed: commit !== undefined,
+                    commit,
+                    ...(settledCommit ? { settledCommit } : {}),
+                    attempts,
+                    receipt: receiptPath,
+                    resumable,
+                    error: `${detail(error)}${interrupted ? ` ${interrupted} received; active Git settled before owned cleanup.${resumable ? ' Retry the same identity to finalize any reported commit.' : ''}` : ''}`,
+                    lockClass: 'other',
+                });
+            }
+            finally {
+                if (!published) {
+                    await lock.close().catch(() => undefined);
+                    if (await stillOwnLock())
+                        await rm(lockPath, { force: true });
+                    else if (operationResult)
+                        delete operationResult.settledCommit;
+                }
+                if (temporary && temporaryIdentity) {
+                    const current = await lstat(temporary).catch((error) => {
+                        if (error.code === 'ENOENT')
+                            return undefined;
+                        throw error;
+                    });
+                    if (current?.ino === temporaryIdentity.ino &&
+                        current.dev === temporaryIdentity.dev)
+                        await rm(temporary, { recursive: true, force: true });
+                    else if (operationResult) {
+                        delete operationResult.settledCommit;
+                        operationResult.outcome = 'failed';
+                        operationResult.resumable = true;
+                        operationResult.error =
+                            `${operationResult.error ?? ''} Operation temporary directory was replaced or removed; replacement preserved for inspection: ${temporary}`.trim();
+                    }
+                }
+            }
+        }
+        return {
+            outcome: 'blocked',
+            committed: false,
+            attempts,
+            resumable: true,
+            error: 'Commit attempt budget must be positive.',
+        };
+    }
+    finally {
+        process.off('SIGTERM', onTerm);
+        process.off('SIGINT', onInt);
+    }
+}