cclaw-cli 0.48.1 → 0.48.3

package/dist/doctor.js

@@ -5,16 +5,16 @@ import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { REQUIRED_DIRS, RUNTIME_ROOT, UTILITY_COMMANDS } from "./constants.js";
 import { CCLAW_AGENTS } from "./content/core-agents.js";
-import { detectAdvancedKeys, readConfig } from "./config.js";
+import { detectAdvancedKeys, InvalidConfigError, readConfig } from "./config.js";
 import { exists } from "./fs-utils.js";
 import { gitignoreHasRequiredPatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, CCLAW_MARKER_START, CCLAW_MARKER_END, harnessShimFileNames, harnessShimSkillNames } from "./harness-adapters.js";
 import { policyChecks } from "./policy.js";
-import { readFlowState } from "./runs.js";
-import { skippedStagesForTrack } from "./flow-state.js";
+import { CorruptFlowStateError, readFlowState } from "./runs.js";
+import { createInitialFlowState, skippedStagesForTrack } from "./flow-state.js";
 import { FLOW_STAGES, TRACK_STAGES } from "./types.js";
 import { checkMandatoryDelegations } from "./delegation.js";
-import { ensureFeatureSystem, listFeatures, readActiveFeature, readFeatureWorktreeRegistry, resolveFeatureWorkspacePath, worktreeRegistryPath } from "./feature-system.js";
+import { activeFeatureMetaPath, ensureFeatureSystem, listFeatures, readActiveFeature, readFeatureWorktreeRegistry, resolveFeatureWorkspacePath, worktreeRegistryPath } from "./feature-system.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { classifyReconciliationNotices, reconcileAndWriteCurrentStageGateCatalog, readReconciliationNotices, RECONCILIATION_NOTICES_REL_PATH, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
@@ -190,6 +190,34 @@ async function readHookDocument(filePath) {
         return null;
     }
 }
