@open-agent-toolkit/cli 0.2.62 → 0.2.64

package/dist/commands/project/log/append.js

@@ -1,6 +1,9 @@
-import { appendFile, readFile, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { basename, isAbsolute, join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
+import { appendFile, readFile, realpath, rm, writeFile, } from 'node:fs/promises';
+import { homedir, hostname, tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { resolveActiveProject, } from '../../../config/oat-config.js';
@@ -10,13 +13,800 @@ import { dirExists, fileExists } from '../../../fs/io.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
 import { Command } from 'commander';
 import { composeJudgmentHeading, composeStructuralHeading, isProjectLogEntryMarker, isProjectLogSectionMarker, PROJECT_LOG_AREA_MAX_LENGTH, PROJECT_LOG_HEADING_DELIMITER, PROJECT_LOG_SCOPES, PROJECT_LOG_TYPES, } from './grammar.js';
-const PROJECT_LOG_FILENAME = 'project-log.md';
+export const PROJECT_LOG_FILENAME = 'project-log.md';
 const SYNTHESIS_HEADING_PREFIX = '\n## End-of-run synthesis';
+/**
+ * Directory, relative to a project, that holds gate partial-finalization
+ * receipts. Ignored by the repository so a receipt never dirties the tree.
+ */
+export const GATE_RECEIPTS_DIRNAME = 'gate-receipts';
+/**
+ * Bounded attempt budget for committing the project log across a transient
+ * `.git/index.lock`. Three attempts means exactly two waits, so the delays
+ * below are the whole window the persistent-versus-transient mtime comparison
+ * spans. Declared here rather than inline so the bound is reviewable and the
+ * gate and the recovery entry point share one budget.
+ */
+export const PROJECT_LOG_COMMIT_ATTEMPTS = 3;
+export const PROJECT_LOG_COMMIT_RETRY_DELAYS_MS = [250, 500];
+const COMMIT_MESSAGE = 'chore(oat): record project log entry';
+/**
+ * Directory, under the OS temp root, that holds the advisory locks serializing
+ * project-log mutations.
+ *
+ * The lock is deliberately *not* stored beside the log. A tracked project
+ * directory would gain an untracked file for the duration of every append, and
+ * a crashed writer would leave one behind for review to trip over. A lock must
+ * also not outlive the machine that took it, which is exactly what a temp root
+ * gives: the receipt needed durability across processes and therefore rejected
+ * `tmpdir()` (DR-260907), while a lock needs the opposite.
+ *
+ * This serializes writers on one machine, which is the condition the gate
+ * actually meets: overlapping `oat` processes in one worktree. It is advisory,
+ * so a writer that cannot take it still proceeds — the identity verification in
+ * `commitProjectLog` is the assurance that a lost entry is never reported as
+ * settled work.
+ */
+const PROJECT_LOG_LOCK_DIRNAME = 'oat-project-log-locks';
+/**
+ * Bounded wait for the advisory lock. Declared rather than inline so the bound
+ * is reviewable: a writer waits at most `WAIT_MS`, polling every `POLL_MS`, and
+ * treats a lock whose owner is gone — or that is older than `STALE_MS` — as
+ * abandoned.
+ */
+export const PROJECT_LOG_LOCK_WAIT_MS = 5_000;
+export const PROJECT_LOG_LOCK_POLL_MS = 25;
+export const PROJECT_LOG_LOCK_STALE_MS = 30_000;
+const DEFAULT_LOCK_DEPENDENCIES = {
+    waitMs: PROJECT_LOG_LOCK_WAIT_MS,
+    pollMs: PROJECT_LOG_LOCK_POLL_MS,
+    staleMs: PROJECT_LOG_LOCK_STALE_MS,
+    sleep: async (ms) => {
+        await new Promise((settle) => setTimeout(settle, ms));
+    },
+    now: () => Date.now(),
+};
+/**
+ * The lock file for one log, keyed by the log's resolved location so two
+ * processes naming the same file through different relative paths — or through
+ * a symlinked temp root — contend on the same lock.
+ */
+/**
+ * The real, symlink-free location of `target`, falling back to the plain
+ * resolution when the path cannot be canonicalized.
+ *
+ * This matters everywhere two spellings of one path must compare equal: a
+ * macOS temp root is `/var/...` to the caller and `/private/var/...` to git, so
+ * a raw `relative()` between the two reads as "outside the repository".
+ */
+function canonicalPath(target) {
+    try {
+        return realpathSync(target);
+    }
+    catch {
+        return resolve(target);
+    }
+}
+export function projectLogLockPath(logPath) {
+    const resolvedDirectory = canonicalPath(dirname(resolve(logPath)));
+    const digest = createHash('sha256')
+        .update(join(resolvedDirectory, basename(logPath)))
+        .digest('hex');
+    return join(tmpdir(), PROJECT_LOG_LOCK_DIRNAME, `${digest}.lock`);
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to another user, which is
+        // still a live owner; only ESRCH proves it is gone.
+        return (error != null &&
+            typeof error === 'object' &&
+            error.code === 'EPERM');
+    }
+}
+function readLockHolder(lockPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, 'utf8'));
+        return parsed != null && typeof parsed === 'object'
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Creates the lock file exclusively and confirms the file still names us.
+ *
+ * `wx` is the primitive: the create either wins or fails with `EEXIST`, in this
+ * process exactly as in any other. The confirming read is what makes a stale
+ * takeover safe. POSIX has no compare-and-unlink, so a contender that judged a
+ * lock abandoned can still remove a *live* lock created in the gap between its
+ * decision and its unlink. When that happens the loser's token is no longer in
+ * the file, so it reports a failed acquire and retries instead of entering the
+ * critical section alongside the winner. Exactly one writer sees its own token.
+ */
+function tryCreateProjectLogLock(lockPath, token) {
+    let descriptor;
+    try {
+        descriptor = openSync(lockPath, 'wx');
+    }
+    catch {
+        return false;
+    }
+    try {
+        writeSync(descriptor, `${JSON.stringify({
+            token,
+            pid: process.pid,
+            host: hostname(),
+            acquiredAt: new Date().toISOString(),
+        })}\n`);
+    }
+    catch {
+        // A lock we cannot identify ourselves in is a lock we must not claim.
+        try {
+            closeSync(descriptor);
+        }
+        catch {
+            // Nothing to recover.
+        }
+        return false;
+    }
+    try {
+        closeSync(descriptor);
+    }
+    catch {
+        // Nothing to recover: the exclusive create already succeeded.
+    }
+    return readLockHolder(lockPath)?.token === token;
+}
+/**
+ * Takes the single-winner right to reclaim an abandoned lock.
+ *
+ * Reclamation is the one operation that removes a file this process did not
+ * create, so it is itself serialized. With the slot held there is no second
+ * reclaimer, and an ordinary acquirer cannot slip in either: its `wx` create
+ * fails for as long as the abandoned lock is still on disk. The lock the
+ * reclaimer unlinks is therefore provably the lock it inspected.
+ *
+ * A slot whose owner died mid-reclamation is itself reclaimed once it is older
+ * than `staleMs`. That fallback is the only place two reclaimers can meet, and
+ * it costs a 30-second stall rather than a lost entry.
+ */
+function acquireReclaimSlot(reclaimPath, staleMs, nowMs) {
+    if (tryCreateReclaimSlot(reclaimPath)) {
+        return true;
+    }
+    const mtime = lockMtimeMs(reclaimPath);
+    if (mtime === undefined) {
+        return tryCreateReclaimSlot(reclaimPath);
+    }
+    if (nowMs - mtime < staleMs) {
+        return false;
+    }
+    try {
+        unlinkSync(reclaimPath);
+    }
+    catch {
+        return false;
+    }
+    return tryCreateReclaimSlot(reclaimPath);
+}
+function tryCreateReclaimSlot(reclaimPath) {
+    try {
+        closeSync(openSync(reclaimPath, 'wx'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether a lock's owner can be shown to be gone.
+ *
+ * A same-host lock whose recorded pid no longer exists was abandoned by a
+ * crashed writer. Anything else — an unreadable body, or a lock recorded by
+ * another host — counts as abandoned only once it is older than `staleMs`, so
+ * a live owner is never evicted on a guess.
+ */
+function lockIsAbandoned(holder, mtimeMs, staleMs, nowMs) {
+    if (holder?.host === hostname() && typeof holder.pid === 'number') {
+        return !isProcessAlive(holder.pid);
+    }
+    return nowMs - mtimeMs >= staleMs;
+}
+/**
+ * Removes a lock whose owner can be shown to be gone.
+ *
+ * This only ever removes *this module's own* advisory lock. It never touches
+ * `.git/index.lock`, which belongs to git and to whichever process took it.
+ *
+ * A same-host lock whose recorded pid no longer exists is abandoned by a
+ * crashed writer and is cleared immediately; anything else — an unreadable
+ * body, or a lock recorded by another host — is cleared only once it is older
+ * than `staleMs`, so a live owner is never evicted on a guess.
+ */
+function clearStaleProjectLogLock(lockPath, staleMs, nowMs) {
+    const mtime = lockMtimeMs(lockPath);
+    if (mtime === undefined) {
+        // Already gone: the next exclusive create is the retry.
+        return true;
+    }
+    if (!lockIsAbandoned(readLockHolder(lockPath), mtime, staleMs, nowMs)) {
+        return false;
+    }
+    const reclaimPath = `${lockPath}.reclaim`;
+    if (!acquireReclaimSlot(reclaimPath, staleMs, nowMs)) {
+        return false;
+    }
+    try {
+        // Re-decided under the slot, against the file as it is now. Nothing can
+        // have replaced it: a competing reclaimer would need this slot, and an
+        // ordinary acquirer cannot create a lock that still exists.
+        const currentMtime = lockMtimeMs(lockPath);
+        if (currentMtime === undefined) {
+            return true;
+        }
+        if (!lockIsAbandoned(readLockHolder(lockPath), currentMtime, staleMs, nowMs)) {
+            return false;
+        }
+        unlinkSync(lockPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            unlinkSync(reclaimPath);
+        }
+        catch {
+            // A slot we cannot remove is reclaimed by the staleness fallback above.
+        }
+    }
+}
+/**
+ * Takes the advisory lock for `logPath`, waiting a bounded time.
+ *
+ * Returns a handle whose `held` is false when the wait elapsed. What that means
+ * is the caller's to decide: see `withProjectLogLock`, where a file-rewriting
+ * mutation refuses and a commit proceeds.
+ */
+async function acquireProjectLogLock(logPath, overrides = {}) {
+    const dependencies = { ...DEFAULT_LOCK_DEPENDENCIES, ...overrides };
+    const lockPath = projectLogLockPath(logPath);
+    const token = randomUUID();
+    try {
+        mkdirSync(dirname(lockPath), { recursive: true });
+    }
+    catch {
+        return { path: lockPath, token, held: false };
+    }
+    const deadline = dependencies.now() + dependencies.waitMs;
+    for (;;) {
+        if (tryCreateProjectLogLock(lockPath, token)) {
+            return { path: lockPath, token, held: true };
+        }
+        if (clearStaleProjectLogLock(lockPath, dependencies.staleMs, dependencies.now()) &&
+            tryCreateProjectLogLock(lockPath, token)) {
+            return { path: lockPath, token, held: true };
+        }
+        if (dependencies.now() >= deadline) {
+            return { path: lockPath, token, held: false };
+        }
+        await dependencies.sleep(dependencies.pollMs);
+    }
+}
+/**
+ * Releases a lock this process still owns. A lock that was stolen as stale now
+ * belongs to its new holder, so the token is checked before the unlink.
+ */
+function releaseProjectLogLock(handle) {
+    if (!handle.held) {
+        return;
+    }
+    const holder = readLockHolder(handle.path);
+    if (holder !== undefined && holder.token !== handle.token) {
+        return;
+    }
+    try {
+        unlinkSync(handle.path);
+    }
+    catch {
+        // Already released or never created; there is nothing to report.
+    }
+}
+/**
+ * Runs `mutate` with the log's advisory lock held, releasing it on every path.
+ *
+ * `required` is for mutations that rewrite the file. Running one of those
+ * without the lock is exactly the read/modify/write race this exists to close,
+ * so an unavailable lock refuses rather than proceeding: a loud, retryable
+ * failure that the caller reports is strictly better than a silent clobber of
+ * another writer's entry, and the recovery command replays the append safely.
+ *
+ * `best-effort` is for work that cannot lose an entry — committing does not
+ * rewrite the log — where holding the lock only keeps this process from racing
+ * its own sibling into `.git/index.lock`.
+ */
+async function withProjectLogLock(logPath, overrides, policy, mutate) {
+    const handle = await acquireProjectLogLock(logPath, overrides);
+    if (!handle.held && policy === 'required') {
+        throw new Error(`Timed out waiting for the project log lock at ${handle.path}. Another writer is holding it; retry once it finishes.`);
+    }
+    try {
+        return await mutate();
+    }
+    finally {
+        releaseProjectLogLock(handle);
+    }
+}
+const DEFAULT_COMMIT_DEPENDENCIES = {
+    attempts: PROJECT_LOG_COMMIT_ATTEMPTS,
+    retryDelaysMs: PROJECT_LOG_COMMIT_RETRY_DELAYS_MS,
+    sleep: async (ms) => {
+        await new Promise((settle) => setTimeout(settle, ms));
+    },
+    lock: {},
+    runGit,
+};
+/**
+ * Outcomes that mean the log entry is committed and a partial-finalization
+ * receipt is no longer needed.
+ */
+const SETTLED_COMMIT_OUTCOMES = new Set([
+    'committed',
+    'already-committed',
+    'nothing-to-commit',
+]);
+/**
+ * Git's own index-lock contention evidence. Deliberately narrow: any stderr
+ * that merely mentions `index.lock` — a hook that prints advice, for instance —
+ * is a real failure, and treating it as contention would retry and then bury it
+ * behind a partial-finalization receipt.
+ *
+ * Git emits its "another git process" advice only alongside the fatal line that
+ * names the lock it could not create, so the advice on its own is not evidence;
+ * it counts only when the same output also names an index lock.
+ */
+const INDEX_LOCK_CREATE_RE = /unable to create '[^']*index\.lock': file exists/i;
+const GIT_CONTENTION_ADVICE_RE = /another git process seems to be running in this repository/i;
+const INDEX_LOCK_MENTION_RE = /index\.lock/i;
+/**
+ * Accepted residual: a hook that reproduces git's advice sentence *and* names
+ * an index lock in the same output is read as contention and retried three
+ * times. That costs one wasted retry window and a misleading `lockClass`, but
+ * it is not a swallowed failure — the exit status stays non-zero, the raw
+ * stderr is preserved in `error`, nothing is left staged, and the gate still
+ * emits `gate-project-log-commit-failed`. Demanding the fatal line for the
+ * advice branch too would reject nothing git actually emits, but it would also
+ * make the branch redundant with the primary regex, so the branch is kept for
+ * git output shapes that lead with the advice.
+ */
+function isIndexLockContention(stderr) {
+    return (INDEX_LOCK_CREATE_RE.test(stderr) ||
+        (GIT_CONTENTION_ADVICE_RE.test(stderr) &&
+            INDEX_LOCK_MENTION_RE.test(stderr)));
+}
+function runGit(repoRoot, args) {
+    return execFileSync('git', args, {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        // Capture stderr rather than inheriting it so skip and failure probes do
+        // not leak raw `git fatal:` lines into command output.
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // Reading the committed log back is one of these calls, and a long-lived
+        // project log outgrows the 1 MiB default.
+        maxBuffer: 64 * 1024 * 1024,
+    }).trim();
+}
+function gitFailureMessage(error) {
+    const stderr = error && typeof error === 'object' && 'stderr' in error
+        ? error.stderr
+        : undefined;
+    return ((stderr != null ? stderr.toString().trim() : '') ||
+        (error instanceof Error ? error.message : String(error)));
+}
+function lockMtimeMs(lockPath) {
+    try {
+        return statSync(lockPath).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveIndexLockPath(repoRoot) {
+    try {
+        return join(runGit(repoRoot, ['rev-parse', '--absolute-git-dir']), 'index.lock');
+    }
+    catch {
+        return join(repoRoot, '.git', 'index.lock');
+    }
+}
+/**
+ * Classifies a failed git invocation as an index-lock contention or a real
+ * failure.
+ *
+ * Only a stderr that actually names `index.lock` is lock contention; every
+ * other failure (hook, signing, identity, pathspec) stays `other` so it is
+ * reported rather than retried and swallowed. A lock is `persistent` only when
+ * its mtime is unchanged across the whole retry window, which is why the
+ * caller passes the mtime it observed on the first lock failure.
+ */
+export function classifyGitLockFailure(stderr, lockPath, firstObservedMtimeMs) {
+    if (!isIndexLockContention(stderr)) {
+        return 'other';
+    }
+    const current = lockMtimeMs(lockPath);
+    if (current === undefined || firstObservedMtimeMs === undefined) {
+        return 'transient-index-lock';
+    }
+    return current === firstObservedMtimeMs
+        ? 'persistent-index-lock'
+        : 'transient-index-lock';
+}
+function readHead(run) {
+    try {
+        return run(['rev-parse', 'HEAD']);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when the log on disk still carries the entry this commit is finalizing.
+ * An absent identity means the caller did not name an entry, so there is
+ * nothing to contradict.
+ */
+function logCarriesIdentity(input) {
+    if (input.identity === undefined) {
+        return true;
+    }
+    try {
+        return (findProjectLogEntryByIdempotencyKey(readFileSync(input.logPath, 'utf8'), input.identity.key, input.identity.body) !== undefined);
+    }
+    catch {
+        // An unreadable log cannot be shown to carry the entry, and this function
+        // never throws: the caller reports the disposition instead.
+        return false;
+    }
+}
+/**
+ * The content of `logPath` as committed at HEAD, or undefined when HEAD does
+ * not have it.
+ *
+ * The working tree is deliberately not consulted. A dirty entry is precisely
+ * the state an exhausted commit retry leaves behind, so a reader that answers
+ * from the working tree cannot tell finished finalization from unfinished
+ * finalization — which is the whole question both callers here are asking.
+ */
+function readCommittedProjectLog(run, logPath) {
+    try {
+        const top = canonicalPath(run(['rev-parse', '--show-toplevel']));
+        const relativePath = relative(top, canonicalPath(logPath))
+            .split(sep)
+            .join('/');
+        if (relativePath === '' || relativePath.startsWith('..')) {
+            return undefined;
+        }
+        return run(['show', `HEAD:${relativePath}`]);
+    }
+    catch {
+        return undefined;
+    }
+}
+function committedIdentityState(run, logPath, key, body) {
+    const committed = readCommittedProjectLog(run, logPath);
+    if (committed === undefined) {
+        return 'unknown';
+    }
+    return findProjectLogEntryByIdempotencyKey(committed, key, body) !== undefined
+        ? 'present'
+        : 'absent';
+}
+/**
+ * Whether the committed log carries `key`.
+ *
+ * Exported for callers that must distinguish finished finalization from
+ * unfinished finalization — the gate's receipt classifier among them — so that
+ * question is answered by this module rather than by a caller opening
+ * `project-log.md` itself (DR-260718).
+ */
+export async function committedProjectLogIdentityState(repoRoot, logPath, key, body) {
+    return committedIdentityState((args) => runGit(repoRoot, args), logPath, key, body);
+}
+/**
+ * The committed-log verdict for the entry this commit names, or `unknown` when
+ * the caller named no entry.
+ */
+function committedInputIdentityState(run, input) {
+    if (input.identity === undefined) {
+        return 'unknown';
+    }
+    return committedIdentityState(run, input.logPath, input.identity.key, input.identity.body);
+}
+/**
+ * True when the entry this commit names survives: present at HEAD, or — when
+ * HEAD cannot answer — still present in the file on disk.
+ *
+ * The working-tree reading is a fallback for `unknown`, never an override of
+ * `absent`: HEAD is the authority whenever it can speak.
+ */
+function identitySurvives(run, input) {
+    const state = committedInputIdentityState(run, input);
+    if (state === 'present') {
+        return true;
+    }
+    if (state === 'absent') {
+        return false;
+    }
+    return logCarriesIdentity(input);
+}
+function entryMissingMessage(input) {
+    return `the committed project log does not carry this entry (${input.identity?.key ?? 'unknown'}); another writer rewrote it`;
+}
+/**
+ * True when another writer already committed the entry we were trying to
+ * commit.
+ *
+ * All three conditions are required. A clean log means the working tree matches
+ * HEAD, a moved HEAD means someone committed, and — when the caller named the
+ * entry's identity — that identity still being in the *committed* log means the
+ * content that landed is the content we appended, not a rewrite that dropped
+ * it.
+ */
+function settledByAnotherWriter(run, snapshot, input) {
+    try {
+        if (run(['status', '--porcelain', '--', input.logPath]).length !== 0) {
+            return false;
+        }
+        if (readHead(run) === snapshot.head) {
+            return false;
+        }
+        return identitySurvives(run, input);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The locked half of `commitProjectLog`: snapshot, bounded retry, and the
+ * committed-identity verification, all with the advisory lock held so this
+ * process never races its own sibling into `.git/index.lock` and never reads a
+ * snapshot another local writer is about to invalidate.
+ */
+async function commitLockedProjectLog(input, dependencies, run, message) {
+    let snapshot;
+    try {
+        snapshot = {
+            head: readHead(run),
+            dirty: run(['status', '--porcelain', '--', input.logPath]).length > 0,
+        };
+    }
+    catch (error) {
+        return {
+            outcome: 'failed',
+            committed: false,
+            attempts: 0,
+            error: gitFailureMessage(error),
+        };
+    }
+    if (!snapshot.dirty) {
+        if (!identitySurvives(run, input)) {
+            // A committed log that no longer carries this entry is a lost entry, not
+            // finished work: reporting it as settled would consume the receipt while
+            // the finalization never happened. The recovery command re-appends it
+            // idempotently and commits.
+            return {
+                outcome: 'entry-missing-after-commit',
+                committed: false,
+                attempts: 0,
+                error: entryMissingMessage(input),
+            };
+        }
+        return { outcome: 'nothing-to-commit', committed: false, attempts: 0 };
+    }
+    const lockPath = resolveIndexLockPath(input.repoRoot);
+    let lockObserved = false;
+    let firstLockMtimeMs;
+    let lastError = '';
+    let attempt = 0;
+    while (attempt < dependencies.attempts) {
+        attempt += 1;
+        let staged = false;
+        try {
+            run(['add', '--', input.logPath]);
+            staged = true;
+            run(['commit', '-m', message, '--', input.logPath]);
+            // A nominally successful commit is not a successful finalization. A
+            // caller that named its entry gets `committed` only when HEAD is read and
+            // positively carries that entry: `absent` means an overlapping writer
+            // clobbered the append before it was staged, and `unknown` means the
+            // verification could not be performed at all. Settling on unread evidence
+            // is what would let both writers succeed with one run id missing, so
+            // neither state settles — both route to the same idempotent recovery.
+            const verified = input.identity === undefined
+                ? 'present'
+                : committedInputIdentityState(run, input);
+            if (verified !== 'present') {
+                return {
+                    outcome: verified === 'absent'
+                        ? 'entry-missing-after-commit'
+                        : 'commit-unverified',
+                    committed: false,
+                    attempts: attempt,
+                    error: verified === 'absent'
+                        ? entryMissingMessage(input)
+                        : `the commit succeeded but the committed project log could not be read back to confirm this entry (${input.identity?.key ?? 'unknown'})`,
+                };
+            }
+            return { outcome: 'committed', committed: true, attempts: attempt };
+        }
+        catch (error) {
+            if (staged) {
+                try {
+                    // A failed commit (hook, signing, identity) would otherwise leave the
+                    // log staged, which is a worse state than the dirty tree we started
+                    // in.
+                    run(['reset', '--quiet', '--', input.logPath]);
+                }
+                catch {
+                    // Best effort: the reported commit failure already tells the caller
+                    // the log needs attention.
+                }
+            }
+            lastError = gitFailureMessage(error);
+            if (classifyGitLockFailure(lastError, lockPath) === 'other') {
+                // A retry can race a competing writer: once it commits our appended
+                // entry and releases the lock, our next `git commit` fails with
+                // "nothing to commit", which is settlement rather than a failure.
+                // Settlement demands a moved HEAD and a clean log that still carries
+                // this entry, so a genuine failure — where the log stays dirty — can
+                // never be reclassified by this branch.
+                if (settledByAnotherWriter(run, snapshot, input)) {
+                    return {
+                        outcome: 'already-committed',
+                        committed: false,
+                        attempts: attempt,
+                    };
+                }
+                return {
+                    outcome: 'failed',
+                    committed: false,
+                    attempts: attempt,
+                    error: lastError,
+                    lockClass: 'other',
+                };
+            }
+            if (!lockObserved) {
+                // Record the first observation even when the lock is already gone: an
+                // absent baseline means the lock changed during the window, which is
+                // contention rather than a stuck lock.
+                lockObserved = true;
+                firstLockMtimeMs = lockMtimeMs(lockPath);
+            }
+            if (attempt < dependencies.attempts) {
+                await dependencies.sleep(dependencies.retryDelaysMs[attempt - 1] ?? 0);
+            }
+        }
+    }
+    if (settledByAnotherWriter(run, snapshot, input)) {
+        return {
+            outcome: 'already-committed',
+            committed: false,
+            attempts: attempt,
+        };
+    }
+    return {
+        outcome: 'blocked-by-index-lock',
+        committed: false,
+        attempts: attempt,
+        error: lastError,
+        lockClass: classifyGitLockFailure(lastError, lockPath, firstLockMtimeMs),
+    };
+}
+/**
+ * Stages and commits `project-log.md`, retrying a bounded number of times when
+ * the failure is a transient `.git/index.lock`.
+ *
+ * The log is tracked, so an uncommitted append leaves the worktree dirty for
+ * whatever runs next — including a dispatched subagent whose preflight requires
+ * a clean tree. The commit is pathspec-scoped to the log alone so unrelated
+ * working-tree changes are never swept in.
+ *
+ * Scope note: this commits the whole log file, so a log that was already dirty
+ * before the caller ran is committed along with this entry. That is deliberate
+ * — leaving the earlier append uncommitted would reproduce the dirty tree this
+ * exists to prevent — but it does mean the commit is not always exactly one
+ * entry.
+ *
+ * Never throws, and never deletes, moves, or forces an index lock: a lock this
+ * process did not take is another process's, and only its owner may clear it.
+ * Git failures are reported to the caller, which degrades to a diagnostic
+ * rather than altering any exit status. On failure the index is restored so a
+ * partially staged log is not left behind.
+ *
+ * Exactly one outcome is derived from a single pre-action snapshot (entry HEAD
+ * plus entry dirtiness) rather than from eligibility re-sampled after the
+ * action, so a log another writer committed mid-retry reads as
+ * `already-committed` instead of a spurious failure.
+ */
+export async function commitProjectLog(input, overrides = {}) {
+    const dependencies = { ...DEFAULT_COMMIT_DEPENDENCIES, ...overrides };
+    const run = (args) => dependencies.runGit(input.repoRoot, args);
+    const message = input.message ?? COMMIT_MESSAGE;
+    try {
+        run(['rev-parse', '--is-inside-work-tree']);
+    }
+    catch {
+        return { outcome: 'not-a-repo', committed: false, attempts: 0 };
+    }
+    return withProjectLogLock(input.logPath, dependencies.lock, 'best-effort', async () => commitLockedProjectLog(input, dependencies, run, message));
+}
+/**
+ * The whole whitespace-delimited word of `body` that carries `key` — for a gate
+ * finalization body that is `run=<runId>`, not the bare run id.
+ *
+ * Matching the whole word rather than the bare key is what keeps
+ * `run=<key>.suffix` from reading as a prior append of `<key>`, and it makes
+ * the recorded identity the same token a reader sees in the log.
+ */
+function idempotencyToken(key, body) {
+    if (body === undefined) {
+        return undefined;
+    }
+    return body.split(/\s+/).find((word) => word.includes(key));
+}
+/**
+ * Returns the heading of the first existing entry whose body already carries
+ * this idempotency identity, or undefined when the log has no such entry.
+ *
+ * With `body` supplied the match is the exact whole-word token derived from it;
+ * without one — the advisory staleness check, which has only a run id — any
+ * word containing `key` counts. Callers that must not duplicate an entry always
+ * pass the body.
+ *
+ * The scan lives here, in the log module, because log reads and mutations are
+ * CLI-owned (DR-260718); callers such as the gate never open `project-log.md`
+ * themselves.
+ */
+export function findProjectLogEntryByIdempotencyKey(content, key, body) {
+    const token = idempotencyToken(key, body);
+    const carries = (line) => line
+        .split(/\s+/)
+        .some((word) => token === undefined ? word.includes(key) : word === token);
+    let heading;
+    for (const line of content.split(/\r?\n/)) {
+        if (isProjectLogEntryMarker(line)) {
+            heading = line.trim();
+            continue;
+        }
+        if (isProjectLogSectionMarker(line)) {
+            heading = undefined;
+            continue;
+        }
+        if (heading !== undefined && carries(line)) {
+            return heading;
+        }
+    }
+    return undefined;
+}
 const DEFAULT_APPEND_DEPENDENCIES = {
     resolveActiveProject,
     resolveEffectiveConfig,
     resolveAssetsRoot,
     now: () => new Date(),
+    readLog: async (path) => readFile(path, 'utf8'),
+    writeLog: async (path, content) => {
+        await writeFile(path, content, 'utf8');
+    },
+    appendLog: async (path, content) => {
+        await appendFile(path, content, 'utf8');
+    },
+    lock: {},
 };
 const DEFAULT_COMMAND_DEPENDENCIES = {
     ...DEFAULT_APPEND_DEPENDENCIES,
@@ -117,6 +907,28 @@ function validateEntry(input, date) {
         versionNote,
     };
 }
+/**
+ * Validates the optional idempotency key and requires it to be present in the
+ * body.
+ *
+ * The dedupe scan recognizes a prior append by finding the key inside an
+ * existing entry body, so a key the body never carries would make every replay
+ * append a fresh duplicate. Rejecting that combination is what keeps
+ * `already-appended` a real guarantee rather than a hope.
+ */
+function validateIdempotencyKey(value, body) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const key = validateSingleLine(value, '--idempotency-key');
+    if (/\s/.test(key)) {
+        throw new Error('--idempotency-key must not contain whitespace.');
+    }
+    if (idempotencyToken(key, body) === undefined) {
+        throw new Error('--idempotency-key must appear in --body so a replayed append can recognize its own entry.');
+    }
+    return key;
+}
 async function resolveTargetProject(input, dependencies) {
     if (input.project) {
         const projectPath = isAbsolute(input.project)
@@ -142,23 +954,44 @@ export function instantiateProjectLogTemplate(template, projectName, date) {
         .replaceAll(/\n?oat_template_name:\s*[^\n]*\n/gi, '\n');
     return instantiated.endsWith('\n') ? instantiated : `${instantiated}\n`;
 }
-async function appendEntry(logPath, heading, body, versionNote) {
+/**
+ * Inserts one entry, before the end-of-run synthesis section when the log has
+ * one.
+ *
+ * The synthesis branch is a read/modify/write, so two overlapping writers would
+ * lose an entry; every caller therefore runs this with the log's advisory lock
+ * held. The plain branch still appends rather than rewriting, which keeps a
+ * writer that could not take the lock strictly additive.
+ */
+async function appendEntry(logPath, heading, body, versionNote, dependencies) {
     const bodyWithVersion = versionNote?.trim()
         ? `${body} (observed on ${versionNote.trim()})`
         : body;
     const entry = `\n${heading}\n\n${bodyWithVersion}\n`;
-    const content = await readFile(logPath, 'utf8');
+    const content = await dependencies.readLog(logPath);
     const synthesisIndex = content.indexOf(SYNTHESIS_HEADING_PREFIX);
     if (synthesisIndex >= 0) {
-        await writeFile(logPath, `${content.slice(0, synthesisIndex)}${entry}${content.slice(synthesisIndex)}`, 'utf8');
+        await dependencies.writeLog(logPath, `${content.slice(0, synthesisIndex)}${entry}${content.slice(synthesisIndex)}`);
         return;
     }
-    await appendFile(logPath, `${content.endsWith('\n') ? '' : '\n'}${entry}`, 'utf8');
+    await dependencies.appendLog(logPath, `${content.endsWith('\n') ? '' : '\n'}${entry}`);
 }
+/**
+ * Appends one entry to the project log, at most once per idempotency key.
+ *
+ * The existence check, the idempotency scan, the template instantiation, and
+ * the write are one critical section under the log's advisory lock. Separating
+ * the scan from the mutation is what let two overlapping writers both pass the
+ * scan and then lose one entry to the other's stale rewrite, so they are not
+ * separable here.
+ */
 export async function appendProjectLog(input, overrides = {}) {
     const dependencies = { ...DEFAULT_APPEND_DEPENDENCIES, ...overrides };
     const projectPath = await resolveTargetProject(input, dependencies);
     const logPath = join(projectPath, PROJECT_LOG_FILENAME);
+    return withProjectLogLock(logPath, dependencies.lock, 'required', async () => appendLockedProjectLog(input, dependencies, logPath));
+}
+async function appendLockedProjectLog(input, dependencies, logPath) {
     const logExists = await fileExists(logPath);
     if (!logExists) {
         const effective = await dependencies.resolveEffectiveConfig(input.repoRoot, join(input.home ?? homedir(), '.oat'));
@@ -168,32 +1001,219 @@ export async function appendProjectLog(input, overrides = {}) {
     }
     const date = dependencies.now().toISOString().slice(0, 10);
     const { heading, body, versionNote } = validateEntry(input, date);
+    const idempotencyKey = validateIdempotencyKey(input.idempotencyKey, body);
     let created = false;
+    if (logExists && idempotencyKey !== undefined) {
+        const existing = findProjectLogEntryByIdempotencyKey(await dependencies.readLog(logPath), idempotencyKey, body);
+        if (existing !== undefined) {
+            // Append-only order is preserved (DR-260714): a replay observes the
+            // entry it already wrote instead of writing a second one.
+            return {
+                status: 'already-appended',
+                logPath,
+                heading: existing,
+                created: false,
+            };
+        }
+    }
     if (!logExists) {
         const assetsRoot = await dependencies.resolveAssetsRoot();
         const template = await readFile(join(assetsRoot, 'templates', PROJECT_LOG_FILENAME), 'utf8');
-        await writeFile(logPath, instantiateProjectLogTemplate(template, basename(projectPath), date), 'utf8');
+        await dependencies.writeLog(logPath, instantiateProjectLogTemplate(template, basename(dirname(logPath)), date));
         created = true;
     }
-    await appendEntry(logPath, heading, body, versionNote);
+    await appendEntry(logPath, heading, body, versionNote, dependencies);
     return { status: 'appended', logPath, heading, created };
 }
+async function samePath(left, right) {
+    if (resolve(left) === resolve(right)) {
+        return true;
+    }
+    try {
+        return (await realpath(left)) === (await realpath(right));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validates a gate partial-finalization receipt against the live tree before
+ * anything is appended or committed.
+ *
+ * Recovery finalizes a log entry; it never re-reads or re-validates the review
+ * verdict, so the check here is identity only: the receipt must describe this
+ * project, in this worktree, for a review artifact whose bytes are unchanged.
+ * Any mismatch refuses and touches nothing.
+ */
+async function validateGateProjectLogReceipt(options) {
+    let receipt;
+    try {
+        receipt = JSON.parse(await readFile(options.receiptPath, 'utf8'));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `receipt is unreadable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (receipt.runId !== options.idempotencyKey) {
+        return {
+            ok: false,
+            reason: `receipt run id ${String(receipt.runId)} does not match --idempotency-key ${options.idempotencyKey}`,
+        };
+    }
+    if (typeof receipt.projectPath !== 'string' ||
+        !(await samePath(receipt.projectPath, options.projectPath))) {
+        return {
+            ok: false,
+            reason: `receipt project ${String(receipt.projectPath)} does not resolve to ${options.projectPath}`,
+        };
+    }
+    let worktreeRoot;
+    try {
+        worktreeRoot = runGit(options.repoRoot, ['rev-parse', '--show-toplevel']);
+    }
+    catch {
+        return { ok: false, reason: 'no git worktree resolves for the project' };
+    }
+    if (typeof receipt.worktreeRoot !== 'string' ||
+        !(await samePath(receipt.worktreeRoot, worktreeRoot))) {
+        return {
+            ok: false,
+            reason: `receipt worktree ${String(receipt.worktreeRoot)} does not match ${worktreeRoot}`,
+        };
+    }
+    if (receipt.artifactPath != null) {
+        if (typeof receipt.artifactSignature !== 'string' ||
+            receipt.artifactSignature.length === 0) {
+            // A receipt that names an artifact always records its signature, so an
+            // unsigned one is malformed rather than merely artifact-free.
+            return {
+                ok: false,
+                reason: `receipt names ${receipt.artifactPath} without an artifact signature`,
+            };
+        }
+        const artifactPath = isAbsolute(receipt.artifactPath)
+            ? receipt.artifactPath
+            : join(worktreeRoot, receipt.artifactPath);
+        let content;
+        try {
+            content = await readFile(artifactPath, 'utf8');
+        }
+        catch {
+            return {
+                ok: false,
+                reason: `review artifact is missing: ${receipt.artifactPath}`,
+            };
+        }
+        const signature = createHash('sha256').update(content).digest('hex');
+        if (signature !== receipt.artifactSignature) {
+            return {
+                ok: false,
+                reason: `review artifact signature changed for ${receipt.artifactPath}`,
+            };
+        }
+    }
+    // The receipt describes exactly one entry. Consuming it while writing some
+    // other entry would finalize the wrong thing and discard the real pending
+    // work, so the replayed entry has to be the entry the receipt names.
+    for (const [label, expected, actual] of [
+        ['--producer', receipt.producer, options.producer],
+        ['--ref', receipt.ref, options.ref],
+        ['--body', receipt.body, options.body],
+    ]) {
+        if (expected !== actual) {
+            return {
+                ok: false,
+                reason: `${label} does not match the receipt entry (expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)})`,
+            };
+        }
+    }
+    return { ok: true, receipt };
+}
+function reportReceiptMismatch(context, receiptPath, reason) {
+    if (context.json) {
+        context.logger.json({
+            status: 'error',
+            type: 'gate-project-log-receipt-mismatch',
+            receiptPath,
+            reason,
+        });
+        return;
+    }
+    context.logger.error(`gate-project-log-receipt-mismatch: ${reason} (${receiptPath}). Nothing was appended or committed.`);
+}
 async function runAppendCommand(options, context, dependencies) {
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const body = options.body === '-' ? await dependencies.readStdin() : options.body;
+        let receiptPath;
+        if (options.commit && options.idempotencyKey) {
+            const projectPath = await resolveTargetProject({ repoRoot, home: context.home, project: options.project }, dependencies);
+            const candidate = join(projectPath, GATE_RECEIPTS_DIRNAME, `${options.idempotencyKey}.json`);
+            if (await fileExists(candidate)) {
+                const validation = await validateGateProjectLogReceipt({
+                    receiptPath: candidate,
+                    repoRoot,
+                    projectPath,
+                    idempotencyKey: options.idempotencyKey,
+                    producer: options.producer,
+                    ref: options.ref,
+                    body,
+                });
+                if (!validation.ok) {
+                    reportReceiptMismatch(context, candidate, validation.reason);
+                    process.exitCode = 1;
+                    return;
+                }
+                receiptPath = candidate;
+            }
+        }
         const result = await appendProjectLog({
             repoRoot,
             home: context.home,
             ...options,
             body,
         }, dependencies);
+        let commit;
+        let receiptRemoved = false;
+        if (options.commit && result.status !== 'skipped') {
+            commit = await commitProjectLog({
+                repoRoot,
+                logPath: result.logPath,
+                ...(options.idempotencyKey !== undefined && body !== undefined
+                    ? { identity: { key: options.idempotencyKey, body } }
+                    : {}),
+            });
+            if (receiptPath !== undefined &&
+                SETTLED_COMMIT_OUTCOMES.has(commit.outcome)) {
+                await rm(receiptPath, { force: true });
+                receiptRemoved = true;
+            }
+        }
+        const settled = commit === undefined || SETTLED_COMMIT_OUTCOMES.has(commit.outcome);
         if (context.json) {
-            context.logger.json(result);
+            context.logger.json({
+                ...result,
+                ...(commit ? { commit } : {}),
+                ...(receiptPath !== undefined
+                    ? { receipt: { path: receiptPath, removed: receiptRemoved } }
+                    : {}),
+            });
         }
         else if (result.status === 'appended') {
             context.logger.success(`Appended project log entry: ${result.logPath}`);
         }
+        else if (result.status === 'already-appended') {
+            context.logger.success(`Project log entry already present for --idempotency-key: ${result.heading}`);
+        }
+        if (!settled) {
+            if (!context.json) {
+                context.logger.error(`Unable to commit the project log (${commit.outcome}${commit.lockClass ? `, ${commit.lockClass}` : ''}): ${commit.error ?? 'no detail'}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
         process.exitCode = 0;
     }
     catch (error) {
@@ -220,6 +1240,8 @@ export function createProjectLogAppendCommand(overrides = {}) {
         .option('--body <text>', 'Entry body, or - to read the body from stdin')
         .option('--version-note <text>', 'Append an observed-on version clause')
         .option('--project <path>', 'Explicit project path; defaults to the active project')
+        .option('--idempotency-key <key>', 'Globally unique key (a run id, not a common word) that must appear in --body; an entry already carrying it is reported as already-appended instead of duplicated')
+        .option('--commit', 'Stage and commit the project log after appending, retrying across a transient index lock')
         .addHelpText('after', `
 Entry contract:
   Log breaks, surprises, workarounds, or notable successes; record evidence, not narrative.
@@ -227,6 +1249,7 @@ Entry contract:
   High-value judgments may use Observation:, Impact:, and Recommendation: fields.
   Structural bodies are one line and reference artifacts by path instead of inlining them.
   Add --version-note for tool-related observations.
+  Pass --idempotency-key with --commit to finalize a gate partial-finalization receipt; a replay reports already-appended instead of duplicating the entry.
   Never record secret values (tokens, keys, signed URLs, or credentials); reference secrets by name or source.
   Prior entries are never edited or struck through. Append a new judgment entry that references and explains a correction.