iterate-plugin 3.5.7 → 3.7.0

package/dist/tools/checkpoint.js

@@ -18,10 +18,27 @@ import { readDecisionEntries } from "./decision-log.js";
 import { readQualityGate } from "./quality-store.js";
 import { readExperienceBank } from "./experience-store.js";
 import { readDefenseEvents } from "./defense-store.js";
+import { asNumber, asRecord, parseRenderedJson } from "./present.js";
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
 /** Max findings persisted in a checkpoint (a model-authored findings payload is
  *  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, fallback) {
+    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) {
     const file = checkpointPath(projectRoot);
@@ -35,22 +52,28 @@ export function readCheckpoint(projectRoot) {
             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)
+        if (round === null || round < 0 || round > MAX_COUNTER)
             return null;
-        const num = (v, fallback) => typeof v === 'number' && Number.isFinite(v) ? v : fallback;
         // 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 : [],
             startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : new Date().toISOString(),
             updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
@@ -118,24 +141,31 @@ export function computeStatus(input) {
     const lastEntry = entries.length > 0 ? entries[entries.length - 1] : null;
     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,
         taskMode,
@@ -158,7 +188,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
@@ -177,6 +207,42 @@ export function computeStatus(input) {
 export function registerCheckpointTool(ctx) {
     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;
+            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. ' +
             '`resume` loads an existing checkpoint, bumps its resumeCount, and persists it back — ' +

package/dist/tools/config.js

@@ -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 { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFile, } from "../config-write.js";
@@ -86,6 +86,21 @@ export function registerConfigTool(ctx) {
             // ── Write operation ────────────────────────────────────────────────
             if (args.operation === 'write') {
                 const updates = args.updates;
+                // 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 };
@@ -132,6 +147,27 @@ export function registerConfigTool(ctx) {
             const hasOverride = source === 'override';
             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.message ?? err)}`],
+                                section: 'validation_report',
+                            };
+                        }
+                    }
+                }
                 return {
                     found: hasOverride,
                     valid: errors.length === 0,
@@ -141,7 +177,13 @@ export function registerConfigTool(ctx) {
             }
             if (args.section) {
                 const configRecord = config;
-                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]
+                    : undefined;
                 if (section === undefined) {
                     return {
                         found: hasOverride,

package/dist/tools/context.js

@@ -25,10 +25,20 @@ export function isAllowedSkillDir(skillDir, allowedRoots) {
         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 {
@@ -279,7 +289,7 @@ export function registerContextTool(ctx) {
                 .split(',')
                 .map((s) => s.trim().toLowerCase())
                 .filter(Boolean);
-            const result = { found: true, searched: [] };
+            const result = { found: false, searched: [] };
             // Relay user-attached image metadata into the review context. The
             // orchestrator observes attached images in the session and passes their
             // metadata here; invalid entries are dropped with a reported reason.
@@ -328,6 +338,13 @@ export function registerContextTool(ctx) {
             if (requested.includes('project') || requested.includes('iterate.md')) {
                 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/dist/tools/decision-log.js

@@ -2,6 +2,7 @@ import { appendFileSync, readFileSync, mkdirSync, existsSync, openSync, writeSyn
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
+import { makeLockRelease } from "../file-lock.js";
 const LOG_DIR = '.iterate';
 const LOG_FILE = 'decision-log.jsonl';
 // ─── Cross-process log mutex ────────────────────────────────────────────────
@@ -13,9 +14,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;
 const LOCK_STALE_MS = 10000;
@@ -41,15 +44,34 @@ function sleepSync(ms) {
  * 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) {
+export function acquireLogLock(projectRoot, options = {}) {
+    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, options = {}) {
+    const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
+        ? options.waitMs
+        : LOCK_WAIT_MS;
+    const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
+        ? options.staleMs
+        : 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);
@@ -61,12 +83,12 @@ export function acquireLogLock(projectRoot) {
         }
         catch (err) {
             if (err.code !== 'EEXIST')
-                return () => { };
+                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)
+                if (Date.now() - st.mtimeMs > staleMs)
                     stale = true;
                 else {
                     const pid = Number(readFileSync(lockPath, 'utf-8'));
@@ -84,12 +106,14 @@ export function acquireLogLock(projectRoot) {
                 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;
         }
         // Owned the lock: stamp the holder pid, then release once on return.
+        // The release is ownership-checked (see `makeLockRelease`): a lock stolen
+        // from this process after its owner went stale must not be unlinked by us.
         try {
             writeSync(fd, String(process.pid));
         }
@@ -98,28 +122,64 @@ export function acquireLogLock(projectRoot) {
             closeSync(fd);
         }
         catch { /* best-effort */ }
-        let released = false;
-        return () => {
-            if (released)
-                return;
-            released = true;
-            try {
-                unlinkSync(lockPath);
-            }
-            catch { /* already gone */ }
+        return {
+            acquired: true,
+            release: makeLockRelease(lockPath),
         };
     }
 }
 // ─── 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();
-/** Line-count the log file from scratch (entries = non-empty JSON lines). */
-function recountEntries(filePath) {
+/** LRU-ish get: refresh recency by re-inserting the key. */
+function cacheGet(filePath) {
+    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, value) {
+    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() {
+    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) {
     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 };
     }
 }
 /**
@@ -183,19 +243,37 @@ export function appendDecisionEntry(projectRoot, entry) {
     // 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;
+            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) {