+async function readJsonObjectStatus(filePath) {
+    if (!(await exists(filePath))) {
+        return { exists: false, ok: false, error: "file is missing" };
+    }
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { exists: true, ok: false, error: "JSON root must be an object" };
+        }
+        return { exists: true, ok: true };
+    }
+    catch (error) {
+        return {
+            exists: true,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+async function readPermissionBits(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        return stat.mode & 0o777;
+    }
+    catch {
+        return null;
+    }
+}
 function normalizeOpenCodePluginEntry(entry) {
     if (typeof entry === "string" && entry.trim().length > 0)
         return entry.trim();
@@ -212,12 +240,16 @@ async function opencodeRegistrationCheck(projectRoot) {
         path.join(projectRoot, ".opencode/opencode.json"),
         path.join(projectRoot, ".opencode/opencode.jsonc")
     ];
+    const mismatches = [];
+    let foundAnyConfig = false;
     for (const configPath of candidates) {
         if (!(await exists(configPath))) {
             continue;
         }
+        foundAnyConfig = true;
         const parsed = await readHookDocument(configPath);
         if (!parsed) {
+            mismatches.push(`${path.relative(projectRoot, configPath)} is unreadable or invalid JSON`);
             continue;
         }
         const plugins = Array.isArray(parsed.plugin) ? parsed.plugin : [];
@@ -225,7 +257,10 @@ async function opencodeRegistrationCheck(projectRoot) {
         if (registered) {
             return { ok: true, details: `${path.relative(projectRoot, configPath)} registers ${expected}` };
         }
-        return { ok: false, details: `${path.relative(projectRoot, configPath)} missing plugin ${expected}` };
+        mismatches.push(`${path.relative(projectRoot, configPath)} missing plugin ${expected}`);
+    }
+    if (foundAnyConfig) {
+        return { ok: false, details: mismatches.join(" | ") };
     }
     return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${expected}` };
 }
@@ -244,6 +279,12 @@ async function opencodePluginRuntimeShapeCheck(projectRoot) {
             };
         }
         const plugin = imported.default({ directory: projectRoot });
+        if (!plugin || typeof plugin !== "object" || Array.isArray(plugin)) {
+            return {
+                ok: false,
+                details: `${path.relative(projectRoot, pluginPath)} factory must return a plugin object`
+            };
+        }
         const requiredHandlers = [
             "event",
             "tool.execute.before",
@@ -257,7 +298,6 @@ async function opencodePluginRuntimeShapeCheck(projectRoot) {
                 details: `${path.relative(projectRoot, pluginPath)} missing runtime handlers: ${missing.join(", ")}`
             };
         }
-        await plugin.event({ event: { type: "session.updated", data: {} } });
         return {
             ok: true,
             details: `${path.relative(projectRoot, pluginPath)} exports compatible runtime handler shape`
@@ -426,6 +466,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         checks.push({
             name: "config:valid",
             ok: false,
+            severity: error instanceof InvalidConfigError ? "error" : "warning",
             details: error instanceof Error ? error.message : "Invalid config"
         });
     }
@@ -1289,10 +1330,28 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: modePath
         });
     }
-    await ensureFeatureSystem(projectRoot);
-    const activeFeature = await readActiveFeature(projectRoot);
-    let flowState = await readFlowState(projectRoot);
-    if (options.reconcileCurrentStageGates === true) {
+    await ensureFeatureSystem(projectRoot, { repair: false });
+    const activeFeature = await readActiveFeature(projectRoot, { repair: false });
+    let flowState = createInitialFlowState();
+    let flowStateCorruptError = null;
+    try {
+        flowState = await readFlowState(projectRoot, { repairFeatureSystem: false });
+    }
+    catch (error) {
+        if (error instanceof CorruptFlowStateError) {
+            flowStateCorruptError = error;
+            checks.push({
+                name: "flow_state:readable",
+                ok: false,
+                severity: "error",
+                details: error.message
+            });
+        }
+        else {
+            throw error;
+        }
+    }
+    if (options.reconcileCurrentStageGates === true && !flowStateCorruptError) {
         const reconciliation = await reconcileAndWriteCurrentStageGateCatalog(projectRoot);
         if (reconciliation.wrote) {
             flowState = {
@@ -1311,13 +1370,53 @@ export async function doctorChecks(projectRoot, options = {}) {
                 : `no gate reconciliation changes needed for stage "${reconciliation.stage}"`
         });
     }
+    else if (options.reconcileCurrentStageGates === true && flowStateCorruptError) {
+        checks.push({
+            name: "gates:reconcile:writeback",
+            ok: false,
+            details: "skipped gate reconciliation because flow-state.json is corrupt"
+        });
+    }
     const activeRunId = typeof flowState.activeRunId === "string" ? flowState.activeRunId.trim() : "";
     checks.push({
         name: "flow_state:active_run_id",
         ok: activeRunId.length > 0,
         details: `${RUNTIME_ROOT}/state/flow-state.json must include activeRunId`
     });
+    const sensitivePermissionTargets = [
+        path.join(projectRoot, RUNTIME_ROOT, "state", "flow-state.json"),
+        path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-log.json"),
+        path.join(projectRoot, RUNTIME_ROOT, "state", "reconciliation-notices.json"),
+        path.join(projectRoot, RUNTIME_ROOT, "state", "worktrees.json"),
+        path.join(projectRoot, RUNTIME_ROOT, "state", "active-feature.json"),
+        path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl")
+    ];
+    const permissiveStateFiles = [];
+    for (const targetPath of sensitivePermissionTargets) {
+        const bits = await readPermissionBits(targetPath);
+        if (bits === null)
+            continue;
+        if (bits > 0o640) {
+            permissiveStateFiles.push(`${path.relative(projectRoot, targetPath)}:${bits.toString(8)}`);
+        }
+    }
+    checks.push({
+        name: "warning:state:file_permissions",
+        ok: true,
+        details: permissiveStateFiles.length === 0
+            ? "sensitive state files are <=0640 permissions"
+            : `warning: sensitive state files are overly permissive (${permissiveStateFiles.join(", ")}). Run \`chmod 600 .cclaw/state/*.json .cclaw/state/*.jsonl .cclaw/knowledge.jsonl\` if this machine is multi-user.`
+    });
     const reconciliationNotices = await readReconciliationNotices(projectRoot);
+    checks.push({
+        name: "state:reconciliation_notices_parse",
+        ok: reconciliationNotices.parseOk && reconciliationNotices.schemaOk,
+        details: !reconciliationNotices.parseOk
+            ? `unable to parse ${RECONCILIATION_NOTICES_REL_PATH}; reset with \`cclaw sync\` or repair JSON by hand`
+            : !reconciliationNotices.schemaOk
+                ? `${RECONCILIATION_NOTICES_REL_PATH} schemaVersion mismatch; expected ${reconciliationNotices.schemaVersion}`
+                : `${RECONCILIATION_NOTICES_REL_PATH} parsed successfully`
+    });
     const noticeBuckets = classifyReconciliationNotices(flowState, reconciliationNotices.notices);
     const formatNoticeList = (items) => items
         .slice(0, 8)
@@ -1425,22 +1524,38 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? "no TODO/TBD/FIXME placeholder markers found in active artifacts"
             : `warning: placeholder markers detected in active artifacts (${artifactPlaceholderHits.join(", ")}). Clear before marking completion.`
     });
