akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/commands/improve/improve.js

@@ -14,7 +14,8 @@ import { resolveMutationTarget } from "../../core/mutation-target.js";
 import { getDbPath, getStateDbPathInDataDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { openStateDatabase } from "../../core/state-db.js";
-import { info, warn } from "../../core/warn.js";
+import { info, warn, warnVerbose } from "../../core/warn.js";
+import { beginWriteProvenance, relativeWrittenPath } from "../../core/write-provenance.js";
 import { resolveWritable, resolveWriteTarget } from "../../core/write-source.js";
 import { ensureIndex } from "../../indexer/ensure-index.js";
 import { akmIndex } from "../../indexer/indexer.js";
@@ -84,12 +85,38 @@ export function armBudgetWatchdog(budgetMs, controller, deps) {
         }
     };
 }
+/**
+ * The run's write-provenance journal lifecycle as one named unit (#652).
+ *
+ * The journal is opened once the run owns its lock — so it spans exactly the
+ * window in which this run, and only this run, is allowed to write — and closed
+ * on every exit path including the crash-safety commit. Keeping the mutable
+ * handle behind this factory rather than as a bare `let` in {@link akmImprove}
+ * is also what keeps that function under the R31 size gate
+ * (`tests/architecture/improve-fn-size-ratchet.test.ts`, absolute 220-line bar
+ * with an empty baseline): lifecycle state belongs in a named unit, not in the
+ * orchestrator's preamble.
+ */
+function createRunWriteJournal() {
+    let journal;
+    return {
+        open: () => {
+            journal = beginWriteProvenance();
+        },
+        close: () => {
+            journal?.end();
+            journal = undefined;
+        },
+        current: () => journal,
+    };
+}
 export async function akmImprove(options = {}) {
     const setup = resolveImproveRunSetup(options);
     options = setup.options;
     const { budgetMs, budgetAbortController, scope, selectedStrategy, syncRepoDir, resolvedStateDbPath, resolvedLockPath, lockStaleAfterMs, } = setup;
     let clearBudgetTimer = () => { };
     let initialGitPaths = new Set();
+    const runJournal = createRunWriteJournal();
     const preEnsureCleanupWarnings = [];
     // Assigned by runIndexAndCollect() (closure) so TS cannot prove definite
     // assignment — seed with empty values; the runIndexAndCollect() call below
@@ -126,6 +153,7 @@ export async function akmImprove(options = {}) {
     const commitStashBatch = makeCommitStashBatch({
         run: setup,
         getInitialGitPaths: () => initialGitPaths,
+        getWriteJournal: () => runJournal.current(),
         // Captured via getter: the live `eventsCtx` binding is reassigned after the
         // prepass, and the catch-path sync must write through the current context.
         getEventsCtx: () => eventsCtx,
@@ -150,6 +178,9 @@ export async function akmImprove(options = {}) {
             process.on("exit", exitBackstop);
             initialGitPaths =
                 syncRepoDir && isGitBackedStash(syncRepoDir) ? new Set(listGitChangedPaths(syncRepoDir)) : new Set();
+            // #652: open AFTER the lock, so the journal covers exactly the window in
+            // which this run — and only this run — is allowed to write.
+            runJournal.open();
             // Drain the standing proposal backlog before indexing so fresh proposal
             // generation sees promotions from this same serialized run.
             triageDrain = await runTriagePrePass(setup);
@@ -180,6 +211,7 @@ export async function akmImprove(options = {}) {
             exitBackstop = undefined;
         }
         releaseRunLock();
+        runJournal.close();
         throw err;
     }
     try {
@@ -230,6 +262,13 @@ export async function akmImprove(options = {}) {
         // the only commit; for a multi-cycle run the earlier cycles were banked by
         // the inter-cycle calls and this records the last batch). `result` carries
         // the full `{accepted}`/`{refs}`/`{triage_*}` token data for the message.
+        //
+        // #652: surface the run's write provenance on the envelope BEFORE the sync
+        // (the sync itself writes no assets), so `result.writtenPaths` describes
+        // exactly the set the commit below was scoped to.
+        const writtenPaths = describeRunWrittenPaths(setup, runJournal.current()?.writtenPaths() ?? []);
+        if (writtenPaths.length > 0)
+            result.writtenPaths = writtenPaths;
         result.sync = commitStashBatch(result);
         return result;
     }
@@ -261,6 +300,10 @@ export async function akmImprove(options = {}) {
             exitBackstop = undefined;
         }
         releaseRunLock();
+        // #652: close the write-provenance journal LAST among the write-facing
+        // teardown steps — the catch path's crash-safety commit above still needs
+        // it open to know what this run wrote.
+        runJournal.close();
         // I1: close the long-lived state.db connection opened at the top of the run.
         try {
             eventsDb?.close();
@@ -270,6 +313,22 @@ export async function akmImprove(options = {}) {
         }
     }
 }
+/**
+ * Shape the run's journaled absolute paths for `result.writtenPaths` (#652):
+ * POSIX-relative to the run's primary stash dir (the repo root for a git-backed
+ * stash) when the write landed inside it, absolute otherwise — a run writing to
+ * a `--target` bundle outside the stash still reports what it wrote. Deduped and
+ * sorted so the field is stable across runs.
+ */
+function describeRunWrittenPaths(setup, writtenPaths) {
+    const root = setup.primaryStashDir ?? setup.syncRepoDir;
+    const described = new Set();
+    for (const absolutePath of writtenPaths) {
+        const relative = root ? relativeWrittenPath(root, absolutePath) : undefined;
+        described.add(relative ?? absolutePath.replaceAll(path.sep, "/"));
+    }
+    return [...described].sort();
+}
 /** Resolve a dry-run inspection source without adapting it into a write target. */
 function resolveImproveReadSource(config, scopedRef, explicitTarget, fallbackStashDir) {
     if (scopedRef?.origin && explicitTarget && scopedRef.origin !== explicitTarget) {
@@ -659,19 +718,67 @@ async function runTriagePrePass(run) {
     }
     return triageDrain;
 }
+/** A path is never staged by auto-sync when it is (or looks like) a lock file. */
+function isSyncExcludedPath(relativePath) {
+    return path.basename(relativePath).includes(".lock");
+}
+/**
+ * Resolve the EXACT repo-relative path set the auto-sync commit stages (#652).
+ *
+ * Precedence:
+ *
+ *   1. **Run-scoped write provenance** (`writtenPaths`, absolute) — the paths
+ *      this run actually wrote, created, or removed, intersected with the paths
+ *      Git currently reports as changed. The intersection is what makes the set
+ *      correct rather than merely plausible: it drops a journaled path whose
+ *      final bytes match HEAD (nothing to commit), a journaled path that was
+ *      created and then removed again (never existed for Git), and any journaled
+ *      path Git ignores (which `saveGitStash` would otherwise reject outright).
+ *      A journaled path that was ALREADY dirty when the run started stays IN —
+ *      this run rewrote it, so this run owns it.
+ *   2. **Dirty-path diff** (pre-#652 behaviour) — only when no journal was open,
+ *      which a live run never hits. Kept as the defensive fallback so a future
+ *      caller that commits outside the journal window degrades to the previous,
+ *      battle-tested heuristic instead of silently committing nothing.
+ *
+ * `unattributed` counts in-scope paths that became dirty DURING the run without
+ * this run writing them: concurrent human edits (correctly excluded) and, if the
+ * number is ever surprising, the fingerprint of a missing journal call site.
+ */
+export function resolveSyncPathSet(input) {
+    const { repoDir, assetPrefix, changedPaths, initialPaths, writtenPaths, provenance } = input;
+    const inScope = (relativePath) => !isSyncExcludedPath(relativePath) &&
+        (!assetPrefix || relativePath === assetPrefix || relativePath.startsWith(`${assetPrefix}/`));
+    if (!provenance) {
+        return { paths: changedPaths.filter((p) => !initialPaths.has(p) && inScope(p)), unattributed: [] };
+    }
+    const changed = new Set(changedPaths);
+    const attributed = new Set();
+    for (const absolutePath of writtenPaths) {
+        const relativePath = relativeWrittenPath(repoDir, absolutePath);
+        if (!relativePath || !changed.has(relativePath) || !inScope(relativePath))
+            continue;
+        attributed.add(relativePath);
+    }
+    return {
+        paths: [...attributed].sort(),
+        unattributed: changedPaths.filter((p) => !attributed.has(p) && !initialPaths.has(p) && inScope(p)).sort(),
+    };
+}
 /**
  * Crash-safe / incremental stash sync (#662) — see the factory-returned
  * closure's original doc block: the primary stash writes as a filesystem
  * source DURING the run; this commits them at end-of-run AND from the catch
- * path. Idempotent + NON-FATAL. `getEventsCtx`/`getInitialGitPaths` are
- * getters because both outer bindings are (re)assigned after this factory
- * runs — the returned closure must observe the live values.
+ * path. Idempotent + NON-FATAL. `getEventsCtx`/`getInitialGitPaths`/
+ * `getWriteJournal` are getters because those outer bindings are (re)assigned
+ * after this factory runs — the returned closure must observe the live values.
  */
 function makeCommitStashBatch(deps) {
     const { writeTarget, primaryStashDir, effectiveSync, options, _earlyConfig, improveProfile } = deps.run;
     return (messageContext) => {
         const eventsCtx = deps.getEventsCtx();
         const initialGitPaths = deps.getInitialGitPaths();
+        const writeJournal = deps.getWriteJournal();
         const repoDir = writeTarget?.source.repoPath ?? primaryStashDir;
         if (!primaryStashDir || !repoDir || effectiveSync.enabled === false || !isGitBackedStash(repoDir)) {
             return undefined;
@@ -683,13 +790,17 @@ function makeCommitStashBatch(deps) {
         try {
             const assetRoot = writeTarget?.source.path ?? primaryStashDir;
             const assetPrefix = assetRoot ? path.relative(repoDir, assetRoot).replaceAll(path.sep, "/") : "";
-            const paths = listGitChangedPaths(repoDir).filter((changedPath) => {
-                if (initialGitPaths.has(changedPath))
-                    return false;
-                if (path.basename(changedPath).includes(".lock"))
-                    return false;
-                return !assetPrefix || changedPath === assetPrefix || changedPath.startsWith(`${assetPrefix}/`);
+            const { paths, unattributed } = resolveSyncPathSet({
+                repoDir,
+                assetPrefix,
+                changedPaths: listGitChangedPaths(repoDir),
+                initialPaths: initialGitPaths,
+                writtenPaths: writeJournal?.writtenPaths() ?? [],
+                provenance: writeJournal !== undefined,
             });
+            if (unattributed.length > 0) {
+                warnVerbose(`[improve] auto-sync left ${unattributed.length} path(s) uncommitted — not written by this run: ${unattributed.join(", ")}`);
+            }
             const syncResult = saveGitStashFn(undefined, message, writableOverride, {
                 push,
                 repoDir,
@@ -702,6 +813,11 @@ function makeCommitStashBatch(deps) {
                     pushed: syncResult.pushed,
                     skipped: syncResult.skipped,
                     reason: syncResult.reason ?? null,
+                    // #652 provenance audit trail: how many paths this run staged, and
+                    // how many in-scope paths went dirty during the run that it did NOT
+                    // write (concurrent edits — deliberately left for their author).
+                    attributed: paths.length,
+                    unattributed: unattributed.length,
                 },
             }, eventsCtx);
             return {

package/dist/commands/improve/locks.js

@@ -7,6 +7,7 @@ import { ConfigError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../../core/file-lock.js";
 import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../../core/maintenance-barrier.js";
+import { describeInaccessiblePath } from "../../core/path-access.js";
 import { warn } from "../../core/warn.js";
 export const MIN_IMPROVE_LOCK_STALE_MS = 4 * 60 * 60 * 1000;
 export function improveLockPath(lockBaseDir) {
@@ -56,6 +57,12 @@ function tryAcquireImproveLockUnlocked(lockPath, staleAfterMs, skipIfLocked, onR
         }
         // Re-grabbed by another racer in the window — fall through and treat as held.
     }
+    // A lock we cannot READ is a hard stop, never a reclaim candidate (#791): the
+    // holder may be alive and working, and we simply lack permission to see it.
+    // Stealing the lease here would let two improve runs mutate the same bundle.
+    if (probe.state === "inaccessible") {
+        throw new ConfigError(`improve lock exists but is not readable: ${describeInaccessiblePath(lockPath, probe.code)}.`, "DATA_DIR_UNREADABLE");
+    }
     const rawContent = probe.state === "absent" ? undefined : probe.rawContent;
     const lock = rawContent
         ? (() => {

package/dist/commands/improve/memory/memory-improve.js

@@ -8,6 +8,7 @@ import { mutateFrontmatter, parseFrontmatter } from "../../../core/asset/frontma
 import { conceptIdFromTypeName } from "../../../core/asset/resolve-ref.js";
 import { asNonEmptyString, groupBy, stringArray } from "../../../core/common.js";
 import { DERIVED_SUFFIX } from "../../../core/recognition-util.js";
+import { recordWrittenPath } from "../../../core/write-provenance.js";
 import { isDerivedMemory, memoryIdentityRef, parseMemoryName, resolveParentRef } from "./derived-ref.js";
 export function analyzeMemoryCleanup(stashDir, options = {}) {
     const records = collectDerivedMemories(stashDir, options.parentRef);
@@ -200,6 +201,8 @@ export function applyMemoryCleanup(stashDir, plan) {
                 continue; // no change
             const newContent = assembleAsset(fm.data, resolvedBody);
             fs.writeFileSync(candidate.filePath, newContent, "utf8");
+            // #652: relative-date resolution rewrites the asset in place.
+            recordWrittenPath(candidate.filePath);
             relativeDatesResolved++;
         }
         catch (error) {
@@ -463,6 +466,10 @@ function archiveCleanupCandidate(stashDir, candidate, filePath) {
     const archivedPath = path.join(archiveDir, originalPath);
     fs.mkdirSync(path.dirname(archivedPath), { recursive: true });
     fs.renameSync(filePath, archivedPath);
+    // #652: an archive is a delete + a create. BOTH ends are journaled so the
+    // sync stages the removal of the original alongside the archived copy.
+    recordWrittenPath(filePath);
+    recordWrittenPath(archivedPath);
     const archiveRef = path.relative(stashDir, archivedPath).replace(/\\/g, "/");
     const auditPath = path.join(archiveDir, "cleanup.md");
     const auditRef = path.relative(stashDir, auditPath).replace(/\\/g, "/");
@@ -480,6 +487,7 @@ function archiveCleanupCandidate(stashDir, candidate, filePath) {
         archivedPath: archiveRef,
     }, "Archived derived memory for recoverable cleanup.\n");
     fs.writeFileSync(auditPath, auditAsset, "utf8");
+    recordWrittenPath(auditPath);
     return {
         ref: candidate.ref,
         parentRef: candidate.parentRef,
@@ -535,6 +543,7 @@ function appendBeliefStateTransitionLog(stashDir, transitions) {
     }))
         .join("\n");
     fs.appendFileSync(logPath, `${lines}\n`, "utf8");
+    recordWrittenPath(logPath);
     return logPath;
 }
 function priorBeliefStateForArchive(candidate) {

package/dist/commands/improve/run-context.js

@@ -41,6 +41,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "../../core/common.js";
+import { recordWrittenPath } from "../../core/write-provenance.js";
 import { chatCompletion } from "../../llm/client.js";
 /**
  * Build a `RunContext` over the given carriers with the supplied memo (or `null`
@@ -73,6 +74,10 @@ function buildRunContext(carriers, memo) {
         },
         writeAsset(filePath, content) {
             carriers.writeFile(filePath, content);
+            // #652: journal the write for the run's write-provenance set. Recorded
+            // here (not in the default `writeFile` carrier) so an injected IO seam is
+            // attributed identically to a real `fs` write.
+            recordWrittenPath(filePath);
             memo?.set(memoKey(filePath), content);
         },
         noteAssetWrite(filePath) {

package/dist/commands/improve/session-asset.js

@@ -26,6 +26,7 @@ import path from "node:path";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
+import { recordWrittenPath } from "../../core/write-provenance.js";
 import { normalizeHarnessId } from "../../integrations/harnesses/index.js";
 /**
  * JSON Schema for the session-summary LLM call. Strict so providers that
@@ -240,6 +241,9 @@ export async function writeSessionAsset(data, stashDir, generate) {
     const filePath = resolveSessionAssetPath(stashDir, harness, sessionId);
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, content, "utf8");
+    // #652: extract's session asset is written outside the proposal queue —
+    // journal it so the run's auto-sync stages it as one of its own writes.
+    recordWrittenPath(filePath);
     return {
         written: true,
         filePath,

package/dist/commands/lint/base-linter.js

@@ -448,11 +448,17 @@ function parseInnerFrontmatterBlock(body) {
  * File mutations triggered by the fixable base checks (`unquoted-colon`,
  * `missing-updated`) are flushed to disk here when `ctx.fix` is set, and
  * `ctx.raw` is updated in place so a caller can re-parse the post-fix content.
+ * A failed flush (read-only file, full disk) DOWNGRADES the optimistic
+ * `fixed: true` findings this call made to `fixed: "failed"` rather than
+ * throwing — an uncaught throw here used to kill the whole sweep and hide
+ * which earlier files had already been rewritten (issue #761).
  */
 export function runBaseChecks(ctx) {
     const issues = [];
     let currentRaw = ctx.raw;
     let modified = false;
+    /** Findings whose `fixed: true` is only true once the flush below succeeds. */
+    const pendingFixes = [];
     // M8: Parse lint_skip from frontmatter for per-file rule suppression.
     // Accept both an array (`lint_skip: [missing-ref, stale-path]`) and a
     // single scalar (`lint_skip: missing-ref`). Non-string entries are coerced
@@ -469,12 +475,14 @@ export function runBaseChecks(ctx) {
             if (ctx.fix) {
                 currentRaw = fixUnquotedColon(currentRaw);
                 modified = true;
-                issues.push({
+                const issue = {
                     file: ctx.relPath,
                     issue: "unquoted-colon",
                     detail: unquotedColonDetail,
                     fixed: true,
-                });
+                };
+                issues.push(issue);
+                pendingFixes.push(issue);
             }
             else {
                 issues.push({
@@ -498,12 +506,14 @@ export function runBaseChecks(ctx) {
             }
             currentRaw = fixMissingUpdated(currentRaw, mtime);
             modified = true;
-            issues.push({
+            const issue = {
                 file: ctx.relPath,
                 issue: "missing-updated",
                 detail: `stamped updated: ${localDateStamp(mtime)}`,
                 fixed: true,
-            });
+            };
+            issues.push(issue);
+            pendingFixes.push(issue);
         }
         else {
             issues.push({
@@ -515,9 +525,23 @@ export function runBaseChecks(ctx) {
         }
     }
     if (modified) {
-        fs.writeFileSync(ctx.filePath, currentRaw, "utf8");
-        // Propagate the mutated raw back so subclasses can re-parse if needed
-        ctx.raw = currentRaw;
+        // Mirrors the two stub-delete call sites in `commands/lint/index.ts`
+        // (`appendMemoryStubIssue`/`appendWorkflowStubIssue`), which already report
+        // a failed mutation as `fixed: "failed"` instead of throwing. Without this
+        // the sweep aborted mid-run on the first unwritable file and the caller got
+        // an exception instead of a result naming the fixes that HAD landed.
+        try {
+            fs.writeFileSync(ctx.filePath, currentRaw, "utf8");
+            // Propagate the mutated raw back so subclasses can re-parse if needed
+            ctx.raw = currentRaw;
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            for (const issue of pendingFixes) {
+                issue.fixed = "failed";
+                issue.detail = `${issue.detail} — could not write fix: ${reason}`;
+            }
+        }
     }
     // ── 3. stale-path ──────────────────────────────────────────────────────
     // M3: checkStalePath returns all stale matches; push one issue per path.