cclaw-cli 0.48.1 → 0.48.3

package/dist/run-archive.js

@@ -3,7 +3,8 @@ import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
 import { createInitialFlowState } from "./flow-state.js";
 import { readActiveFeature, syncActiveFeatureSnapshot } from "./feature-system.js";
-import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+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";
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
@@ -17,6 +18,12 @@ const STATE_SNAPSHOT_EXCLUDE = new Set([
 const DELEGATION_LOG_FILE = "delegation-log.json";
 const TDD_CYCLE_LOG_FILE = "tdd-cycle-log.jsonl";
 const RECONCILIATION_NOTICES_FILE = "reconciliation-notices.json";
+const CRITICAL_STATE_SNAPSHOT_FILES = new Set([
+    "flow-state.json",
+    DELEGATION_LOG_FILE,
+    TDD_CYCLE_LOG_FILE,
+    RECONCILIATION_NOTICES_FILE
+]);
 function runsRoot(projectRoot) {
     return path.join(projectRoot, RUNS_DIR_REL_PATH);
 }
@@ -26,6 +33,9 @@ function activeArtifactsPath(projectRoot) {
 function stateDirPath(projectRoot) {
     return path.join(projectRoot, STATE_DIR_REL_PATH);
 }
+function archiveLockPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", ".archive.lock");
+}
 async function snapshotStateDirectory(projectRoot, destinationRoot) {
     const sourceDir = stateDirPath(projectRoot);
     if (!(await exists(sourceDir))) {
@@ -57,8 +67,12 @@ async function snapshotStateDirectory(projectRoot, destinationRoot) {
                 copied.push(entry.name);
             }
         }
-        catch {
-            // best-effort snapshot; continue on individual failures
+        catch (error) {
+            if (CRITICAL_STATE_SNAPSHOT_FILES.has(entry.name)) {
+                const details = error instanceof Error ? error.message : String(error);
+                throw new Error(`Archive snapshot failed for critical state file "${entry.name}" (${details}).`);
+            }
+            // Non-critical snapshot files are best-effort and may be skipped.
         }
     }
     return copied.sort((a, b) => a.localeCompare(b));
@@ -66,9 +80,9 @@ async function snapshotStateDirectory(projectRoot, destinationRoot) {
 async function resetCarryoverStateFiles(projectRoot, activeRunId) {
     const stateDir = stateDirPath(projectRoot);
     await ensureDir(stateDir);
-    await writeFileSafe(path.join(stateDir, DELEGATION_LOG_FILE), `${JSON.stringify({ runId: activeRunId, entries: [] }, null, 2)}\n`);
-    await writeFileSafe(path.join(stateDir, TDD_CYCLE_LOG_FILE), "");
-    await writeFileSafe(path.join(stateDir, RECONCILIATION_NOTICES_FILE), `${JSON.stringify({ schemaVersion: 1, notices: [] }, null, 2)}\n`);
+    await writeFileSafe(path.join(stateDir, DELEGATION_LOG_FILE), `${JSON.stringify({ runId: activeRunId, entries: [] }, null, 2)}\n`, { mode: 0o600 });
+    await writeFileSafe(path.join(stateDir, TDD_CYCLE_LOG_FILE), "", { mode: 0o600 });
+    await writeFileSafe(path.join(stateDir, RECONCILIATION_NOTICES_FILE), `${JSON.stringify({ schemaVersion: 1, notices: [] }, null, 2)}\n`, { mode: 0o600 });
 }
 function toArchiveDate(date = new Date()) {
     const yyyy = date.getFullYear().toString();
@@ -147,136 +161,160 @@ export async function listRuns(projectRoot) {
 }
 export async function archiveRun(projectRoot, featureName, options = {}) {
     await ensureRunSystem(projectRoot);
-    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";
-    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`);
-    let artifactsMoved = false;
-    try {
-        await fs.rename(artifactsDir, archiveArtifactsPath);
-        artifactsMoved = true;
+    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 archiveStatePath = path.join(archivePath, "state");
-        const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
-        const resetState = createInitialFlowState();
-        await writeFlowState(projectRoot, resetState, { allowReset: 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 });
+        }
+        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);
+        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 });
+            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
+            };
+        }
+        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 {
-                // Rollback failed — sentinel + orphaned archive dir will be
-                // surfaced by doctor and can be reconciled manually.
+            if (stateReset) {
+                try {
+                    await writeFlowState(projectRoot, stateBeforeReset, { allowReset: 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,
+        staleAfterMs: 120_000
+    });
 }
 const KNOWLEDGE_SOFT_THRESHOLD = 50;
 async function readKnowledgeStats(projectRoot) {
-    const knowledgePath = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
-    let activeEntryCount = 0;
-    if (await exists(knowledgePath)) {
-        const text = await fs.readFile(knowledgePath, "utf8");
-        activeEntryCount = countActiveKnowledgeEntries(text);
-    }
+    const { entries } = await readKnowledgeSafely(projectRoot);
+    const activeEntryCount = entries.length;
     return {
         activeEntryCount,
         softThreshold: KNOWLEDGE_SOFT_THRESHOLD,

package/dist/run-persistence.d.ts

@@ -12,12 +12,19 @@ export interface WriteFlowStateOptions {
      */
     allowReset?: boolean;
 }
+export interface ReadFlowStateOptions {
+    /**
+     * When false, skip feature-system auto-repair writes and read flow-state in
+     * pure diagnostic mode.
+     */
+    repairFeatureSystem?: boolean;
+}
 export declare class CorruptFlowStateError extends Error {
     readonly statePath: string;
     readonly quarantinedPath: string;
     constructor(statePath: string, quarantinedPath: string, cause: unknown);
 }
-export declare function readFlowState(projectRoot: string): Promise<FlowState>;
+export declare function readFlowState(projectRoot: string, options?: ReadFlowStateOptions): Promise<FlowState>;
 export declare function writeFlowState(projectRoot: string, state: FlowState, options?: WriteFlowStateOptions): Promise<void>;
 interface EnsureRunSystemOptions {
     createIfMissing?: boolean;

package/dist/run-persistence.js

@@ -277,7 +277,7 @@ function sanitizeCloseoutState(value) {
 }
 function coerceFlowState(parsed) {
     const track = coerceTrack(parsed.track);
-    const next = createInitialFlowState("active", track);
+    const next = createInitialFlowState({ track });
     const activeRunIdRaw = parsed.activeRunId;
     const activeRunId = typeof activeRunIdRaw === "string" && activeRunIdRaw.trim().length > 0
         ? activeRunIdRaw.trim()
@@ -333,8 +333,10 @@ async function quarantineCorruptState(statePath, cause) {
     }
     throw new CorruptFlowStateError(statePath, quarantinedPath, cause);
 }
-export async function readFlowState(projectRoot) {
-    await ensureFeatureSystem(projectRoot);
+export async function readFlowState(projectRoot, options = {}) {
+    if (options.repairFeatureSystem !== false) {
+        await ensureFeatureSystem(projectRoot);
+    }
     const statePath = flowStatePath(projectRoot);
     if (!(await exists(statePath))) {
         return createInitialFlowState();
@@ -375,12 +377,11 @@ export async function writeFlowState(projectRoot, state, options = {}) {
                 if (err instanceof InvalidStageTransitionError) {
                     throw err;
                 }
-                // A corrupt prior file is surfaced by readFlowState elsewhere; don't
-                // block a legitimate write attempt on parse errors here.
+                throw new Error(`cannot validate flow-state transition because ${FLOW_STATE_REL_PATH} is unreadable or corrupt (${err instanceof Error ? err.message : String(err)}). Run \`cclaw doctor\` and reconcile the state before retrying.`);
             }
         }
         const safe = coerceFlowState({ ...state });
-        await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`);
+        await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`, { mode: 0o600 });
     });
     await syncActiveFeatureSnapshot(projectRoot);
 }