-    const features = await listFeatures(projectRoot);
-    const worktreeRegistry = await readFeatureWorktreeRegistry(projectRoot);
+    const activeMetaStatus = await readJsonObjectStatus(activeFeatureMetaPath(projectRoot));
+    const worktreeRegistryStatus = await readJsonObjectStatus(worktreeRegistryPath(projectRoot));
+    const features = await listFeatures(projectRoot, { repair: false });
+    const worktreeRegistry = await readFeatureWorktreeRegistry(projectRoot, { repair: false });
     const activeFeatureEntry = worktreeRegistry.entries.find((entry) => entry.featureId === activeFeature);
     const activeFeatureWorkspacePath = activeFeatureEntry
         ? resolveFeatureWorkspacePath(projectRoot, activeFeatureEntry)
         : "";
     checks.push({
         name: "state:active_feature_meta",
-        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "active-feature.json")),
+        ok: activeMetaStatus.exists,
         details: `${RUNTIME_ROOT}/state/active-feature.json must exist`
     });
+    checks.push({
+        name: "state:active_feature_meta_valid_json",
+        ok: activeMetaStatus.ok,
+        details: activeMetaStatus.ok
+            ? `${RUNTIME_ROOT}/state/active-feature.json parsed successfully`
+            : `${RUNTIME_ROOT}/state/active-feature.json is invalid: ${activeMetaStatus.error ?? "unknown error"}`
+    });
     checks.push({
         name: "state:worktree_registry_exists",
-        ok: await exists(worktreeRegistryPath(projectRoot)),
+        ok: worktreeRegistryStatus.exists,
         details: `${RUNTIME_ROOT}/state/worktrees.json must exist and track feature->worktree mapping`
     });
+    checks.push({
+        name: "state:worktree_registry_valid_json",
+        ok: worktreeRegistryStatus.ok,
+        details: worktreeRegistryStatus.ok
+            ? `${RUNTIME_ROOT}/state/worktrees.json parsed successfully`
+            : `${RUNTIME_ROOT}/state/worktrees.json is invalid: ${worktreeRegistryStatus.error ?? "unknown error"}`
+    });
     checks.push({
         name: "state:active_feature_exists",
         ok: features.includes(activeFeature),
@@ -1590,7 +1705,9 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs")),
         details: `${RUNTIME_ROOT}/runs must exist for archived feature snapshots`
     });
-    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
+    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage, {
+        repairFeatureSystem: false
+    });
     const missingEvidenceNote = delegation.missingEvidence && delegation.missingEvidence.length > 0
         ? ` (role-switch rows without evidenceRefs: ${delegation.missingEvidence.join(", ")})`
         : "";

package/dist/eval/runner.js

@@ -524,6 +524,34 @@ function stagesInResults(caseResults) {
         set.add(c.stage);
     return FLOW_STAGES.filter((s) => set.has(s));
 }
+const MAX_PARALLEL_CASES = 4;
+async function runCasesWithBoundedConcurrency(items, concurrency, worker) {
+    if (items.length === 0) {
+        return [];
+    }
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    if (limit === 1) {
+        const results = [];
+        for (let i = 0; i < items.length; i += 1) {
+            results.push(await worker(items[i], i));
+        }
+        return results;
+    }
+    const results = new Array(items.length);
+    let cursor = 0;
+    const runners = Array.from({ length: limit }, async () => {
+        while (true) {
+            const index = cursor;
+            cursor += 1;
+            if (index >= items.length) {
+                return;
+            }
+            results[index] = await worker(items[index], index);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+}
 /**
  * Main eval runner. Dispatches between fixture-backed verification, the
  * single-stage agent-with-tools loop, and the multi-stage workflow
@@ -653,8 +681,11 @@ export async function runEval(options) {
         }
     }
     else {
-        for (let i = 0; i < corpus.length; i += 1) {
-            const item = corpus[i];
+        // Only parallelize fixture/rules verification passes that do not depend on
+        // LLM judge/agent loops. Those modes touch cost guards and retries where
+        // ordered execution is safer.
+        const caseConcurrency = flags.runJudge || flags.runAgent ? 1 : MAX_PARALLEL_CASES;
+        const results = await runCasesWithBoundedConcurrency(corpus, caseConcurrency, async (item, i) => {
             progress.emit({
                 kind: "case-start",
                 caseId: item.id,
@@ -682,8 +713,9 @@ export async function runEval(options) {
                 durationMs: result.durationMs,
                 ...(result.costUsd !== undefined ? { costUsd: result.costUsd } : {})
             });
-            caseResults.push(result);
-        }
+            return result;
+        });
+        caseResults.push(...results);
     }
     const stages = stagesInResults(caseResults);
     const baselines = await loadBaselinesByStage(options.projectRoot, stages);

package/dist/feature-system.d.ts

@@ -19,16 +19,23 @@ export interface CreateFeatureOptions {
     cloneActive?: boolean;
     switchTo?: boolean;
 }
+export interface FeatureSystemAccessOptions {
+    /**
+     * When false, read metadata without auto-repair writes. Useful for pure
+     * diagnostics (doctor) that should not mutate state as a side effect.
+     */
+    repair?: boolean;
+}
 export declare function activeFeatureMetaPath(projectRoot: string): string;
 export declare function worktreeRegistryPath(projectRoot: string): string;
 export declare function featureRootPath(projectRoot: string, featureId: string): string;
 export declare function featureArtifactsPath(projectRoot: string, featureId: string): string;
 export declare function featureStatePath(projectRoot: string, featureId: string): string;
 export declare function resolveFeatureWorkspacePath(projectRoot: string, entry: FeatureWorkspaceEntry): string;
-export declare function ensureFeatureSystem(projectRoot: string): Promise<ActiveFeatureMeta>;
-export declare function readFeatureWorktreeRegistry(projectRoot: string): Promise<FeatureWorktreeRegistry>;
-export declare function readActiveFeature(projectRoot: string): Promise<string>;
-export declare function listFeatures(projectRoot: string): Promise<string[]>;
+export declare function ensureFeatureSystem(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<ActiveFeatureMeta>;
+export declare function readFeatureWorktreeRegistry(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<FeatureWorktreeRegistry>;
+export declare function readActiveFeature(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<string>;
+export declare function listFeatures(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<string[]>;
 export declare function syncActiveFeatureSnapshot(projectRoot: string): Promise<void>;
 export declare function switchActiveFeature(projectRoot: string, featureId: string): Promise<ActiveFeatureMeta>;
 export declare function createFeature(projectRoot: string, rawFeatureId: string, options?: CreateFeatureOptions): Promise<string>;

package/dist/feature-system.js

@@ -178,7 +178,7 @@ async function writeRegistry(projectRoot, registry) {
         updatedAt: registry.updatedAt,
         entries: dedupeEntries(registry.entries)
     };
-    await writeFileSafe(worktreeRegistryPath(projectRoot), `${JSON.stringify(normalized, null, 2)}\n`);
+    await writeFileSafe(worktreeRegistryPath(projectRoot), `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
 }
 async function readActiveFeatureMetaInternal(projectRoot) {
     const filePath = activeFeatureMetaPath(projectRoot);
@@ -213,7 +213,7 @@ async function writeActiveFeatureMeta(projectRoot, meta) {
         activeFeature: normalizedFeatureId(meta.activeFeature),
         updatedAt: meta.updatedAt
     };
-    await writeFileSafe(activeFeatureMetaPath(projectRoot), `${JSON.stringify(normalized, null, 2)}\n`);
+    await writeFileSafe(activeFeatureMetaPath(projectRoot), `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
 }
 function registryHasFeature(registry, featureId) {
     return registry.entries.some((entry) => entry.featureId === featureId);
@@ -278,20 +278,64 @@ async function ensureRegistryState(projectRoot) {
     await writeActiveFeatureMeta(projectRoot, activeMeta);
     return { registry, activeMeta };
 }
-export async function ensureFeatureSystem(projectRoot) {
-    const { activeMeta } = await ensureRegistryState(projectRoot);
+async function readRegistryStateReadonly(projectRoot) {
+    const currentRegistry = await readRegistry(projectRoot);
+    const entries = [...currentRegistry.entries];
+    const gitRepo = await isGitRepository(projectRoot);
+    const source = gitRepo ? "git-worktree" : "workspace";
+    const branch = gitRepo ? await currentBranch(projectRoot) : "workspace/default";
+    if (!entries.some((entry) => entry.featureId === DEFAULT_FEATURE_ID)) {
+        entries.push(buildDefaultEntry(source, branch));
+    }
+    const legacyFeatureIds = await listLegacySnapshotIds(projectRoot);
+    for (const legacyId of legacyFeatureIds) {
+        if (entries.some((entry) => entry.featureId === legacyId)) {
+            continue;
+        }
+        entries.push({
+            featureId: legacyId,
+            branch: `legacy/${legacyId}`,
+            path: `${LEGACY_FEATURES_DIR_REL_PATH}/${legacyId}`,
+            source: "legacy-snapshot",
+            createdAt: new Date().toISOString()
+        });
+    }
+    const registry = {
+        schemaVersion: WORKTREE_REGISTRY_SCHEMA_VERSION,
+        updatedAt: currentRegistry.updatedAt,
+        entries: dedupeEntries(entries)
+    };
+    const active = await readActiveFeatureMetaInternal(projectRoot);
+    return {
+        registry,
+        activeMeta: {
+            activeFeature: registryHasFeature(registry, active.activeFeature)
+                ? active.activeFeature
+                : DEFAULT_FEATURE_ID,
+            updatedAt: active.updatedAt
+        }
+    };
+}
+async function resolveFeatureSystemState(projectRoot, options = {}) {
+    if (options.repair === false) {
+        return readRegistryStateReadonly(projectRoot);
+    }
+    return ensureRegistryState(projectRoot);
+}
+export async function ensureFeatureSystem(projectRoot, options = {}) {
+    const { activeMeta } = await resolveFeatureSystemState(projectRoot, options);
     return activeMeta;
 }
-export async function readFeatureWorktreeRegistry(projectRoot) {
-    const { registry } = await ensureRegistryState(projectRoot);
+export async function readFeatureWorktreeRegistry(projectRoot, options = {}) {
+    const { registry } = await resolveFeatureSystemState(projectRoot, options);
     return registry;
 }
-export async function readActiveFeature(projectRoot) {
-    const meta = await ensureFeatureSystem(projectRoot);
+export async function readActiveFeature(projectRoot, options = {}) {
+    const meta = await ensureFeatureSystem(projectRoot, options);
     return normalizedFeatureId(meta.activeFeature);
 }
-export async function listFeatures(projectRoot) {
-    const registry = await readFeatureWorktreeRegistry(projectRoot);
+export async function listFeatures(projectRoot, options = {}) {
+    const registry = await readFeatureWorktreeRegistry(projectRoot, options);
     return registry.entries.map((entry) => entry.featureId).sort((a, b) => a.localeCompare(b));
 }
 export async function syncActiveFeatureSnapshot(projectRoot) {

package/dist/flow-state.d.ts

@@ -92,8 +92,10 @@ export declare function isFlowTrack(value: unknown): value is FlowTrack;
 export declare function trackStages(track: FlowTrack): FlowStage[];
 export declare function skippedStagesForTrack(track: FlowTrack): FlowStage[];
 export declare function firstStageForTrack(track: FlowTrack): FlowStage;
+export declare function createRunId(date?: Date): string;
 export declare function createInitialFlowState(activeRunIdOrOptions?: string | InitialFlowStateOptions, maybeTrack?: FlowTrack): FlowState;
 export declare function canTransition(from: FlowStage, to: FlowStage): boolean;
+export declare function getAvailableTransitions(from: FlowStage, track?: FlowTrack): TransitionRule[];
 export declare function getTransitionGuards(from: FlowStage, to: FlowStage, track?: FlowTrack): string[];
 export declare function nextStage(stage: FlowStage, track?: FlowTrack): FlowStage | null;
 export declare function previousStage(stage: FlowStage, track?: FlowTrack): FlowStage | null;

package/dist/flow-state.js

@@ -58,11 +58,14 @@ export function firstStageForTrack(track) {
     const stages = TRACK_STAGES[track];
     return stages[0] ?? "brainstorm";
 }
-export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTrack) {
+export function createRunId(date = new Date()) {
+    return `run-${date.getTime().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function createInitialFlowState(activeRunIdOrOptions = {}, maybeTrack) {
     const options = typeof activeRunIdOrOptions === "string"
         ? { activeRunId: activeRunIdOrOptions, track: maybeTrack }
         : activeRunIdOrOptions;
-    const activeRunId = options.activeRunId ?? "active";
+    const activeRunId = options.activeRunId ?? createRunId();
     const track = options.track ?? "standard";
     const skippedStages = skippedStagesForTrack(track);
     const stageGateCatalog = {};
@@ -97,6 +100,20 @@ export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTra
 export function canTransition(from, to) {
     return TRANSITION_RULES.some((rule) => rule.from === from && rule.to === to);
 }
+export function getAvailableTransitions(from, track = "standard") {
+    const natural = nextStage(from, track);
+    const fromRules = TRANSITION_RULES.filter((rule) => rule.from === from);
+    if (!natural) {
+        return fromRules;
+    }
+    return fromRules.sort((a, b) => {
+        if (a.to === natural && b.to !== natural)
+            return -1;
+        if (b.to === natural && a.to !== natural)
+            return 1;
+        return a.to.localeCompare(b.to);
+    });
+}
 export function getTransitionGuards(from, to, track = "standard") {
     // Natural forward edge on this track: derive guards fresh from the
     // track-specific gate schema. `TRANSITION_RULES` collapses shared edges

package/dist/fs-utils.d.ts

@@ -18,7 +18,10 @@ export interface DirectoryLockOptions {
  * The lock is removed in a finally block.
  */
 export declare function withDirectoryLock<T>(lockPath: string, fn: () => Promise<T>, options?: DirectoryLockOptions): Promise<T>;
-export declare function writeFileSafe(filePath: string, content: string): Promise<void>;
+export interface WriteFileSafeOptions {
+    mode?: number;
+}
+export declare function writeFileSafe(filePath: string, content: string, options?: WriteFileSafeOptions): Promise<void>;
 export declare function exists(filePath: string): Promise<boolean>;
 export declare function removeIfExists(targetPath: string): Promise<void>;
 export declare function resolveProjectPath(cwd: string, relativePath: string): string;

package/dist/fs-utils.js

@@ -27,6 +27,7 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
     const staleAfterMs = options.staleAfterMs ?? 60_000;
     await ensureDir(path.dirname(lockPath));
     let acquired = false;
+    let lastError = null;
     for (let attempt = 0; attempt < retries; attempt += 1) {
         try {
             await fs.mkdir(lockPath);
@@ -34,6 +35,7 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
             break;
         }
         catch (error) {
+            lastError = error;
             const code = error?.code;
             if (code !== "EEXIST") {
                 throw error;
@@ -52,21 +54,32 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
         }
     }
     if (!acquired) {
-        throw new Error(`Failed to acquire lock: ${lockPath}`);
+        const details = lastError instanceof Error ? lastError.message : String(lastError);
+        throw new Error(`Failed to acquire lock: ${lockPath} (attempts=${retries}, retryDelayMs=${retryDelayMs}, staleAfterMs=${staleAfterMs}, lastError=${details})`);
     }
     try {
         return await fn();
     }
     finally {
-        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+        await fs.rm(lockPath, { recursive: true, force: true }).catch((cleanupError) => {
+            // Lock cleanup failure should not shadow the original operation result,
+            // but keep a diagnostic breadcrumb for flaky FS environments.
+            const details = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+            // eslint-disable-next-line no-console
+            console.warn(`cclaw lock cleanup failed for ${lockPath}: ${details}`);
+        });
     }
 }
-export async function writeFileSafe(filePath, content) {
+export async function writeFileSafe(filePath, content, options = {}) {
     await ensureDir(path.dirname(filePath));
     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, "utf8");
+    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);
+        }
     }
     catch (error) {
         const code = error?.code;
@@ -78,6 +91,9 @@ export async function writeFileSafe(filePath, content) {
         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);

package/dist/gate-evidence.d.ts

@@ -41,6 +41,8 @@ export interface ReconciliationNotice {
 export interface ReconciliationNoticesPayload {
     schemaVersion: number;
     notices: ReconciliationNotice[];
+    parseOk: boolean;
+    schemaOk: boolean;
 }
 export interface ReconciliationNoticeBuckets {
     activeBlocked: ReconciliationNotice[];

package/dist/gate-evidence.js

@@ -72,7 +72,9 @@ function reconciliationNoticesPath(projectRoot) {
 function defaultReconciliationNoticesPayload() {
     return {
         schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
-        notices: []
+        notices: [],
+        parseOk: true,
+        schemaOk: true
     };
 }
 function sanitizeReconciliationNotice(raw) {
@@ -104,6 +106,7 @@ export async function readReconciliationNotices(projectRoot) {
     }
     try {
         const raw = JSON.parse(await fs.readFile(filePath, "utf8"));
+        const schemaOk = raw.schemaVersion === RECONCILIATION_NOTICES_SCHEMA_VERSION;
         const notices = Array.isArray(raw.notices)
             ? raw.notices
                 .map((value) => sanitizeReconciliationNotice(value))
@@ -111,11 +114,17 @@ export async function readReconciliationNotices(projectRoot) {
             : [];
         return {
             schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
-            notices
+            notices,
+            parseOk: true,
+            schemaOk
         };
     }
     catch {
-        return defaultReconciliationNoticesPayload();
+        return {
+            ...defaultReconciliationNoticesPayload(),
+            parseOk: false,
+            schemaOk: false
+        };
     }
 }
 async function writeReconciliationNotices(projectRoot, payload) {
@@ -124,7 +133,7 @@ async function writeReconciliationNotices(projectRoot, payload) {
     await writeFileSafe(filePath, `${JSON.stringify({
         schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
         notices: payload.notices
-    }, null, 2)}\n`);
+    }, null, 2)}\n`, { mode: 0o600 });
 }
 export function classifyReconciliationNotices(flowState, notices) {
     const activeBlocked = [];