iterate-plugin 3.5.6 → 3.6.0

package/src/tools/checkpoint.ts

@@ -20,6 +20,7 @@ import { readDecisionEntries } from './decision-log.ts'
 import { readQualityGate } from './quality-store.ts'
 import { readExperienceBank } from './experience-store.ts'
 import { readDefenseEvents } from './defense-store.ts'
+import { asNumber, asRecord, parseRenderedJson } from './present.ts'
 import type { DefenseEventType, IterationCheckpoint, IterationStatus, QualityGateSnapshot } from '../types.ts'
 
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
@@ -28,6 +29,23 @@ import type { DefenseEventType, IterationCheckpoint, IterationStatus, QualityGat
  *  bounded, mirroring MAX_FIX_CONTENT_CHARS for fix content). */
 export const MAX_CHECKPOINT_FINDINGS = 1000
 
+/**
+ * Sanity cap for round/counter fields. Status output fields are declared
+ * `type: 'integer'` in the tool schema; flooring + capping here guarantees a
+ * hand-edited value can never reach dsh's post-execute output validation as a
+ * float (INVALID_TOOL_OUTPUT on iterate_status).
+ */
+const MAX_COUNTER = 1_000_000_000
+
+/**
+ * Coerce a numeric field to a non-negative, in-cap INTEGER.
+ * Non-numeric (string/NaN/undefined) → `fallback`.
+ */
+function toInteger(v: unknown, fallback: number): number {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return fallback
+  return Math.min(Math.max(Math.floor(v), 0), MAX_COUNTER)
+}
+
 /** Read the current checkpoint from disk (missing/corrupt → null). */
 export function readCheckpoint(projectRoot: string): IterationCheckpoint | null {
   const file = checkpointPath(projectRoot)
@@ -38,23 +56,27 @@ export function readCheckpoint(projectRoot: string): IterationCheckpoint | null
     if (parsed.mode !== 'dry-run' && parsed.mode !== 'normal') return null
     // Strict round gate: non-numeric (incl. NaN — `NaN <= 0` is false and
     // `NaN < 0` also false) round values must not survive into the status.
+    // The floor also kills `round: 2.5` — validateCheckpoint only ever SAVES
+    // integers, so a non-integer on disk is hand-edited/corrupt.
     const round =
       typeof parsed.round === 'number' && Number.isFinite(parsed.round)
         ? Math.floor(parsed.round)
         : null
-    if (round === null || round < 0) return null
-    const num = (v: unknown, fallback: number): number =>
-      typeof v === 'number' && Number.isFinite(v) ? v : fallback
+    if (round === null || round < 0 || round > MAX_COUNTER) return null
     // Normalize every field so a hand-edited/corrupt checkpoint (string
-    // maxRounds, missing fixedCount, …) can never leak a non-numeric value
-    // into the status output or crash a consumer.
+    // maxRounds, float fixedCount, missing architecturalCount, …) can never
+    // leak a non-integer value into the status output or crash a consumer.
+    const maxRounds = toInteger(parsed.maxRounds, round)
+    // Consistent with validateCheckpoint's save gate: a checkpoint claiming a
+    // round past its cap is corrupt — otherwise status renders "Round 99 / 5".
+    if (round > maxRounds) return null
     return {
       mode: parsed.mode,
       round,
-      maxRounds: num(parsed.maxRounds, round),
-      fixedCount: num(parsed.fixedCount, 0),
-      architecturalCount: num(parsed.architecturalCount, 0),
-      resumeCount: num(parsed.resumeCount, 0),
+      maxRounds,
+      fixedCount: toInteger(parsed.fixedCount, 0),
+      architecturalCount: toInteger(parsed.architecturalCount, 0),
+      resumeCount: toInteger(parsed.resumeCount, 0),
       findings: Array.isArray(parsed.findings) ? (parsed.findings as IterationCheckpoint['findings']) : [],
       startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : new Date().toISOString(),
       updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
@@ -146,24 +168,30 @@ export function computeStatus(input: {
   const lastUpdated = lastEntry?.timestamp ?? checkpoint?.updatedAt ?? null
 
   // Round = checkpoint.round (explicit) or max round seen in the decision log.
-  let currentRound = checkpoint?.round ?? 0
-  if (!checkpoint) {
+  // Everything is funneled through toInteger: a hand-edited `round: 2.5` entry
+  // or an injected float checkpoint must never surface as a non-integer in the
+  // status output (schema `type: 'integer'`).
+  let currentRound = 0
+  if (checkpoint) {
+    currentRound = toInteger(checkpoint.round, 0)
+  } else {
     for (const e of entries) {
-      if (typeof e.round === 'number' && e.round > currentRound) currentRound = e.round
+      const r = toInteger(e.round, 0)
+      if (r > currentRound) currentRound = r
     }
   }
 
-  const totalRounds = checkpoint?.maxRounds ?? currentRound
+  const totalRounds = checkpoint ? toInteger(checkpoint.maxRounds, currentRound) : currentRound
   // Coerce the registry's per-round counts defensively: a hand-edited registry
   // round missing fixedCount/failedCount would otherwise feed NaN into the
-  // status integer fields.
-  const registryFixed = registry.rounds.reduce((sum, r) => sum + (Number(r.fixedCount) || 0), 0)
-  const failedCount = registry.rounds.reduce((sum, r) => sum + (Number(r.failedCount) || 0), 0)
+  // status integer fields — and fractional counts (1.5) must be floored too.
+  const registryFixed = registry.rounds.reduce((sum, r) => sum + toInteger(r.fixedCount, 0), 0)
+  const failedCount = registry.rounds.reduce((sum, r) => sum + toInteger(r.failedCount, 0), 0)
   // When a checkpoint exists, its snapshot fields are authoritative for resume
   // (fixedCount / architecturalCount / findings); otherwise derive from the
   // live fix registry and decision log.
-  const fixedCount = checkpoint ? checkpoint.fixedCount : registryFixed
-  const architecturalCount = checkpoint?.architecturalCount ?? 0
+  const fixedCount = checkpoint ? toInteger(checkpoint.fixedCount, 0) : registryFixed
+  const architecturalCount = toInteger(checkpoint?.architecturalCount, 0)
 
   return {
     mode: checkpoint?.mode ?? null,
@@ -188,7 +216,7 @@ export function computeStatus(input: {
       !(lastEntry != null &&
         checkpoint.updatedAt &&
         (Date.parse(checkpoint.updatedAt) || 0) >= (Date.parse(lastEntry.timestamp) || 0)),
-    resumeCount: checkpoint?.resumeCount ?? 0,
+    resumeCount: toInteger(checkpoint?.resumeCount, 0),
     checkpoint,
     lastUpdated,
     // v3.0: quality command-center snapshots (present only when the caller
@@ -210,6 +238,40 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
   ctx.tools.register(
     defineTool({
       name: 'iterate_checkpoint',
+      // Result card (#12): the render is a raw JSON blob — turn it into a
+      // progress headline ("Checkpoint saved — round 2/5 (3 fixed)"). This
+      // tool has no `status` operation (progress lives on iterate_status), so
+      // save/load/resume/clear each get their headline. Pure: parsed from the
+      // rendered result only; an unreadable shape declines the card and the UI
+      // falls back to the raw JSON.
+      presentResult: (args, result) => {
+        const a = args as { operation?: unknown }
+        const op = typeof a.operation === 'string' && a.operation ? a.operation : undefined
+        if (!op) return undefined
+        const value = parseRenderedJson(result)
+        if (!value) return undefined
+        if (value.ok !== true) {
+          const err = typeof value.error === 'string' && value.error ? value.error : 'unknown error'
+          return { card: 'generic', title: `Checkpoint ${op} failed: ${err}` }
+        }
+        if (op === 'clear') {
+          return { card: 'generic', title: value.existed === true ? 'Checkpoint cleared' : 'No checkpoint to clear' }
+        }
+        const checkpoint = asRecord(value.checkpoint)
+        if (!checkpoint) {
+          // `load` with nothing on disk is a valid, useful outcome.
+          return op === 'load' ? { card: 'generic', title: 'No checkpoint on disk' } : undefined
+        }
+        const round = asNumber(checkpoint.round)
+        const maxRounds = asNumber(checkpoint.maxRounds)
+        const fixed = asNumber(checkpoint.fixedCount)
+        const resumeCount = asNumber(checkpoint.resumeCount)
+        const base = op === 'save' ? 'Checkpoint saved' : op === 'resume' ? 'Checkpoint resumed' : 'Checkpoint loaded'
+        const resume = op === 'resume' && resumeCount !== undefined ? ` (resume #${resumeCount})` : ''
+        const progress = round !== undefined ? ` — round ${round}${maxRounds !== undefined ? `/${maxRounds}` : ''}` : ''
+        const fixedPart = fixed !== undefined ? ` (${fixed} fixed)` : ''
+        return { card: 'generic', title: base + resume + progress + fixedPart }
+      },
       description:
         'Save / load / resume / clear the iteration checkpoint. The workflow saves a checkpoint at the start of ' +
         'each round (so a long run can resume) and clears it when the iteration completes. ' +

package/src/tools/config.ts

@@ -1,5 +1,5 @@
 import { join } from 'node:path'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from '../config-loader.ts'
@@ -101,6 +101,22 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
         // ── Write operation ────────────────────────────────────────────────
         if (args.operation === 'write') {
           const updates = args.updates as Record<string, unknown> | undefined
+          // Missing/empty `updates` used to re-dump the config as-is: the
+          // write "succeeded" (ok:true + a spurious backup) while silently
+          // re-serializing the file and losing any hand-written comments.
+          // There is nothing to merge — refuse instead.
+          const isEmptyUpdate =
+            updates === undefined ||
+            updates === null ||
+            (typeof updates === 'object' && !Array.isArray(updates) && Object.keys(updates).length === 0)
+          if (isEmptyUpdate) {
+            return {
+              operation: 'write',
+              ok: false,
+              found: false,
+              error: 'updates is required (and must be non-empty) for operation "write"',
+            }
+          }
           const updateErrors = validateConfigUpdates(updates ?? {})
           if (updateErrors.length > 0) {
             return { operation: 'write', ok: false, found: false, errors: updateErrors }
@@ -147,6 +163,26 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
 
         if (args.validate) {
           const errors = validateConfig(config)
+          // A config file that EXISTS but cannot be parsed silently degrades to
+          // the built-in defaults (loadEffectiveConfig never throws). Reporting
+          // `valid: true` for that file would wave through the breakage —
+          // re-read it raw and surface the parse failure as a validation error.
+          const configPath = join(projectRoot, 'iterate.config.yaml')
+          if (source === 'defaults' && existsSync(configPath)) {
+            const raw = readFileSync(configPath, 'utf-8')
+            if (raw.trim().length > 0) {
+              try {
+                readRawConfig(configPath)
+              } catch (err) {
+                return {
+                  found: true,
+                  valid: false,
+                  errors: [`iterate.config.yaml is not usable: ${String((err as Error).message ?? err)}`],
+                  section: 'validation_report',
+                }
+              }
+            }
+          }
           return {
             found: hasOverride,
             valid: errors.length === 0,
@@ -157,7 +193,13 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
 
         if (args.section) {
           const configRecord = config as unknown as Record<string, unknown>
-          const section = configRecord[args.section]
+          // Object.hasOwn, NOT `configRecord[args.section]`: a plain
+          // `configRecord["toString"]` resolves through the PROTOTYPE CHAIN to
+          // a function (non-JSON → ToolOutputError) and `["__proto__"]`
+          // returns Object.prototype dressed up as an "existing section".
+          const section = Object.hasOwn(configRecord, args.section)
+            ? (configRecord[args.section] as unknown)
+            : undefined
           if (section === undefined) {
             return {
               found: hasOverride,

package/src/tools/context.ts

@@ -24,10 +24,19 @@ export function isAllowedSkillDir(skillDir: string, allowedRoots: readonly strin
     if (!existsSync(dir) || !statSync(dir).isDirectory()) return false
     return allowedRoots.some((root) => {
       if (typeof root !== 'string' || root.length === 0) return false
-      const rootReal = realpathSync(root)
-      const rootPrefix = rootReal.endsWith(sep) ? rootReal : rootReal + sep
-      const real = realpathSync(dir)
-      return real === rootReal || real.startsWith(rootPrefix)
+      // Per-root try/catch: realpathSync THROWS for a root that does not exist
+      // yet. One throw around the whole `.some()` would abort the scan and
+      // reject a perfectly valid skillDir sitting inside a LATER root (the
+      // caller then silently falls back to auto-detection) — skip only the
+      // unusable root and keep checking the remaining ones.
+      try {
+        const rootReal = realpathSync(root)
+        const rootPrefix = rootReal.endsWith(sep) ? rootReal : rootReal + sep
+        const real = realpathSync(dir)
+        return real === rootReal || real.startsWith(rootPrefix)
+      } catch {
+        return false // broken/missing allowed root — not a match, keep scanning
+      }
     })
   } catch {
     return false
@@ -307,7 +316,11 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
           searched: string[]
           attachments?: string[]
           attachmentErrors?: string[]
-        } = { found: true, searched: [] }
+          // `found` starts false and is DERIVED at the end from the content
+          // actually returned — hardcoding `true` here meant a miss (no
+          // SKILL.md/ITERATE.md anywhere) still reported `found: true` while
+          // the renderer said "No files found".
+        } = { found: false, searched: [] }
 
         // Relay user-attached image metadata into the review context. The
         // orchestrator observes attached images in the session and passes their
@@ -358,6 +371,13 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
           result.project = readProjectFile(projectRoot, 'ITERATE.md')
         }
 
+        // Derive `found` from what was actually returned. It mirrors the
+        // renderer's "No files found" branch exactly: requested file content,
+        // or relayed attachments (attachmentErrors alone never make a find).
+        result.found =
+          Boolean(result.skill) ||
+          Boolean(result.project) ||
+          (Array.isArray(result.attachments) && result.attachments.length > 0)
         return result
       },
     }),

package/src/tools/decision-log.ts

@@ -27,9 +27,11 @@ const LOG_FILE = 'decision-log.jsonl'
 // by synchronous I/O, but a second plugin process appending to the same
 // project realises the race. The log is serialized with a tiny advisory lock
 // file (exclusive create, pid stamped, stale-stealable) so `append` and the
-// prune rewrite mutually exclude across processes. Best-effort: contention
-// timeouts degrade to "proceed unlocked" (the bounded retry loop in prune.ts
-// stays as defense-in-depth), never to a crash.
+// prune rewrite mutually exclude across processes. Appends are BEST-EFFORT:
+// contention timeouts degrade to "proceed unlocked" (an audit line must never
+// be lost to a wedged append), never to a crash. The prune REWRITE is the
+// opposite — it renames the log and therefore refuses to run when the lock
+// cannot be taken (see `rewriteDecisionLogKeepingRecent` in prune.ts).
 
 const LOCK_FILE = '.decision-log.lock'
 const LOCK_WAIT_MS = 5000
@@ -57,14 +59,40 @@ function sleepSync(ms: number): void {
  * Acquire the decision-log lock for `projectRoot`.
  * Returns a release function (always callable; a no-op when the lock could
  * not be taken — never wedge an append behind a vanished holder).
+ *
+ * `options.waitMs` / `options.staleMs` override the defaults (tests use short
+ * waits so a live-holder timeout is exercised in milliseconds, not 5s).
  */
-export function acquireLogLock(projectRoot: string): () => void {
+export function acquireLogLock(
+  projectRoot: string,
+  options: { waitMs?: number; staleMs?: number } = {},
+): () => void {
+  return acquireLogLockChecked(projectRoot, options).release
+}
+
+/**
+ * {@link acquireLogLock} plus the one thing the prune rewrite needs: whether
+ * the lock was actually TAKEN. Appends stay best-effort on contention (an
+ * audit line must not be lost to a wedged append), but the rewrite renames the
+ * log under any unlocked concurrent appender — it must refuse to run without
+ * the mutex rather than silently dropping an audit line.
+ */
+export function acquireLogLockChecked(
+  projectRoot: string,
+  options: { waitMs?: number; staleMs?: number } = {},
+): { acquired: boolean; release: () => void } {
+  const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
+    ? (options.waitMs as number)
+    : LOCK_WAIT_MS
+  const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
+    ? (options.staleMs as number)
+    : LOCK_STALE_MS
   const dir = join(projectRoot, LOG_DIR)
   if (!existsSync(dir)) {
     try {
       mkdirSync(dir, { recursive: true })
     } catch {
-      return () => {}
+      return { acquired: false, release: () => {} }
     }
   }
   const lockPath = join(dir, LOCK_FILE)
@@ -74,12 +102,12 @@ export function acquireLogLock(projectRoot: string): () => void {
     try {
       fd = openSync(lockPath, 'wx')
     } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return () => {}
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return { acquired: false, release: () => {} }
       // Lock exists — steal it when the owner is gone or the lock is ancient.
       let stale = false
       try {
         const st = statSync(lockPath)
-        if (Date.now() - st.mtimeMs > LOCK_STALE_MS) stale = true
+        if (Date.now() - st.mtimeMs > staleMs) stale = true
         else {
           const pid = Number(readFileSync(lockPath, 'utf-8'))
           if (!processAlive(pid)) stale = true
@@ -91,7 +119,7 @@ export function acquireLogLock(projectRoot: string): () => void {
         try { unlinkSync(lockPath) } catch { /* another holder stole it */ }
         continue
       }
-      if (Date.now() - start > LOCK_WAIT_MS) return () => {}
+      if (Date.now() - start > waitMs) return { acquired: false, release: () => {} }
       sleepSync(LOCK_POLL_MS)
       continue
     }
@@ -99,28 +127,88 @@ export function acquireLogLock(projectRoot: string): () => void {
     try { writeSync(fd, String(process.pid)) } catch { /* pid stamp is advisory */ }
     try { closeSync(fd) } catch { /* best-effort */ }
     let released = false
-    return () => {
-      if (released) return
-      released = true
-      try { unlinkSync(lockPath) } catch { /* already gone */ }
+    return {
+      acquired: true,
+      release: () => {
+        if (released) return
+        released = true
+        try { unlinkSync(lockPath) } catch { /* already gone */ }
+      },
     }
   }
 }
 
 // ─── Entry-count cache (avoid an O(n) full re-read per append) ─────────────
 
+/**
+ * Max distinct log paths tracked by the entry-count cache. The cache is keyed
+ * by PATH (one entry per project's log) with no natural eviction — a long-lived
+ * process touching many projects would otherwise grow it without bound. A
+ * simple insertion-ordered LRU: a hit re-inserts (refreshing recency), a set
+ * past the cap evicts the least-recently-used path. Small on purpose: the
+ * hot path is one project's log.
+ */
+export const LOG_COUNT_CACHE_CAP = 64
+
 const entryCountCache = new Map<string, { size: number; count: number }>()
 
-/** Line-count the log file from scratch (entries = non-empty JSON lines). */
-function recountEntries(filePath: string): number {
+/** LRU-ish get: refresh recency by re-inserting the key. */
+function cacheGet(filePath: string): { size: number; count: number } | undefined {
+  const hit = entryCountCache.get(filePath)
+  if (hit) {
+    entryCountCache.delete(filePath)
+    entryCountCache.set(filePath, hit)
+  }
+  return hit
+}
+
+/** Insert (or refresh) a cache entry, evicting past LOG_COUNT_CACHE_CAP. */
+function cacheSet(filePath: string, value: { size: number; count: number }): void {
+  entryCountCache.delete(filePath)
+  entryCountCache.set(filePath, value)
+  while (entryCountCache.size > LOG_COUNT_CACHE_CAP) {
+    const oldest = entryCountCache.keys().next().value
+    if (oldest === undefined) break
+    entryCountCache.delete(oldest)
+  }
+}
+
+/** Current cache occupancy (exported for unit tests of the capacity bound). */
+export function logCountCacheSize(): number {
+  return entryCountCache.size
+}
+
+/**
+ * Line-count the log file from scratch (entries = non-empty JSON lines).
+ * Exported for unit tests.
+ *
+ * A read failure (file vanished, permission, replaced by a directory) returns
+ * `{ ok: false }` with the last KNOWN cached count for this path — or 0 when
+ * the path was never counted. The old code returned a fabricated `1` here,
+ * which the caller then cached, poisoning the base count for every later
+ * append. The `ok` flag lets the caller skip caching a failed read entirely.
+ */
+export function recountEntries(filePath: string): { count: number; ok: boolean } {
   try {
     const content = readFileSync(filePath, 'utf-8')
-    return content.split('\n').filter((l) => l.trim().length > 0).length
+    return { count: content.split('\n').filter((l) => l.trim().length > 0).length, ok: true }
   } catch {
-    return 1
+    return { count: cacheGet(filePath)?.count ?? 0, ok: false }
   }
 }
 
+/**
+ * Drop the cached entry count for a log file. The cache is keyed by the log
+ * path and assumes "same byte size ⇒ same entry count"; a prune rewrite
+ * (temp + atomic rename) replaces the file with a DIFFERENT number of entries,
+ * so only a stale-cache invalidation keeps the fast path honest. Without it, a
+ * rewrite that lands on the exact same byte size as the previous append would
+ * make the next append report a wrong `count`.
+ */
+export function invalidateLogCountCache(filePath: string): void {
+  entryCountCache.delete(filePath)
+}
+
 /** All valid DecisionLogEntry `type` values (must stay in sync with Types). */
 const VALID_ENTRY_TYPES = new Set<DecisionLogEntry['type']>([
   'round_start',
@@ -174,19 +262,36 @@ export function appendDecisionEntry(projectRoot: string, entry: DecisionLogEntry
   // with a prune rewrite (which renames the file under us).
   const release = acquireLogLock(projectRoot)
   try {
-    const filePath = logPath(projectRoot)
+    // EVERYTHING that can throw — including `logPath`'s mkdirSync (EACCES when
+    // `.iterate` cannot be created, ENOTDIR when an ancestor is a regular file)
+    // and the statSync probes — sits inside the inner try: callers run this
+    // AFTER their own mutations and only handle the structured form, so an
+    // escaping exception would abort the whole iterate_fix/iterate_prune call.
     try {
+      const filePath = logPath(projectRoot)
       const line = JSON.stringify(entry) + '\n'
       const prevSize = existsSync(filePath) ? statSync(filePath).size : 0
       appendFileSync(filePath, line, 'utf-8')
       // Count entries via the size/count cache: when nothing else changed the
       // file since our last append (same byte size), count is just +1 — no full
       // re-read. Falls back to a full re-count whenever the cache is stale.
-      const cached = entryCountCache.get(filePath)
-      const count = cached && cached.size === prevSize
-        ? cached.count + 1
-        : recountEntries(filePath)
-      entryCountCache.set(filePath, { size: existsSync(filePath) ? statSync(filePath).size : prevSize, count })
+      const cached = cacheGet(filePath)
+      let count: number
+      if (cached && cached.size === prevSize) {
+        count = cached.count + 1
+      } else {
+        const recounted = recountEntries(filePath)
+        if (!recounted.ok) {
+          // The append LANDED but the read-back failed (file vanished /
+          // replaced mid-call). Report the best count we actually know —
+          // cached value or 0 — and DO NOT touch the cache: caching a failed
+          // read's fallback under the new byte size would poison every later
+          // append's count.
+          return { count: recounted.count, path: filePath }
+        }
+        count = recounted.count
+      }
+      cacheSet(filePath, { size: existsSync(filePath) ? statSync(filePath).size : prevSize, count })
       return { count, path: filePath }
     } catch (err) {
       return { count: 0, path: join(projectRoot, LOG_DIR, LOG_FILE), error: `failed to append decision log: ${String(err)}` }