cclaw-cli 0.48.16 → 0.48.18

package/dist/content/node-hooks.js

@@ -53,19 +53,173 @@ function safeParseJson(raw, fallback = {}) {
   }
 }
 
-async function readJsonFile(filePath, fallback = {}) {
+// === atomic/locked state I/O =========================================
+//
+// The generated hook script runs OUTSIDE the cclaw CLI process, so it
+// cannot import \`fs-utils.ts\`. These helpers mirror \`writeFileSafe\` and
+// \`withDirectoryLock\` just enough to keep hook-owned state files
+// atomic and free of interleaved concurrent writes.
+
+function hookSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function withDirectoryLockInline(lockPath, fn, options = {}) {
+  const retries = Number.isFinite(options.retries) ? options.retries : 200;
+  const retryDelayMs = Number.isFinite(options.retryDelayMs) ? options.retryDelayMs : 20;
+  const staleAfterMs = Number.isFinite(options.staleAfterMs) ? options.staleAfterMs : 60000;
+  try {
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+  } catch {
+    // parent may already exist
+  }
+  let acquired = false;
+  let lastError = null;
+  for (let attempt = 0; attempt < retries; attempt += 1) {
+    try {
+      await fs.mkdir(lockPath);
+      acquired = true;
+      break;
+    } catch (error) {
+      lastError = error;
+      const code = error && typeof error === "object" && "code" in error ? error.code : null;
+      if (code !== "EEXIST") {
+        throw error;
+      }
+      try {
+        const stat = await fs.stat(lockPath);
+        if (Date.now() - stat.mtimeMs > staleAfterMs) {
+          await fs.rm(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        // lock vanished between retries
+      }
+      await hookSleep(retryDelayMs);
+    }
+  }
+  if (!acquired) {
+    const details = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new Error(
+      "cclaw hook: failed to acquire lock " + lockPath + " (attempts=" + retries + ", lastError=" + details + ")"
+    );
+  }
+  try {
+    return await fn();
+  } finally {
+    await fs.rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+async function writeFileAtomic(filePath, content, options = {}) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = path.join(
+    path.dirname(filePath),
+    "." + path.basename(filePath) + ".tmp-" + process.pid + "-" + Date.now() + "-" + Math.random().toString(36).slice(2, 8)
+  );
+  await fs.writeFile(tempPath, content, { encoding: "utf8" });
+  // Windows' fs.rename can fail transiently with EPERM/EBUSY/EACCES when the
+  // destination file is held open by another process (antivirus, indexer,
+  // or a sibling hook invocation racing on the same file). Retry with tiny
+  // backoff before falling back to copyFile.
+  const renameRetryableCodes = new Set(["EPERM", "EBUSY", "EACCES"]);
+  let attempt = 0;
+  const maxAttempts = 6;
+  while (true) {
+    try {
+      await fs.rename(tempPath, filePath);
+      if (options.mode !== undefined) {
+        await fs.chmod(filePath, options.mode).catch(() => undefined);
+      }
+      return;
+    } catch (error) {
+      const code = error && typeof error === "object" && "code" in error ? error.code : null;
+      if (code === "EXDEV") {
+        try {
+          await fs.copyFile(tempPath, filePath);
+        } finally {
+          await fs.unlink(tempPath).catch(() => undefined);
+        }
+        if (options.mode !== undefined) {
+          await fs.chmod(filePath, options.mode).catch(() => undefined);
+        }
+        return;
+      }
+      if (renameRetryableCodes.has(code) && attempt < maxAttempts) {
+        attempt += 1;
+        await hookSleep(10 * attempt + Math.floor(Math.random() * 10));
+        continue;
+      }
+      if (renameRetryableCodes.has(code)) {
+        // Last-resort fallback: copy-then-unlink. Not atomic, but the
+        // directory lock around this call already serializes writers.
+        try {
+          await fs.copyFile(tempPath, filePath);
+          if (options.mode !== undefined) {
+            await fs.chmod(filePath, options.mode).catch(() => undefined);
+          }
+          return;
+        } finally {
+          await fs.unlink(tempPath).catch(() => undefined);
+        }
+      }
+      await fs.unlink(tempPath).catch(() => undefined);
+      throw error;
+    }
+  }
+}
+
+function lockPathFor(filePath) {
+  return filePath + ".lock";
+}
+
+async function recordHookError(root, stage, detail) {
+  try {
+    const errorsPath = path.join(root, RUNTIME_ROOT, "state", "hook-errors.jsonl");
+    await fs.mkdir(path.dirname(errorsPath), { recursive: true });
+    const payload = JSON.stringify({
+      ts: new Date().toISOString(),
+      stage: typeof stage === "string" ? stage : "unknown",
+      detail: typeof detail === "string" ? detail : String(detail)
+    });
+    await fs.appendFile(errorsPath, payload + "\\n", "utf8");
+  } catch {
+    // diagnostics must never cascade
+  }
+}
+
+async function readJsonFile(filePath, fallback = {}, options = {}) {
   try {
     const raw = await fs.readFile(filePath, "utf8");
-    return safeParseJson(raw, fallback);
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+      return fallback;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed === undefined ? fallback : parsed;
+    } catch (parseErr) {
+      // Emit a diagnostic breadcrumb instead of silently returning fallback.
+      // The hook must still continue (soft-fail), but the corruption is
+      // now visible in \`state/hook-errors.jsonl\` and to \`cclaw doctor\`.
+      if (options.root) {
+        await recordHookError(
+          options.root,
+          options.stage || "read-json",
+          "corrupt-json file=" + filePath + " error=" + (parseErr instanceof Error ? parseErr.message : String(parseErr))
+        );
+      }
+      return fallback;
+    }
   } catch {
     return fallback;
   }
 }
 
 async function writeJsonFile(filePath, value) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
   const next = JSON.stringify(value, null, 2) + "\\n";
-  await fs.writeFile(filePath, next, "utf8");
+  await withDirectoryLockInline(lockPathFor(filePath), async () => {
+    await writeFileAtomic(filePath, next);
+  });
 }
 
 async function fileExists(filePath) {
@@ -86,8 +240,17 @@ async function readTextFile(filePath, fallback = "") {
 }
 
 async function appendJsonLine(filePath, value) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.appendFile(filePath, JSON.stringify(value) + "\\n", "utf8");
+  const payload = JSON.stringify(value) + "\\n";
+  await withDirectoryLockInline(lockPathFor(filePath), async () => {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, payload, "utf8");
+  });
+}
+
+async function writeTextFileAtomic(filePath, content) {
+  await withDirectoryLockInline(lockPathFor(filePath), async () => {
+    await writeFileAtomic(filePath, content);
+  });
 }
 
 async function readStdin() {
@@ -532,7 +695,10 @@ function extractCodePathsFromText(value) {
 
 async function readFlowState(root) {
   const statePath = path.join(root, RUNTIME_ROOT, "state", "flow-state.json");
-  const parsed = await readJsonFile(statePath, {});
+  // Loud-on-corrupt: if flow-state.json exists but fails JSON.parse, log
+  // a breadcrumb into state/hook-errors.jsonl before falling back to an
+  // empty object. Silent fallbacks used to mask stale CLI+hook drift.
+  const parsed = await readJsonFile(statePath, {}, { root, stage: "read-flow-state" });
   const obj = toObject(parsed) || {};
   const completed = Array.isArray(obj.completedStages) ? obj.completedStages : [];
   return {
@@ -602,11 +768,9 @@ async function buildKnowledgeDigest(root, currentStage) {
     });
   const body =
     relevant.length > 0 ? relevant.join("\\n") : "(no matching entries for current stage)";
-  await fs.mkdir(path.dirname(digestFile), { recursive: true });
-  await fs.writeFile(
+  await writeTextFileAtomic(
     digestFile,
-    "# Knowledge digest (auto-generated)\\n\\n" + body + "\\n",
-    "utf8"
+    "# Knowledge digest (auto-generated)\\n\\n" + body + "\\n"
   );
   return {
     digestLines: relevant,
@@ -1069,8 +1233,7 @@ async function handlePreCompact(runtime) {
     digest.push("", "## Knowledge tail", knowledgeTail);
   }
   const digestFile = path.join(stateDir, "session-digest.md");
-  await fs.mkdir(path.dirname(digestFile), { recursive: true });
-  await fs.writeFile(digestFile, digest.join("\\n") + "\\n", "utf8");
+  await writeTextFileAtomic(digestFile, digest.join("\\n") + "\\n");
   return 0;
 }
 

package/dist/fs-utils.js

@@ -75,35 +75,67 @@ export async function writeFileSafe(filePath, content, options = {}) {
     const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
     const targetMode = options.mode;
     await fs.writeFile(tempPath, content, { encoding: "utf8", ...(targetMode !== undefined ? { mode: targetMode } : {}) });
-    try {
-        await fs.rename(tempPath, filePath);
-        if (targetMode !== undefined) {
-            await fs.chmod(filePath, targetMode).catch(() => undefined);
+    // On Windows, `fs.rename` can fail transiently with EPERM / EBUSY / EACCES
+    // when the target file is briefly held open by another process (antivirus,
+    // search indexer, or a concurrent cclaw hook). Retry with small backoff
+    // before falling back to a non-atomic copy + unlink.
+    const renameRetryableCodes = new Set(["EPERM", "EBUSY", "EACCES"]);
+    let attempt = 0;
+    const maxAttempts = 6;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        try {
+            await fs.rename(tempPath, filePath);
+            if (targetMode !== undefined) {
+                await fs.chmod(filePath, targetMode).catch(() => undefined);
+            }
+            return;
         }
-    }
-    catch (error) {
-        const code = error?.code;
-        // `rename` fails with EXDEV when the temp file and target live on
-        // different filesystems (container bind mounts, tmpfs + rootfs,
-        // cross-volume setups). Fall back to copy + unlink so atomic writes
-        // still work — copyFile is not fully atomic but is the best we can
-        // do across devices, and we remove the temp even if copy fails.
-        if (code === "EXDEV") {
-            try {
-                await fs.copyFile(tempPath, filePath);
-                if (targetMode !== undefined) {
-                    await fs.chmod(filePath, targetMode).catch(() => undefined);
+        catch (error) {
+            const code = error?.code;
+            // `rename` fails with EXDEV when the temp file and target live on
+            // different filesystems (container bind mounts, tmpfs + rootfs,
+            // cross-volume setups). Fall back to copy + unlink so atomic writes
+            // still work — copyFile is not fully atomic but is the best we can
+            // do across devices, and we remove the temp even if copy fails.
+            if (code === "EXDEV") {
+                try {
+                    await fs.copyFile(tempPath, filePath);
+                    if (targetMode !== undefined) {
+                        await fs.chmod(filePath, targetMode).catch(() => undefined);
+                    }
+                }
+                finally {
+                    await fs.unlink(tempPath).catch(() => undefined);
                 }
+                return;
             }
-            finally {
-                await fs.unlink(tempPath).catch(() => undefined);
+            if (code !== undefined && renameRetryableCodes.has(code) && attempt < maxAttempts) {
+                attempt += 1;
+                const waitMs = 10 * attempt + Math.floor(Math.random() * 10);
+                await new Promise((resolve) => setTimeout(resolve, waitMs));
+                continue;
             }
-            return;
+            if (code !== undefined && renameRetryableCodes.has(code)) {
+                // Last-resort fallback on Windows: copy-then-unlink. Not atomic,
+                // but the caller is expected to have serialized via a directory
+                // lock so this only loses atomicity under extreme contention.
+                try {
+                    await fs.copyFile(tempPath, filePath);
+                    if (targetMode !== undefined) {
+                        await fs.chmod(filePath, targetMode).catch(() => undefined);
+                    }
+                    return;
+                }
+                finally {
+                    await fs.unlink(tempPath).catch(() => undefined);
+                }
+            }
+            // Other errors: try to clean up the temp to avoid littering the
+            // directory with orphaned `.tmp-<pid>-*` files, then rethrow.
+            await fs.unlink(tempPath).catch(() => undefined);
+            throw error;
         }
-        // Other errors: try to clean up the temp to avoid littering the
-        // directory with orphaned `.tmp-<pid>-*` files, then rethrow.
-        await fs.unlink(tempPath).catch(() => undefined);
-        throw error;
     }
 }
 export async function exists(filePath) {

package/dist/run-archive.js

@@ -6,7 +6,7 @@ import { readActiveFeature, syncActiveFeatureSnapshot } from "./feature-system.j
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { readKnowledgeSafely } from "./knowledge-store.js";
 import { evaluateRetroGate } from "./retro-gate.js";
-import { ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
+import { ensureRunSystem, flowStateLockPathFor, readFlowState, writeFlowState } from "./run-persistence.js";
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
 const STATE_DIR_REL_PATH = `${RUNTIME_ROOT}/state`;
@@ -161,150 +161,157 @@ export async function listRuns(projectRoot) {
 }
 export async function archiveRun(projectRoot, featureName, options = {}) {
     await ensureRunSystem(projectRoot);
+    // Hold BOTH archive.lock and flow-state.lock for the entire archive:
+    // the outer archive lock serializes two concurrent archives; the
+    // inner flow-state lock prevents CLI / hook paths from mutating
+    // flow-state between the archive snapshot and the subsequent reset,
+    // which used to cause lost-update races.
     return withDirectoryLock(archiveLockPath(projectRoot), async () => {
-        const activeFeature = await readActiveFeature(projectRoot);
-        const artifactsDir = activeArtifactsPath(projectRoot);
-        const runsDir = runsRoot(projectRoot);
-        await ensureDir(runsDir);
-        await ensureDir(artifactsDir);
-        const feature = (featureName?.trim() && featureName.trim().length > 0)
-            ? featureName.trim()
-            : await inferFeatureNameFromArtifacts(projectRoot);
-        const archiveBaseId = `${toArchiveDate()}-${slugifyFeatureName(feature)}`;
-        const archiveId = await uniqueArchiveId(projectRoot, archiveBaseId);
-        const archivePath = path.join(runsDir, archiveId);
-        const archiveArtifactsPath = path.join(archivePath, "artifacts");
-        let sourceState = await readFlowState(projectRoot);
-        const retroGate = await evaluateRetroGate(projectRoot, sourceState);
-        const shipCompleted = sourceState.completedStages.includes("ship");
-        const skipRetro = options.skipRetro === true;
-        const skipRetroReason = options.skipRetroReason?.trim();
-        if (skipRetro && (!skipRetroReason || skipRetroReason.length === 0)) {
-            throw new Error("archive --skip-retro requires --retro-reason=<text>.");
-        }
-        const retroSkippedInCloseout = sourceState.closeout.retroSkipped === true &&
-            typeof sourceState.closeout.retroSkipReason === "string" &&
-            sourceState.closeout.retroSkipReason.trim().length > 0;
-        const readyForArchive = sourceState.closeout.shipSubstate === "ready_to_archive";
-        const inShipCloseout = sourceState.currentStage === "ship";
-        if (inShipCloseout && skipRetro) {
-            throw new Error("Archive blocked: --skip-retro is not allowed while current stage is ship. " +
-                "Complete closeout to ready_to_archive via /cc-next.");
-        }
-        if (inShipCloseout && !readyForArchive) {
-            throw new Error("Archive blocked: closeout is not ready_to_archive. " +
-                "Resume /cc-next until closeout reaches ready_to_archive.");
-        }
-        if (shipCompleted && !readyForArchive && !skipRetro) {
-            throw new Error("Archive blocked: closeout is not ready_to_archive. " +
-                "Resume /cc-next until closeout reaches ready_to_archive, " +
-                "or run `cclaw archive --skip-retro --retro-reason=<text>` for CLI-only flows.");
-        }
-        if (retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
-            throw new Error("Archive blocked: retro gate is required after ship completion. " +
-                "Run /cc-next (auto-runs retro) or, for CLI-only flows, re-run `cclaw archive --skip-retro --retro-reason=<text>`.");
-        }
-        if (retroGate.completed) {
-            const completedAt = sourceState.retro.completedAt ?? new Date().toISOString();
-            sourceState = {
-                ...sourceState,
-                retro: {
-                    required: retroGate.required,
-                    completedAt,
-                    compoundEntries: retroGate.compoundEntries
-                }
-            };
-            await writeFlowState(projectRoot, sourceState, { allowReset: true });
-        }
-        const retroSummary = {
-            required: retroGate.required,
-            completed: retroGate.completed,
-            skipped: skipRetro || retroSkippedInCloseout,
-            skipReason: skipRetro
-                ? skipRetroReason
-                : retroSkippedInCloseout
-                    ? sourceState.closeout.retroSkipReason
-                    : undefined,
-            compoundEntries: retroGate.compoundEntries
-        };
-        await ensureDir(archivePath);
-        // Drop an `.archive-in-progress` sentinel immediately so that a crash
-        // between the artifact rename and the final manifest write leaves a
-        // recoverable marker (doctor surfaces these; re-running archive on an
-        // orphan attempts to complete or roll back). The sentinel is removed
-        // only after the manifest lands successfully.
-        const sentinelPath = path.join(archivePath, ".archive-in-progress");
-        const archivedAt = new Date().toISOString();
-        await writeFileSafe(sentinelPath, `${JSON.stringify({ archiveId, startedAt: archivedAt, sourceRunId: sourceState.activeRunId }, null, 2)}\n`);
-        const stateBeforeReset = sourceState;
-        let artifactsMoved = false;
-        let stateReset = false;
-        try {
-            await fs.rename(artifactsDir, archiveArtifactsPath);
-            artifactsMoved = true;
+        return withDirectoryLock(flowStateLockPathFor(projectRoot), async () => {
+            const activeFeature = await readActiveFeature(projectRoot);
+            const artifactsDir = activeArtifactsPath(projectRoot);
+            const runsDir = runsRoot(projectRoot);
+            await ensureDir(runsDir);
             await ensureDir(artifactsDir);
-            const archiveStatePath = path.join(archivePath, "state");
-            const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
-            const resetState = createInitialFlowState();
-            await writeFlowState(projectRoot, resetState, { allowReset: true });
-            stateReset = true;
-            await resetCarryoverStateFiles(projectRoot, resetState.activeRunId);
-            const manifest = {
-                version: 1,
-                archiveId,
-                archivedAt,
-                featureName: feature,
-                activeFeature,
-                sourceRunId: sourceState.activeRunId,
-                sourceCurrentStage: sourceState.currentStage,
-                sourceCompletedStages: sourceState.completedStages,
-                snapshottedStateFiles,
-                retro: retroSummary
-            };
-            await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-            // Manifest landed — sentinel is no longer needed.
-            await fs.unlink(sentinelPath).catch(() => undefined);
-            const knowledgeStats = await readKnowledgeStats(projectRoot);
-            await syncActiveFeatureSnapshot(projectRoot);
-            return {
-                archiveId,
-                archivePath,
-                archivedAt,
-                featureName: feature,
-                activeFeature,
-                resetState,
-                snapshottedStateFiles,
-                knowledge: knowledgeStats,
-                retro: retroSummary
+            const feature = (featureName?.trim() && featureName.trim().length > 0)
+                ? featureName.trim()
+                : await inferFeatureNameFromArtifacts(projectRoot);
+            const archiveBaseId = `${toArchiveDate()}-${slugifyFeatureName(feature)}`;
+            const archiveId = await uniqueArchiveId(projectRoot, archiveBaseId);
+            const archivePath = path.join(runsDir, archiveId);
+            const archiveArtifactsPath = path.join(archivePath, "artifacts");
+            let sourceState = await readFlowState(projectRoot);
+            const retroGate = await evaluateRetroGate(projectRoot, sourceState);
+            const shipCompleted = sourceState.completedStages.includes("ship");
+            const skipRetro = options.skipRetro === true;
+            const skipRetroReason = options.skipRetroReason?.trim();
+            if (skipRetro && (!skipRetroReason || skipRetroReason.length === 0)) {
+                throw new Error("archive --skip-retro requires --retro-reason=<text>.");
+            }
+            const retroSkippedInCloseout = sourceState.closeout.retroSkipped === true &&
+                typeof sourceState.closeout.retroSkipReason === "string" &&
+                sourceState.closeout.retroSkipReason.trim().length > 0;
+            const readyForArchive = sourceState.closeout.shipSubstate === "ready_to_archive";
+            const inShipCloseout = sourceState.currentStage === "ship";
+            if (inShipCloseout && skipRetro) {
+                throw new Error("Archive blocked: --skip-retro is not allowed while current stage is ship. " +
+                    "Complete closeout to ready_to_archive via /cc-next.");
+            }
+            if (inShipCloseout && !readyForArchive) {
+                throw new Error("Archive blocked: closeout is not ready_to_archive. " +
+                    "Resume /cc-next until closeout reaches ready_to_archive.");
+            }
+            if (shipCompleted && !readyForArchive && !skipRetro) {
+                throw new Error("Archive blocked: closeout is not ready_to_archive. " +
+                    "Resume /cc-next until closeout reaches ready_to_archive, " +
+                    "or run `cclaw archive --skip-retro --retro-reason=<text>` for CLI-only flows.");
+            }
+            if (retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
+                throw new Error("Archive blocked: retro gate is required after ship completion. " +
+                    "Run /cc-next (auto-runs retro) or, for CLI-only flows, re-run `cclaw archive --skip-retro --retro-reason=<text>`.");
+            }
+            if (retroGate.completed) {
+                const completedAt = sourceState.retro.completedAt ?? new Date().toISOString();
+                sourceState = {
+                    ...sourceState,
+                    retro: {
+                        required: retroGate.required,
+                        completedAt,
+                        compoundEntries: retroGate.compoundEntries
+                    }
+                };
+                await writeFlowState(projectRoot, sourceState, { allowReset: true, skipLock: true });
+            }
+            const retroSummary = {
+                required: retroGate.required,
+                completed: retroGate.completed,
+                skipped: skipRetro || retroSkippedInCloseout,
+                skipReason: skipRetro
+                    ? skipRetroReason
+                    : retroSkippedInCloseout
+                        ? sourceState.closeout.retroSkipReason
+                        : undefined,
+                compoundEntries: retroGate.compoundEntries
             };
-        }
-        catch (err) {
-            // Best-effort rollback: if artifacts were moved but the subsequent
-            // steps failed, put artifacts back so the user is not left without
-            // a working run. The sentinel is intentionally left behind for
-            // inspection; doctor surfaces it.
-            if (artifactsMoved) {
-                try {
-                    await fs.rm(artifactsDir, { recursive: true, force: true });
-                    await fs.rename(archiveArtifactsPath, artifactsDir);
-                }
-                catch {
-                    // Rollback failed — sentinel + orphaned archive dir will be
-                    // surfaced by doctor and can be reconciled manually.
-                }
+            await ensureDir(archivePath);
+            // Drop an `.archive-in-progress` sentinel immediately so that a crash
+            // between the artifact rename and the final manifest write leaves a
+            // recoverable marker (doctor surfaces these; re-running archive on an
+            // orphan attempts to complete or roll back). The sentinel is removed
+            // only after the manifest lands successfully.
+            const sentinelPath = path.join(archivePath, ".archive-in-progress");
+            const archivedAt = new Date().toISOString();
+            await writeFileSafe(sentinelPath, `${JSON.stringify({ archiveId, startedAt: archivedAt, sourceRunId: sourceState.activeRunId }, null, 2)}\n`);
+            const stateBeforeReset = sourceState;
+            let artifactsMoved = false;
+            let stateReset = false;
+            try {
+                await fs.rename(artifactsDir, archiveArtifactsPath);
+                artifactsMoved = true;
+                await ensureDir(artifactsDir);
+                const archiveStatePath = path.join(archivePath, "state");
+                const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
+                const resetState = createInitialFlowState();
+                await writeFlowState(projectRoot, resetState, { allowReset: true, skipLock: true });
+                stateReset = true;
+                await resetCarryoverStateFiles(projectRoot, resetState.activeRunId);
+                const manifest = {
+                    version: 1,
+                    archiveId,
+                    archivedAt,
+                    featureName: feature,
+                    activeFeature,
+                    sourceRunId: sourceState.activeRunId,
+                    sourceCurrentStage: sourceState.currentStage,
+                    sourceCompletedStages: sourceState.completedStages,
+                    snapshottedStateFiles,
+                    retro: retroSummary
+                };
+                await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+                // Manifest landed — sentinel is no longer needed.
+                await fs.unlink(sentinelPath).catch(() => undefined);
+                const knowledgeStats = await readKnowledgeStats(projectRoot);
+                await syncActiveFeatureSnapshot(projectRoot);
+                return {
+                    archiveId,
+                    archivePath,
+                    archivedAt,
+                    featureName: feature,
+                    activeFeature,
+                    resetState,
+                    snapshottedStateFiles,
+                    knowledge: knowledgeStats,
+                    retro: retroSummary
+                };
             }
-            if (stateReset) {
-                try {
-                    await writeFlowState(projectRoot, stateBeforeReset, { allowReset: true });
-                    await resetCarryoverStateFiles(projectRoot, stateBeforeReset.activeRunId);
+            catch (err) {
+                // Best-effort rollback: if artifacts were moved but the subsequent
+                // steps failed, put artifacts back so the user is not left without
+                // a working run. The sentinel is intentionally left behind for
+                // inspection; doctor surfaces it.
+                if (artifactsMoved) {
+                    try {
+                        await fs.rm(artifactsDir, { recursive: true, force: true });
+                        await fs.rename(archiveArtifactsPath, artifactsDir);
+                    }
+                    catch {
+                        // Rollback failed — sentinel + orphaned archive dir will be
+                        // surfaced by doctor and can be reconciled manually.
+                    }
                 }
-                catch {
-                    // If rollback of state fails, keep sentinel + archive remnants for
-                    // manual reconciliation.
+                if (stateReset) {
+                    try {
+                        await writeFlowState(projectRoot, stateBeforeReset, { allowReset: true, skipLock: true });
+                        await resetCarryoverStateFiles(projectRoot, stateBeforeReset.activeRunId);
+                    }
+                    catch {
+                        // If rollback of state fails, keep sentinel + archive remnants for
+                        // manual reconciliation.
+                    }
                 }
+                throw err;
             }
-            throw err;
-        }
+        });
     }, {
         retries: 400,
         retryDelayMs: 25,

package/dist/run-persistence.d.ts

@@ -11,6 +11,13 @@ export interface WriteFlowStateOptions {
      * bootstrap, or explicit recovery; never set from normal stage handlers.
      */
     allowReset?: boolean;
+    /**
+     * When true, skip the internal directory-lock acquisition. The caller
+     * MUST already hold `flowStateLockPath(projectRoot)` for the duration
+     * of this call. Used by run-archive to keep the full archive +
+     * flow-state reset inside one atomic lock window.
+     */
+    skipLock?: boolean;
 }
 export interface ReadFlowStateOptions {
     /**
@@ -26,6 +33,12 @@ export declare class CorruptFlowStateError extends Error {
 }
 export declare function readFlowState(projectRoot: string, options?: ReadFlowStateOptions): Promise<FlowState>;
 export declare function writeFlowState(projectRoot: string, state: FlowState, options?: WriteFlowStateOptions): Promise<void>;
+/**
+ * Exposed path helper so callers that need to serialize a multi-step
+ * state operation with flow-state writes (e.g. run archival) can
+ * acquire the SAME lock directory used internally by `writeFlowState`.
+ */
+export declare function flowStateLockPathFor(projectRoot: string): string;
 interface EnsureRunSystemOptions {
     createIfMissing?: boolean;
 }

package/dist/run-persistence.js

@@ -362,7 +362,7 @@ export async function readFlowState(projectRoot, options = {}) {
 }
 export async function writeFlowState(projectRoot, state, options = {}) {
     await ensureFeatureSystem(projectRoot);
-    await withDirectoryLock(flowStateLockPath(projectRoot), async () => {
+    const doWrite = async () => {
         const statePath = flowStatePath(projectRoot);
         if (!options.allowReset && (await exists(statePath))) {
             try {
@@ -382,9 +382,23 @@ export async function writeFlowState(projectRoot, state, options = {}) {
         }
         const safe = coerceFlowState({ ...state });
         await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`, { mode: 0o600 });
-    });
+    };
+    if (options.skipLock) {
+        await doWrite();
+    }
+    else {
+        await withDirectoryLock(flowStateLockPath(projectRoot), doWrite);
+    }
     await syncActiveFeatureSnapshot(projectRoot);
 }
+/**
+ * Exposed path helper so callers that need to serialize a multi-step
+ * state operation with flow-state writes (e.g. run archival) can
+ * acquire the SAME lock directory used internally by `writeFlowState`.
+ */
+export function flowStateLockPathFor(projectRoot) {
+    return flowStateLockPath(projectRoot);
+}
 export async function ensureRunSystem(projectRoot, _options = {}) {
     await ensureFeatureSystem(projectRoot);
     await ensureDir(runsRoot(projectRoot));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.48.16",
+  "version": "0.48.18",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {