@open-agent-toolkit/cli 0.2.59 → 0.2.63

package/dist/commands/instructions/instructions.utils.js

@@ -1,5 +1,6 @@
 import { lstat, readdir, readFile, readlink, realpath, stat, } from 'node:fs/promises';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, posix, relative, resolve } from 'node:path';
+import { readOatConfig, resolveDocumentationContentRoot, } from '../../config/oat-config.js';
 export const EXPECTED_CLAUDE_CONTENT = '@AGENTS.md\n';
 export const DEFAULT_INSTRUCTION_SYNC_STRATEGY = 'pointer';
 const ROOT_EXCLUDED_DIRECTORIES = new Set(['.git', '.oat', '.worktrees']);
@@ -87,7 +88,171 @@ function recordInstructionFile(directoryEntries, directoryPath, entryName, entry
     }
     directoryEntries.set(directoryPath, current);
 }
-async function scanInstructionDirectories(repoRoot, dependencies, debug) {
+/**
+ * Canonicalize repo-relative exclusion entries into the exact form the scan
+ * compares against: POSIX separators, collapsed `.` and `..` segments and
+ * duplicate slashes, no trailing slash, de-duplicated, order-preserving.
+ *
+ * Full normalization is what makes the comparison trustworthy. The scan tests
+ * an exclusion against `relative(repoRoot, entryPath)`, which is always
+ * already-normalized, so an un-normalized entry like `apps/./docs` or
+ * `apps//docs` would silently never match and quietly fail open.
+ *
+ * Two classes of entry are dropped rather than normalized:
+ *
+ * - anything resolving to the repository root (`.`, `` , `./`), because
+ *   excluding the root would silence the entire scan — including the
+ *   `.oat/repo` carve-in — from one stray config value; and
+ * - absolute paths and entries escaping the repository (`..`, `../x`), which
+ *   can never name a directory inside the tree being scanned. Dropping them
+ *   keeps a malformed value from masquerading as a matchable exclusion.
+ */
+export function normalizeExcludedPaths(excludedPaths = []) {
+    const normalized = [];
+    for (const candidate of excludedPaths) {
+        const trimmed = toPosixPath(candidate.trim());
+        if (!trimmed || posix.isAbsolute(trimmed)) {
+            continue;
+        }
+        const posixPath = posix.normalize(trimmed).replace(/\/+$/, '');
+        if (!posixPath ||
+            posixPath === '.' ||
+            posixPath === '..' ||
+            posixPath.startsWith('../')) {
+            continue;
+        }
+        if (!normalized.includes(posixPath)) {
+            normalized.push(posixPath);
+        }
+    }
+    return normalized;
+}
+/**
+ * Paths the carve-in queues directly, which therefore never reach the exclusion
+ * predicate and can never be excluded however the config asks. An opt-out
+ * naming one of these is inert and must be reported as such rather than
+ * silently listed as protection.
+ *
+ * Matched exactly, never by prefix: only the carve-in root itself bypasses the
+ * predicate. Its *descendants* are reached by ordinary traversal out of the
+ * queued directory, so `.oat/repo/pjm` is excludable even though `.oat/repo`
+ * is not, and treating it as inert would be a false warning about an exclusion
+ * that really does protect its tree.
+ */
+const UNEXCLUDABLE_PATHS = new Set([...ROOT_EXCLUDED_DIRECTORY_CARVE_INS].map(([directory, carveIn]) => `${directory}/${carveIn}`));
+/**
+ * Whether `relativePath` names a real directory whose on-disk spelling matches
+ * exactly.
+ *
+ * The case check is the point. On a case-insensitive filesystem (APFS, NTFS) a
+ * plain existence test accepts `Apps/Docsapp/docs` for a directory really named
+ * `apps/docsapp/docs`, but the scan compares against `relative(repoRoot, ...)`,
+ * which always yields the true on-disk case. The exclusion would then be
+ * reported as applied while matching nothing — issue #238 recurring silently on
+ * the default developer platform. Resolving through `realpath` and comparing
+ * the result to the requested spelling catches that, and returns false for a
+ * path that does not exist at all.
+ *
+ * `repoRoot` is realpath'd too, so a symlinked checkout (`/tmp` on macOS) does
+ * not make every entry look like a mismatch.
+ */
+async function isCaseExactDirectory(dependencies, repoRoot, relativePath) {
+    try {
+        const realRoot = await dependencies.realpath(repoRoot);
+        const candidate = join(realRoot, relativePath);
+        if (!(await directoryExists(dependencies, candidate))) {
+            return false;
+        }
+        const realCandidate = await dependencies.realpath(candidate);
+        return toPosixPath(relative(realRoot, realCandidate)) === relativePath;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The directories `oat instructions sync` and `oat instructions validate` skip:
+ * the derived documentation content root first, then the explicit
+ * `documentation.instructionPointerExcludes` opt-outs.
+ *
+ * Both commands resolve exclusions through this one function. That is the
+ * property that matters: if they computed exclusions separately, validate
+ * could report drift in a directory sync refuses to touch, and the repository
+ * would have no clean state to reach.
+ *
+ * Every configured entry is classified rather than trusted. An entry that is
+ * dropped during normalization, names an unexcludable carve-in root, or does
+ * not resolve to a real case-exact directory is reported as a warning and kept
+ * out of `effective`, so no caller can mistake a typo for protection.
+ *
+ * `effective` answers "is this tree protected from pointer writes?", not "did
+ * the exclusion predicate fire for it". An entry that names an already-skipped
+ * built-in root (`.git`, `node_modules`) or sits beneath another exclusion is
+ * still effective, because the operator's intent holds; warning about those
+ * would be a false alarm about exclusions that do work.
+ *
+ * Nothing here deletes or rewrites an existing pointer. Excluding a directory
+ * only stops it being reported and written; a `CLAUDE.md` already inside an
+ * excluded tree is left exactly as it is.
+ */
+export async function resolveInstructionPointerExcludes(repoRoot, overrides = {}) {
+    const dependencies = {
+        lstat,
+        realpath,
+        readdir,
+        readFile,
+        readlink,
+        stat,
+        ...overrides,
+    };
+    const config = await readOatConfig(repoRoot);
+    const contentRoot = await resolveDocumentationContentRoot(repoRoot, config, {
+        // Probe through the injected `stat` so a simulated filesystem (tests) and
+        // the real one agree on whether `<root>/docs` exists.
+        dirExists: async (path) => {
+            try {
+                return (await dependencies.stat(path)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+    });
+    const requested = [
+        ...(contentRoot === null
+            ? []
+            : [{ raw: contentRoot, source: 'documentation.root' }]),
+        ...(config.documentation?.instructionPointerExcludes ?? []).map((raw) => ({
+            raw,
+            source: 'documentation.instructionPointerExcludes',
+        })),
+    ];
+    const configured = [];
+    const effective = [];
+    const warnings = [];
+    for (const { raw, source } of requested) {
+        const [normalizedPath] = normalizeExcludedPaths([raw]);
+        if (!normalizedPath) {
+            warnings.push(`Ignoring ${source} entry ${JSON.stringify(raw)}: exclusions must be repository-relative paths inside the repository.`);
+            continue;
+        }
+        if (configured.includes(normalizedPath)) {
+            continue;
+        }
+        configured.push(normalizedPath);
+        if (UNEXCLUDABLE_PATHS.has(normalizedPath)) {
+            warnings.push(`${source} entry ${JSON.stringify(normalizedPath)} has no effect: ${normalizedPath} is always scanned.`);
+            continue;
+        }
+        if (!(await isCaseExactDirectory(dependencies, repoRoot, normalizedPath))) {
+            warnings.push(`${source} entry ${JSON.stringify(normalizedPath)} matches no directory in this repository (matching is case-sensitive), so it excludes nothing.`);
+            continue;
+        }
+        effective.push(normalizedPath);
+    }
+    return { configured, effective, warnings };
+}
+async function scanInstructionDirectories(repoRoot, dependencies, debug, excludedPaths = new Set()) {
     const queue = [repoRoot];
     const directoryEntries = new Map();
     while (queue.length > 0) {
@@ -123,6 +288,19 @@ async function scanInstructionDirectories(repoRoot, dependencies, debug) {
                     }
                     continue;
                 }
+                // Deliberately after the carve-in above, never before it: the carve-in
+                // path is already queued by the time a configured exclusion is tested,
+                // so excluding `.oat` (or any documentation root that happens to
+                // contain one) still leaves `.oat/repo/**` scanned. Skipping the
+                // directory here also skips its whole subtree, because a directory
+                // that is never queued is never read.
+                if (excludedPaths.size > 0) {
+                    const relativePath = toPosixPath(relative(repoRoot, entryPath));
+                    if (excludedPaths.has(relativePath)) {
+                        debug?.(`Skipping excluded directory ${relativePath}`);
+                        continue;
+                    }
+                }
                 queue.push(entryPath);
                 continue;
             }
@@ -181,7 +359,7 @@ export async function scanInstructionFiles(repoRoot, options = {}, overrides = {
         stat,
         ...overrides,
     };
-    const instructionDirectories = await scanInstructionDirectories(repoRoot, dependencies, options.debug);
+    const instructionDirectories = await scanInstructionDirectories(repoRoot, dependencies, options.debug, new Set(normalizeExcludedPaths(options.excludedPaths)));
     const entries = [];
     for (const [directoryPath, directoryEntry] of instructionDirectories) {
         const agentsPath = directoryEntry.agentsPath ?? null;
@@ -402,15 +580,34 @@ function deriveInstructionsStatus(entries, actions) {
     }
     return 'ok';
 }
-export function buildInstructionsPayload({ mode, entries, actions, }) {
+export function buildInstructionsPayload({ mode, entries, actions, excludedPaths, effectiveExcludedPaths, exclusionWarnings, }) {
     const normalizedEntries = normalizeEntries(entries);
     const normalizedActions = normalizeActions(actions);
+    const normalizedExcludedPaths = normalizeExcludedPaths(excludedPaths);
+    const normalizedEffectivePaths = normalizeExcludedPaths(effectiveExcludedPaths);
     return {
         mode,
         status: deriveInstructionsStatus(normalizedEntries, normalizedActions),
         summary: buildInstructionsSummary(normalizedEntries, normalizedActions),
         entries: normalizedEntries,
         actions: normalizedActions,
+        // Both omitted when nothing is configured, so a repository with no
+        // documentation root keeps its existing payload shape exactly. Once
+        // `excludedPaths` is present its effective counterpart always is too, even
+        // when empty: "configured three, protected none" is precisely the state a
+        // consumer must be able to see, and omitting the field would hide it.
+        ...(normalizedExcludedPaths.length > 0
+            ? {
+                excludedPaths: normalizedExcludedPaths,
+                effectiveExcludedPaths: normalizedEffectivePaths,
+            }
+            : {}),
+        // Independent of the two fields above: an entry rejected during
+        // normalization produces a warning but no configured path, and that is
+        // exactly the case a JSON consumer must still be able to see.
+        ...(exclusionWarnings !== undefined && exclusionWarnings.length > 0
+            ? { exclusionWarnings }
+            : {}),
     };
 }
 export function formatInstructionsReport(payload, repoRoot) {

package/dist/commands/instructions/sync/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/sync/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,EAAE,EAAsB,MAAM,kBAAkB,CAAC;AAI3E,OAAO,EAKL,KAAK,mCAAmC,EACzC,MAAM,2CAA2C,CAAC;AAYnD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAQ5C,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAEf;AA+SD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,mCAAmC,CAAM,GAC3D,OAAO,CA6FT"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/sync/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,EAAE,EAAsB,MAAM,kBAAkB,CAAC;AAI3E,OAAO,EAKL,KAAK,mCAAmC,EACzC,MAAM,2CAA2C,CAAC;AAanD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAQ5C,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAEf;AAgTD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,mCAAmC,CAAM,GAC3D,OAAO,CAwGT"}

package/dist/commands/instructions/sync/sync.js

@@ -2,7 +2,7 @@ import { lstat, readFile, rm, symlink, writeFile } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 import { buildCommandContext } from '../../../app/command-context.js';
 import { INSTRUCTION_SYNC_STRATEGIES, } from '../../instructions/instructions.types.js';
-import { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, EXPECTED_CLAUDE_CONTENT, formatInstructionsReport, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
+import { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, EXPECTED_CLAUDE_CONTENT, formatInstructionsReport, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
@@ -16,6 +16,7 @@ function defaultDependencies() {
         lstat,
         readFile,
         removeFile: removeInstructionFile,
+        resolveInstructionPointerExcludes,
         resolveProjectRoot,
         scanInstructionFiles,
         symlinkFile: async (target, path) => {
@@ -249,7 +250,14 @@ export function createInstructionsSyncCommand(overrides = {}) {
         try {
             const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
             const strategy = resolveInstructionSyncStrategy(options.strategy);
+            const exclusions = await dependencies.resolveInstructionPointerExcludes(repoRoot);
+            // Warned before any work: an operator whose opt-out silently matches
+            // nothing must hear about it even when the sync then succeeds.
+            for (const warning of exclusions.warnings) {
+                context.logger.warn(warning);
+            }
             const entries = await dependencies.scanInstructionFiles(repoRoot, {
+                excludedPaths: exclusions.configured,
                 strategy,
             });
             const plannedActions = planSyncActions({
@@ -267,6 +275,9 @@ export function createInstructionsSyncCommand(overrides = {}) {
                     ? entries
                     : getPostSyncEntries(entries, actions, strategy),
                 actions,
+                excludedPaths: exclusions.configured,
+                effectiveExcludedPaths: exclusions.effective,
+                exclusionWarnings: exclusions.warnings,
             });
             if (context.json) {
                 context.logger.json(payload);

package/dist/commands/instructions/validate/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/validate/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,uCAAuC,EAC7C,MAAM,2CAA2C,CAAC;AAWnD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAU5C,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,uCAAuC,CAAM,GAC/D,OAAO,CA2DT"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/validate/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,uCAAuC,EAC7C,MAAM,2CAA2C,CAAC;AAYnD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAW5C,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,uCAAuC,CAAM,GAC/D,OAAO,CAsET"}

package/dist/commands/instructions/validate/validate.js

@@ -1,6 +1,6 @@
 import { buildCommandContext } from '../../../app/command-context.js';
 import { INSTRUCTION_SYNC_STRATEGIES, } from '../../instructions/instructions.types.js';
-import { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, formatInstructionsReport, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
+import { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, formatInstructionsReport, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
@@ -8,6 +8,7 @@ import { Command, Option } from 'commander';
 function defaultDependencies() {
     return {
         buildCommandContext,
+        resolveInstructionPointerExcludes,
         resolveProjectRoot,
         scanInstructionFiles,
     };
@@ -27,13 +28,23 @@ export function createInstructionsValidateCommand(overrides = {}) {
         const strategy = resolveInstructionSyncStrategy(options.strategy);
         try {
             const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+            const exclusions = await dependencies.resolveInstructionPointerExcludes(repoRoot);
+            // Warned before any work: an operator whose opt-out silently matches
+            // nothing must hear about it even when validate then reports `ok`.
+            for (const warning of exclusions.warnings) {
+                context.logger.warn(warning);
+            }
             const entries = await dependencies.scanInstructionFiles(repoRoot, {
+                excludedPaths: exclusions.configured,
                 strategy,
             });
             const payload = buildInstructionsPayload({
                 mode: 'validate',
                 entries,
                 actions: [],
+                excludedPaths: exclusions.configured,
+                effectiveExcludedPaths: exclusions.effective,
+                exclusionWarnings: exclusions.warnings,
             });
             if (context.json) {
                 context.logger.json(payload);

package/dist/commands/project/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/project/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBpC,wBAAgB,oBAAoB,IAAI,OAAO,CAuB9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/project/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,wBAAgB,oBAAoB,IAAI,OAAO,CAwB9C"}

package/dist/commands/project/index.js

@@ -11,6 +11,7 @@ import { createProjectMigrateCommand } from './migrate/index.js';
 import { createProjectNewCommand } from './new/index.js';
 import { createProjectOpenCommand } from './open/index.js';
 import { createProjectPauseCommand } from './pause/index.js';
+import { createProjectPromoteCommand } from './promote/index.js';
 import { createProjectPruneCommand } from './prune/index.js';
 import { createProjectPullCommand } from './pull/index.js';
 import { createProjectPushCommand } from './push/index.js';
@@ -34,6 +35,7 @@ export function createProjectCommand() {
         .addCommand(createProjectNewCommand())
         .addCommand(createProjectOpenCommand())
         .addCommand(createProjectPauseCommand())
+        .addCommand(createProjectPromoteCommand())
         .addCommand(createProjectPruneCommand())
         .addCommand(createProjectPushCommand())
         .addCommand(createProjectPullCommand())

package/dist/commands/project/log/append.d.ts

@@ -2,6 +2,176 @@ import { type CommandContext, type GlobalOptions } from '../../../app/command-co
 import { type ActiveProjectResolution } from '../../../config/oat-config.js';
 import { type ResolvedConfig } from '../../../config/resolve.js';
 import { Command } from 'commander';
+export declare const PROJECT_LOG_FILENAME = "project-log.md";
+/**
+ * Directory, relative to a project, that holds gate partial-finalization
+ * receipts. Ignored by the repository so a receipt never dirties the tree.
+ */
+export declare 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 declare const PROJECT_LOG_COMMIT_ATTEMPTS = 3;
+export declare const PROJECT_LOG_COMMIT_RETRY_DELAYS_MS: readonly number[];
+/**
+ * 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 declare const PROJECT_LOG_LOCK_WAIT_MS = 5000;
+export declare const PROJECT_LOG_LOCK_POLL_MS = 25;
+export declare const PROJECT_LOG_LOCK_STALE_MS = 30000;
+export interface ProjectLogLockDependencies {
+    waitMs: number;
+    pollMs: number;
+    staleMs: number;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+}
+export declare function projectLogLockPath(logPath: string): string;
+export type GitLockFailureClass = 'transient-index-lock' | 'persistent-index-lock' | 'other';
+export type ProjectLogCommitOutcome = 'committed' | 'already-committed' | 'nothing-to-commit' | 'not-a-repo' | 'blocked-by-index-lock' | 'entry-missing-after-commit' | 'commit-unverified' | 'failed';
+export interface ProjectLogCommitResult {
+    outcome: ProjectLogCommitOutcome;
+    committed: boolean;
+    attempts: number;
+    error?: string;
+    lockClass?: GitLockFailureClass;
+}
+export interface CommitProjectLogInput {
+    repoRoot: string;
+    logPath: string;
+    message?: string;
+    /**
+     * Identity of the entry this commit is finalizing: the idempotency key plus
+     * the body it was written in, which together name the exact token to look
+     * for. Supplied so a settled outcome is proven rather than inferred — a clean
+     * log whose content still carries this entry is a log whose HEAD content
+     * carries it too.
+     */
+    identity?: {
+        key: string;
+        body: string;
+    };
+}
+export interface CommitProjectLogDependencies {
+    attempts: number;
+    retryDelaysMs: readonly number[];
+    sleep: (ms: number) => Promise<void>;
+    /**
+     * Advisory-lock overrides. Kept separate from `sleep` above, which is the
+     * index-lock retry delay: the two waits are different bounds and a caller
+     * that observes one must not be told about the other.
+     */
+    lock: Partial<ProjectLogLockDependencies>;
+    /**
+     * Git runner for this path. Injectable so a control can make one command
+     * fail — the committed-log read back is allowed to be unavailable, and what
+     * happens then has to be provable rather than asserted.
+     */
+    runGit: (repoRoot: string, args: string[]) => string;
+}
+/**
+ * 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 declare function classifyGitLockFailure(stderr: string, lockPath: string, firstObservedMtimeMs?: number): GitLockFailureClass;
+/**
+ * Whether the log *as committed at HEAD* carries a given entry identity.
+ *
+ * `unknown` is a first-class answer, and it is never read as `absent`: a
+ * repository with no HEAD, a log that has never been committed, or a git
+ * invocation that fails for an environmental reason all say nothing about the
+ * entry, and turning that silence into "the entry is gone" would manufacture
+ * failures out of missing evidence.
+ */
+export type CommittedLogIdentityState = 'present' | 'absent' | 'unknown';
+/**
+ * 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 declare function committedProjectLogIdentityState(repoRoot: string, logPath: string, key: string, body?: string): Promise<CommittedLogIdentityState>;
+/**
+ * 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 declare function commitProjectLog(input: CommitProjectLogInput, overrides?: Partial<CommitProjectLogDependencies>): Promise<ProjectLogCommitResult>;
+/**
+ * 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 declare function findProjectLogEntryByIdempotencyKey(content: string, key: string, body?: string): string | undefined;
+/**
+ * Durable record of a gate project-log append that was written but could not be
+ * committed. It carries everything the recovery command needs to finish the
+ * finalization from a later process, and enough identity to refuse when the
+ * tree it describes is no longer the tree it is replayed against.
+ */
+export interface GateProjectLogReceipt {
+    runId: string;
+    project: string;
+    projectPath: string;
+    worktreeRoot: string;
+    logPath: string;
+    artifactPath: string | null;
+    artifactSignature: string | null;
+    appendStatus: 'appended' | 'already-appended';
+    commitStatus: ProjectLogCommitOutcome;
+    lockClass: GitLockFailureClass | null;
+    attempts: number;
+    producer: string;
+    ref: string;
+    body: string;
+    recovery: {
+        command: string;
+    };
+}
 export interface AppendProjectLogInput {
     repoRoot: string;
     home?: string;
@@ -14,12 +184,18 @@ export interface AppendProjectLogInput {
     ref?: string;
     body?: string;
     versionNote?: string;
+    idempotencyKey?: string;
 }
 export type ProjectLogAppendResult = {
     status: 'appended';
     logPath: string;
     heading: string;
     created: boolean;
+} | {
+    status: 'already-appended';
+    logPath: string;
+    heading: string;
+    created: false;
 } | {
     status: 'skipped';
     reason: 'projectLog=false';
@@ -29,6 +205,16 @@ export interface AppendProjectLogDependencies {
     resolveEffectiveConfig: (repoRoot: string, userConfigDir: string, env?: NodeJS.ProcessEnv) => Promise<ResolvedConfig>;
     resolveAssetsRoot: () => Promise<string>;
     now: () => Date;
+    /**
+     * The log's own read/modify/write primitives. Injectable so a test can hold
+     * one writer inside the window while another enters it, which is the only way
+     * to prove the serialization rather than assert it.
+     */
+    readLog: (path: string) => Promise<string>;
+    writeLog: (path: string, content: string) => Promise<void>;
+    appendLog: (path: string, content: string) => Promise<void>;
+    /** Advisory-lock overrides for the append window. */
+    lock: Partial<ProjectLogLockDependencies>;
 }
 export interface ProjectLogAppendCommandDependencies extends AppendProjectLogDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
@@ -36,6 +222,15 @@ export interface ProjectLogAppendCommandDependencies extends AppendProjectLogDep
     readStdin: () => Promise<string>;
 }
 export declare function instantiateProjectLogTemplate(template: string, projectName: string, date: string): string;
+/**
+ * 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 declare function appendProjectLog(input: AppendProjectLogInput, overrides?: Partial<AppendProjectLogDependencies>): Promise<ProjectLogAppendResult>;
 export declare function createProjectLogAppendCommand(overrides?: Partial<ProjectLogAppendCommandDependencies>): Command;
 //# sourceMappingURL=append.d.ts.map

package/dist/commands/project/log/append.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"append.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/log/append.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAI9E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAC9B;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;CAC5B,CAAC;AAEN,MAAM,WAAW,4BAA4B;IAC3C,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7E,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,KACpB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAqBD,MAAM,WAAW,mCAAoC,SAAQ,4BAA4B;IACvF,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC;AA4LD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,MAAM,CAOR;AAiCD,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,qBAAqB,EAC5B,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,sBAAsB,CAAC,CAoCjC;AAsCD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,mCAAmC,CAAM,GAC3D,OAAO,CA8CT"}
+{"version":3,"file":"append.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/log/append.ts"],"names":[],"mappings":"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"}