package/dist/trace-matrix.js

@@ -124,17 +124,17 @@ export async function buildTraceMatrix(projectRoot) {
     const acToTasks = new Map();
     for (const [task, acs] of taskToAcs) {
         for (const ac of acs) {
-            const prev = acToTasks.get(ac) ?? [];
-            if (!prev.includes(task)) {
-                acToTasks.set(ac, [...prev, task]);
-            }
+            const prev = acToTasks.get(ac) ?? new Set();
+            prev.add(task);
+            acToTasks.set(ac, prev);
         }
     }
     const entries = criterionIds.map((criterionId) => {
-        const taskIds = acToTasks.get(criterionId) ?? [];
+        const taskIds = [...(acToTasks.get(criterionId) ?? new Set())];
+        const taskIdSet = new Set(taskIds);
         const testSlices = [];
         for (const [slice, tasks] of sliceToTasks) {
-            if (tasks.some((t) => taskIds.includes(t))) {
+            if (tasks.some((t) => taskIdSet.has(t))) {
                 testSlices.push(slice);
             }
         }
@@ -145,7 +145,7 @@ export async function buildTraceMatrix(projectRoot) {
             reviewFindings: layer1LinesForCriterion(layer1, criterionId)
         };
     });
-    const orphanedCriteria = criterionIds.filter((ac) => (acToTasks.get(ac) ?? []).length === 0);
+    const orphanedCriteria = criterionIds.filter((ac) => (acToTasks.get(ac)?.size ?? 0) === 0);
     const tasksWithSlice = new Set();
     for (const tasks of sliceToTasks.values()) {
         for (const t of tasks) {

package/package.json

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