iterate-plugin 3.5.6 → 3.6.0

package/dist/review-scope.js

@@ -22,8 +22,12 @@
  */
 import { readdirSync } from 'node:fs';
 import { join, relative } from 'node:path';
-/** Relative-scope sentinel for whole-module findings. */
-export const WHOLE_FILE_LINE = 0;
+// Single source of truth for the whole-file line sentinel: evidence.ts's gate
+// and this module's inventory filters must agree on what `0` means. Evidence
+// imports neither this module nor review.ts, so the edge is acyclic (review.ts
+// → review-scope.ts → evidence.ts → types.ts).
+import { WHOLE_FILE_LINE } from "./evidence.js";
+export { WHOLE_FILE_LINE };
 /** Source extensions a full-scope walk includes. */
 const SOURCE_EXTENSIONS = new Set([
     '.py', '.pyi', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
@@ -82,13 +86,19 @@ function isIgnoredDir(name) {
 }
 /** Collect the sorted relative-path inventory for a review scope. */
 export function collectScopeFiles(root, opts) {
+    // `opts` / `scope` come from tool args: a missing or malformed options
+    // object must degrade to a full walk, never throw inside the inventory step.
+    if (!opts || typeof opts !== 'object')
+        return collectFull(root);
     if (opts.scope === 'changed-only')
         return collectChanged(opts.changedFiles ?? []);
     return collectFull(root);
 }
 function collectChanged(changedFiles) {
+    // A non-array `changedFiles` (JSON arg) must not be iterated char-by-char.
+    const list = Array.isArray(changedFiles) ? changedFiles : [];
     const out = new Set();
-    for (const rel of changedFiles) {
+    for (const rel of list) {
         if (typeof rel !== 'string' || !rel.trim())
             continue;
         if (rel === String(WHOLE_FILE_LINE))
@@ -145,9 +155,17 @@ function collectFull(root) {
 /** Split `files` into stable batches, keeping directory runs together. */
 export function chunkFiles(files, perChunk) {
     // Number.isFinite: NaN fails `perChunk < 1` and would yield one unbounded
-    // chunk (current.length >= NaN is never true).
-    const size = Number.isFinite(perChunk) && perChunk >= 1 ? perChunk : DEFAULT_SCOPE_CHUNK_SIZE;
-    const ordered = [...files].sort();
+    // chunk (current.length >= NaN is never true). Math.floor: a fractional
+    // size (2.5) made chunks alternate between 2 and 3 members — the caller's
+    // "files per batch" is a count, so it must be an integer.
+    const size = Number.isFinite(perChunk) && perChunk >= 1
+        ? Math.floor(perChunk)
+        : DEFAULT_SCOPE_CHUNK_SIZE;
+    // A non-array / sparse-free copy: callers pass tool-arg JSON, and sort()
+    // on a non-array (or `rel.includes` on a number) would throw.
+    const ordered = (Array.isArray(files) ? files : [])
+        .filter((rel) => typeof rel === 'string')
+        .sort();
     const chunks = [];
     let current = [];
     let lastDir;
@@ -172,19 +190,24 @@ export function chunkFiles(files, perChunk) {
 }
 /** Score self-reported reads against the assigned inventory. */
 export function computeCoverage(assigned, readFiles) {
+    // Both lists are JSON-arg-derived: `for...of` over a bare number throws and
+    // over a bare string iterates single characters into the read set. Anything
+    // non-array behaves like "nothing" (empty inventory / nothing read).
+    const assignedList = Array.isArray(assigned) ? assigned : [];
+    const readList = Array.isArray(readFiles) ? readFiles : [];
     const readNorm = new Set();
-    for (const p of readFiles ?? []) {
+    for (const p of readList) {
         if (typeof p === 'string' && p)
             readNorm.add(normalizePath(p));
     }
-    const assignedSorted = [...assigned].sort();
+    const assignedSorted = [...assignedList].filter((rel) => typeof rel === 'string').sort();
     const covered = assignedSorted.filter((rel) => readNorm.has(normalizePath(rel)));
     const uncovered = assignedSorted.filter((rel) => !readNorm.has(normalizePath(rel)));
     const rawRatio = assignedSorted.length === 0 ? 1 : covered.length / assignedSorted.length;
     const ratio = Math.round(rawRatio * 1000) / 1000;
     return {
         assigned: assignedSorted,
-        read: [...new Set((readFiles ?? []).filter((p) => typeof p === 'string'))].sort(),
+        read: [...new Set(readList.filter((p) => typeof p === 'string'))].sort(),
         covered,
         uncovered,
         ratio,

package/dist/review.js

@@ -44,9 +44,44 @@ export function sortFindings(findings) {
         return (Number(a?.line) || 0) - (Number(b?.line) || 0);
     });
 }
+/**
+ * Hard ceiling on the round cap the aggregation math will honor.
+ *
+ * Mirrors `MAX_MAX_ROUNDS` in `config-loader.ts` (the config bomb guard) —
+ * `test/review.test.ts` asserts the two constants stay in sync. The tool
+ * boundary only clamps the LOWER bound of `maxReviewRounds`, so an absurd
+ * caller value (1e15) would otherwise drive the `findingsByRound` allocation
+ * bound (`roundCap * 2`) straight into OOM territory.
+ */
+export const MAX_REVIEW_ROUNDS_CAP = 100;
+/**
+ * Clamp an untrusted round cap to `[1, MAX_REVIEW_ROUNDS_CAP]`.
+ *
+ * Non-finite / non-numeric input (`NaN`, `Infinity`, a string) collapses to
+ * 1 — the smallest sane cap. Without this, `Math.max(1, NaN)` stayed `NaN`
+ * and `new Array(NaN)` threw `RangeError` out of `aggregateRounds`.
+ */
+export function clampMaxReviewRounds(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 1;
+    return Math.min(MAX_REVIEW_ROUNDS_CAP, Math.max(1, Math.floor(value)));
+}
+/**
+ * True when `n` is a round number the deterministic core accepts: a positive
+ * integer. Shared by `aggregateRounds` / `computeConvergence` /
+ * `buildReviewReport` (and re-read by the meta-review audit) so every reader
+ * of "the last round" agrees on which round numbers count — a fractional
+ * (`1.5`) or non-finite round is simply "not a round", never a convergence
+ * input that could be mis-indexed into `findingsByRound`.
+ */
+export function isValidRoundNumber(n) {
+    return typeof n === 'number' && Number.isInteger(n) && n >= 1;
+}
 /** Normalize a summary so near-identical duplicates collapse to one key. */
 export function normalizeSummary(summary) {
-    return summary
+    // Coerce: `summary` is model-authored JSON when schema validation is off,
+    // so a numeric summary must not crash `.trim()` inside the dedupe key.
+    return String(summary ?? '')
         .trim()
         .toLowerCase()
         .replace(/[\s\n\t]+/g, ' ');
@@ -58,8 +93,12 @@ export function normalizeSummary(summary) {
  * neither side anchors one, i.e. whole-file findings).
  */
 export function findingKey(f) {
-    const line = typeof f.line === 'number' && f.line > 0 ? f.line : 0;
-    return `${f.file}|${f.dimension}|${line}|${normalizeSummary(f.summary)}`;
+    // Defensive reads: with `output_schema_validation: false` a finding may
+    // carry wrong-typed fields (and `f` itself may be a null list element), and
+    // this key feeds the dedupe Set on EVERY round — it must never throw.
+    const src = (f ?? {});
+    const line = typeof src.line === 'number' && src.line > 0 ? src.line : 0;
+    return `${String(src.file ?? '')}|${String(src.dimension ?? '')}|${line}|${normalizeSummary(src.summary)}`;
 }
 /**
  * Remove duplicate findings within a list.
@@ -69,6 +108,10 @@ export function dedupeFindings(findings) {
     const seen = new Set();
     const out = [];
     for (const f of findings) {
+        // A null / array entry (hostile or schema-validation-off JSON) must never
+        // reach `summarize`, which reads `f.severity` unguarded.
+        if (!f || typeof f !== 'object' || Array.isArray(f))
+            continue;
         const key = findingKey(f);
         if (seen.has(key))
             continue;
@@ -84,10 +127,19 @@ export function dedupeFindings(findings) {
  *  - entry `line` is 0/undefined (whole file) OR equals the finding's line.
  */
 export function filterKnownIntentional(findings, known) {
-    if (!known || known.length === 0)
+    // `known` is config/arg JSON: a non-array truthy value must behave like
+    // "no entries", never reach `known.some` and throw.
+    if (!Array.isArray(known) || known.length === 0)
         return findings;
     return findings.filter((f) => {
+        // A null / non-object finding has no file/dimension to match on; drop it
+        // here so it can never crash the comparator (aggregateRounds drops it too,
+        // so the report's counts stay consistent either way).
+        if (!f || typeof f !== 'object' || Array.isArray(f))
+            return false;
         const matched = known.some((k) => {
+            if (!k || typeof k !== 'object')
+                return false;
             const sameFile = k.file === f.file;
             const sameDim = k.dimension === f.dimension;
             if (!sameFile || !sameDim)
@@ -124,16 +176,25 @@ export function aggregateRounds(rounds, maxReviewRounds) {
     // 1e9) would otherwise allocate an array of that size below (OOM). Round
     // numbers above the configured cap are clamped to the cap.
     let maxRound = 0;
-    const roundCap = Math.max(1, maxReviewRounds);
-    for (const round of rounds) {
+    // Upper-bounded too: `Math.max(1, NaN)` used to stay NaN and blow up in
+    // `new Array(effectiveMax)`, and an unbounded cap scaled the allocation
+    // bound to whatever the caller asked for.
+    const roundCap = clampMaxReviewRounds(maxReviewRounds);
+    for (const round of Array.isArray(rounds) ? rounds : []) {
         if (!round || typeof round !== 'object')
             continue;
-        if (typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1)
+        if (!isValidRoundNumber(round.round))
             continue;
         const findings = Array.isArray(round.findings) ? round.findings : [];
         if (round.round > maxRound)
             maxRound = round.round;
         for (const f of findings) {
+            // Null / non-object elements (schema validation off) would crash
+            // `findingKey`; dropping them here keeps `findingsByRound` summing to
+            // exactly the returned findings list (the meta-review's CONVERGENCE_SUM
+            // check reads that equality).
+            if (!f || typeof f !== 'object' || Array.isArray(f))
+                continue;
             const key = findingKey(f);
             if (seen.has(key))
                 continue;
@@ -162,8 +223,9 @@ export function aggregateRounds(rounds, maxReviewRounds) {
  * Compute convergence statistics for a dry-run review.
  */
 export function computeConvergence(rounds, maxReviewRounds) {
-    const { findingsByRound } = aggregateRounds(rounds, maxReviewRounds);
-    const totalRounds = rounds.length;
+    const list = Array.isArray(rounds) ? rounds : [];
+    const { findingsByRound } = aggregateRounds(list, maxReviewRounds);
+    const totalRounds = list.length;
     // `findingsByRound` is indexed by the actual round number (round r → index
     // r-1), sized to the highest present round (clamped). Convergence must read
     // the HIGHEST PRESENT round's count — not the last array element (rounds
@@ -171,15 +233,17 @@ export function computeConvergence(rounds, maxReviewRounds) {
     // 1..N). The count index is bounded by the array length aggregateRounds
     // actually allocated.
     let lastRound = 0;
-    for (const round of rounds) {
-        if (!round || typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1)
+    for (const round of list) {
+        if (!isValidRoundNumber(round?.round))
             continue;
         if (round.round > lastRound)
             lastRound = round.round;
     }
     const idx = Math.min(lastRound, findingsByRound.length) - 1;
     const lastRoundCount = idx >= 0 ? (findingsByRound[idx] ?? 0) : 0;
-    const converged = totalRounds > 0 && lastRoundCount === 0;
+    // `lastRound === 0` means NO round carried an interpretable number: claiming
+    // `converged` there would bless a report the core could not actually read.
+    const converged = totalRounds > 0 && lastRound > 0 && lastRoundCount === 0;
     return {
         totalRounds,
         findingsByRound,
@@ -199,7 +263,15 @@ function summarize(findings) {
         high: 0,
         medium: 0,
         low: 0,
-        byDimension: {},
+        // NULL-PROTOTYPE map: a model-authored `dimension` of `__proto__` or
+        // `constructor` would otherwise resolve against Object.prototype — the
+        // `__proto__` setter silently discards a primitive value and `constructor`
+        // string-concatenates the Object function — so the counter never
+        // accumulated and the meta-review's DIMENSION_SUM check false-positived.
+        // A null-prototype object has no inherited accessors, so every dimension
+        // (including those three names) is a plain own data property and
+        // JSON-serializes normally.
+        byDimension: Object.create(null),
     };
     for (const f of findings) {
         if (f.severity === 'critical')
@@ -223,7 +295,8 @@ function summarize(findings) {
  */
 export function buildReviewReport(input) {
     // 1. Filter known-intentional per round (before cross-round dedupe).
-    const filteredRounds = input.rounds
+    const inputRounds = Array.isArray(input.rounds) ? input.rounds : [];
+    const filteredRounds = inputRounds
         .map((r) => ({
         round: typeof r?.round === 'number' ? r.round : 0,
         findings: filterKnownIntentional(Array.isArray(r?.findings) ? r.findings : [], input.knownIntentional),
@@ -246,7 +319,11 @@ export function buildReviewReport(input) {
     //    non-contiguous round sets would otherwise read the wrong count).
     let lastRound = 0;
     for (const r of filteredRounds) {
-        if (typeof r.round === 'number' && r.round > lastRound)
+        // Same validity rule as aggregateRounds: a fractional / NaN round is not
+        // a round, so it must never be used as an index into `findingsByRound`
+        // (Math.min(1.5, len) - 1 = 0.5 → reads `undefined` → counts as 0 new →
+        // a round that really did report findings would be read as "converged").
+        if (isValidRoundNumber(r.round) && r.round > lastRound)
             lastRound = r.round;
     }
     // `lastRound` can exceed the array length when over-cap rounds were FOLDED
@@ -255,7 +332,7 @@ export function buildReviewReport(input) {
     // new findings (which would falsely report "converged").
     const idx = Math.min(lastRound, findingsByRound.length) - 1;
     const lastRoundCount = lastRound > 0 && idx >= 0 ? (findingsByRound[idx] ?? 0) : 0;
-    const converged = filteredRounds.length > 0 && lastRoundCount === 0;
+    const converged = filteredRounds.length > 0 && lastRound > 0 && lastRoundCount === 0;
     // Attach the normal-mode fix count to the summary (dry-run leaves it absent).
     const computed = summarize(sorted);
     if (input.mode === 'normal' && typeof input.fixedCount === 'number' && Number.isInteger(input.fixedCount)) {
@@ -659,7 +736,9 @@ export function buildReviewPlan(input) {
         goal,
         scope,
         dimensions: dimensionTasks,
-        maxReviewRounds: input.maxReviewRounds,
+        // Clamped with the SAME rule aggregateRounds honors, so the cap this plan
+        // advertises is never a number the aggregation math would silently clamp.
+        maxReviewRounds: clampMaxReviewRounds(input.maxReviewRounds),
         knownIntentional: input.knownIntentional ?? [],
         changedFiles: effectiveChangedOnly ? changedFiles : [],
         fallbackToFull,

package/dist/session-hooks.js

@@ -3,7 +3,8 @@
  *
  * Wires the {@link decideApproval} policy gate to dsh's `tools/pre-execute`
  * waterfall. This is the AUTHORITATIVE approval seam for destructive iterate
- * tools (`iterate_fix` / `iterate_rollback` / `iterate_prune` with dryRun:false):
+ * tools (`iterate_fix` / `iterate_rollback` / `iterate_prune` with dryRun:false
+ * / `iterate_config` with operation:"write"):
  *
  *   - `allow` policy      → the call runs.
  *   - `deny`  policy      → the call is refused (fail-closed), surfaced as an
@@ -13,11 +14,19 @@
  *                           plus the human-readable reason) so durable
  *                           projections can route it distinctly from a normal
  *                           tool failure.
- *   - `ask`   policy      → return `{ kind: 'ask', reason }`; dsh's own
- *                           scheduler routes it through the `approval` service
- *                           (see `@deepseek-ai/dsh-user-approval`), which
- *                           prompts the human and audits an approve/deny pair
- *                           on the session.
+ *   - `ask`   policy      → return `{ kind: 'ask', reason, displayReason }`;
+ *                           dsh's own scheduler routes it through the
+ *                           `approval` service (see
+ *                           `@deepseek-ai/dsh-user-approval`), which prompts
+ *                           the human and audits an approve/deny pair on the
+ *                           session. `reason` is the audited English summary;
+ *                           `displayReason` (dsh 0.2.x) is the localized
+ *                           prompt text. LANGUAGE RULE: human-facing text
+ *                           follows the project `language` (zh|en); every
+ *                           structured/durable field (deny reason,
+ *                           `info.reason`, decision-log entries, console
+ *                           logs) stays English so machine matchers never
+ *                           depend on a locale.
  *   - canceled            → if the caller aborted the invocation before
  *                           dispatch, return `{ kind: 'cancel' }` (the
  *                           canonical 0.1.6-alpha.1 cancellation result) so a
@@ -31,7 +40,15 @@
  *
  * Safety properties:
  *   - Read-only tools and non-iterate tools are always allowed (the gate only
- *     inspects the three destructive iterate toolnames).
+ *     inspects the four gated iterate toolnames, and of those only prune
+ *     `dryRun:false` and `iterate_config` `operation:"write"` — a config read
+ *     or a dry-run prune short-circuits to allow inside the policy gate).
+ *   - The approval policy is read from the SESSION workspace whenever a
+ *     session cwd is known — the model-controlled `path` argument can never
+ *     choose where the human's policy comes from (it is only consulted when
+ *     there is no session cwd at all). Otherwise `path:` could point at an
+ *     `approval: allow` directory to self-grant, or dodge a `deny` in the
+ *     workspace.
  *   - If the project root / observatory config cannot be resolved, the policy
  *     degrades to `ask` (fail-safe: destructive writes always require consent).
  */
@@ -77,8 +94,14 @@ export function gateDecision(exec) {
     if (signal && typeof signal.aborted === 'boolean' && signal.aborted) {
         return { kind: 'cancel' };
     }
-    // Resolve the project root (use the call's own `path` arg, else the agent's
-    // session cwd) to read the effective observatory policy.
+    // Resolve the project root whose observatory policy governs this call.
+    // SECURITY: the policy source must NOT be model-controlled. `path` is a
+    // model argument, so reading the policy from the path-resolved root let a
+    // call point `path:` at a directory with `approval: allow` (self-grant) or
+    // dodge a human's `deny` in the session workspace. When the session cwd is
+    // known, the SESSION workspace's config is authoritative and `path` is
+    // ignored; the path-resolved root is only the fallback when there is no
+    // session cwd at all (headless/tests). The `ask` default stays fail-closed.
     let argPath;
     let sessionCwd;
     try {
@@ -93,8 +116,15 @@ export function gateDecision(exec) {
     catch {
         // hostile/proxied exec — fall through with both undefined (defaults to ask)
     }
-    const resolved = resolveProjectRoot(argPath, sessionCwd);
+    // Passing sessionCwd as BOTH the input and the anchor makes the root the
+    // session cwd itself (no server-cwd fallback can sneak in), anchored there.
+    const resolved = sessionCwd
+        ? resolveProjectRoot(sessionCwd, sessionCwd)
+        : resolveProjectRoot(argPath, sessionCwd);
     let policy = 'ask';
+    // Project language for the HUMAN-FACING ask prompt only (see the header's
+    // language rule: structured deny/audit text stays English).
+    let language = 'en';
     if (resolved.ok) {
         const { config } = loadEffectiveConfig(resolved.root);
         const p = config.observatory?.approval;
@@ -103,8 +133,10 @@ export function gateDecision(exec) {
         else if (p === 'allow')
             policy = 'allow';
         // anything else (including a corrupt/missing `ask`) → 'ask'
+        if (config.language === 'zh')
+            language = 'zh';
     }
-    const decision = decideApproval(exec, policy);
+    const decision = decideApproval(exec, policy, language);
     if (decision.kind === 'deny') {
         return {
             kind: 'deny',
@@ -113,12 +145,19 @@ export function gateDecision(exec) {
                 ...DENY_INFO,
                 // ToolErrorInfo.reason (0.1.6-alpha.1): raw user-facing detail kept in
                 // durable state; the model-facing text still only sees `reason` above.
+                // Deliberately the ENGLISH structured reason, never the localized
+                // prompt — durable projections must match on a stable string.
                 reason: decision.reason,
             },
         };
     }
-    if (decision.kind === 'ask')
-        return { kind: 'ask', reason: decision.reason };
+    // dsh 0.2.x: `displayReason` is the localized prompt text (en + the
+    // configured locale); `reason` stays the audited English summary. Both are
+    // forwarded so the approval UI can show the full localized explanation
+    // (including the WARNING line for gate-disabling config writes).
+    if (decision.kind === 'ask') {
+        return { kind: 'ask', reason: decision.reason, displayReason: decision.displayReason };
+    }
     return { kind: 'allow' };
 }
 /**
@@ -139,6 +178,9 @@ export function registerSessionHooks(ctx) {
             return Promise.resolve({
                 kind: 'ask',
                 reason: 'iterate approval gate unavailable — require consent',
+                // Fail-safe path: no config was read, so the localized prompt falls
+                // back to English (displayReason requires at least an `en` entry).
+                displayReason: { en: 'iterate approval gate unavailable — require consent' },
             });
         }
         if (decision.kind === 'ask') {