iterate-plugin 2.9.0 → 2.9.2

package/dist/config-loader.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
 import yaml from 'js-yaml';
 /**
@@ -168,9 +169,46 @@ export function validateConfig(config) {
  */
 export function resolveProjectRoot(input) {
     const raw = (input ?? '').trim();
-    const root = raw ? resolve(raw) : resolve(process.cwd());
+    const root = raw ? resolve(raw) : resolve(effectiveCwd());
     if (!root || root === sep) {
         return { ok: false, reason: 'Refusing filesystem root as project root.' };
     }
     return { ok: true, root };
 }
+/**
+ * Resolve the default working directory for tools invoked without an explicit
+ * `path`. Prefers the process cwd, but a daemon-managed web server can start
+ * with cwd = `/` (e.g. launchd), which is not a usable project root. In that
+ * case fall back to the session workspace encoded in `DSH_SESSION_JSONL`
+ * (`…/sessions/<encoded-workspace>/<session-id>/session.jsonl.zstd`), where
+ * the workspace directory is `--`-wrapped with `/` → `-` and percent-encoded
+ * bytes spelled as `~<hex>` (e.g. `/Volumes/Eng-Dev/iterate-skill` →
+ * `--Volumes-Eng-Dev-iterate-skill--`).
+ */
+function effectiveCwd() {
+    let cwd = '';
+    try {
+        cwd = process.cwd();
+    }
+    catch {
+        // cwd may be unreadable (deleted dir) — fall through to session workspace
+    }
+    if (cwd && cwd !== sep && cwd !== homedir())
+        return cwd;
+    const session = process.env.DSH_SESSION_JSONL;
+    if (session) {
+        const m = session.match(/\/sessions\/([^/]+)\//);
+        const encoded = m ? m[1] : undefined;
+        if (encoded && encoded.startsWith('--') && encoded.endsWith('--')) {
+            try {
+                const decoded = decodeURIComponent(encoded.slice(2, -2).replace(/~/g, '%'));
+                if (decoded && decoded.startsWith(sep))
+                    return decoded;
+            }
+            catch {
+                // malformed encoding — fall through to cwd
+            }
+        }
+    }
+    return cwd || sep;
+}

package/dist/skill-prompt.js

@@ -90,7 +90,7 @@ for (let r = 1; r <= maxRounds; r++) {
       : ''
     const raw = await parallel(dims.map(dim => () => agent(
       'Review dimension "' + dim + '".' +
-      (attachments.length > 0 ? ' User-attached images are part of the evidence (reproduce/verify against them): ' + JSON.stringify(attachments) + '.' : '') +
+      (attachments.length > 0 ? ' User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
       ' Already-known findings (do NOT re-report): ' +
       JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.',
       Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
@@ -190,11 +190,13 @@ const checkpoint = (ckRes && ckRes.checkpoint) ? ckRes.checkpoint : null
 const startRound = (checkpoint && typeof checkpoint.round === 'number') ? checkpoint.round + 1 : 1
 // Track how many times this checkpoint has already been resumed (interruption recovery).
 const resumeCount = (checkpoint && typeof checkpoint.resumeCount === 'number') ? checkpoint.resumeCount : 0
+// The effective count AFTER this recovery: this run counts as one more resume.
+const effectiveResumeCount = checkpoint ? resumeCount + 1 : 0
 if (checkpoint) {
   // A previous run left a checkpoint — record the recovery so the decision log
   // shows the resume, then continue where it left off.
   await agent(
-    'Call iterate_decision_log({operation:"append", type:"resume", round:' + startRound + ', data:{resumedFromRound:' + checkpoint.round + ', resumeCount:' + (resumeCount + 1) + '}})',
+    'Call iterate_decision_log({operation:"append", type:"resume", round:' + startRound + ', data:{resumedFromRound:' + checkpoint.round + ', resumeCount:' + effectiveResumeCount + '}})',
     Object.assign({ label: 'log:resume' }, backend)
   )
 }
@@ -216,7 +218,8 @@ const knownIntentional = (plan.knownIntentional || [])   // config personalizati
 const dims = plan.dimensions.map(d => d.id)
 const maxRounds = plan.maxReviewRounds
 const rounds = []          // findings per review round (each on the then-current code state)
-const architectural = []   // findings deliberately left unfixed (reported at the end)
+// Restore previously-unfixed architectural findings when resuming an interrupted run.
+const architectural = (checkpoint && Array.isArray(checkpoint.findings)) ? checkpoint.findings : []   // findings deliberately left unfixed (reported at the end)
 let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? checkpoint.fixedCount : 0
 let converged = false
 let abortedByValidation = false
@@ -235,7 +238,7 @@ for (let r = startRound; r <= maxRounds; r++) {
       : ''
     const raw = await parallel(dims.map(dim => () => agent(
       'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed). ' +
-      (attachments.length > 0 ? ' User-attached images are part of the evidence (reproduce/verify against them): ' + JSON.stringify(attachments) + '.' : '') +
+      (attachments.length > 0 ? ' User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
       'Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.',
       Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
     )))
@@ -341,7 +344,7 @@ for (let r = startRound; r <= maxRounds; r++) {
 
   // Persist progress so an interrupted run can resume from the next round.
   await agent(
-    'Call iterate_checkpoint({ operation: "save", mode: "normal", round:' + r + ', maxRounds:' + maxRounds + ', fixedCount:' + fixedCount + ', architecturalCount:' + architectural.length + ', resumeCount:' + resumeCount + ', findings:' + JSON.stringify(architectural) + ' }) and return the checkpoint JSON.',
+    'Call iterate_checkpoint({ operation: "save", mode: "normal", round:' + r + ', maxRounds:' + maxRounds + ', fixedCount:' + fixedCount + ', architecturalCount:' + architectural.length + ', resumeCount:' + effectiveResumeCount + ', findings:' + JSON.stringify(architectural) + ' }) and return the checkpoint JSON.',
     Object.assign({ label: 'checkpoint:save:r' + r }, backend)
   )
 

package/dist/tools/checkpoint.js

@@ -149,7 +149,7 @@ export function registerCheckpointTool(ctx) {
             const projectRoot = resolved.root;
             if (args.operation === 'load') {
                 const checkpoint = readCheckpoint(projectRoot);
-                return { operation: 'load', ok: true, checkpoint: checkpoint ?? undefined };
+                return { operation: 'load', ok: true, checkpoint: checkpoint };
             }
             if (args.operation === 'clear') {
                 const existed = existsSync(checkpointPath(projectRoot));
@@ -217,7 +217,7 @@ export function registerStatusTool(ctx) {
                 additionalProperties: false,
                 properties: {
                     ok: { type: 'boolean', required: true },
-                    mode: { type: 'string' },
+                    mode: { oneOf: [{ type: 'string' }, { type: 'null' }] },
                     currentRound: { type: 'integer' },
                     totalRounds: { type: 'integer' },
                     fixedCount: { type: 'integer' },
@@ -227,7 +227,7 @@ export function registerStatusTool(ctx) {
                     hasCheckpoint: { type: 'boolean' },
                     interrupted: { type: 'boolean', description: 'True when a checkpoint exists, meaning the previous run was interrupted before finishing.' },
                     resumeCount: { type: 'integer', description: 'How many times the current checkpoint has already been resumed.' },
-                    lastUpdated: { type: 'string' },
+                    lastUpdated: { oneOf: [{ type: 'string' }, { type: 'null' }] },
                     error: { type: 'string' },
                 },
             },
@@ -258,7 +258,7 @@ export function registerStatusTool(ctx) {
             });
             return {
                 ok: true,
-                mode: status.mode ?? undefined,
+                mode: status.mode ?? null,
                 currentRound: status.currentRound,
                 totalRounds: status.totalRounds,
                 fixedCount: status.fixedCount,
@@ -268,7 +268,7 @@ export function registerStatusTool(ctx) {
                 hasCheckpoint: status.hasCheckpoint,
                 interrupted: status.interrupted,
                 resumeCount: status.resumeCount,
-                lastUpdated: status.lastUpdated ?? undefined,
+                lastUpdated: status.lastUpdated ?? null,
             };
         },
     }));

package/dist/tools/config.js

@@ -47,14 +47,14 @@ export function registerConfigTool(ctx) {
                 properties: {
                     found: { type: 'boolean', required: true },
                     valid: { type: 'boolean' },
-                    errors: { type: 'array', items: { type: 'string' } },
+                    errors: { oneOf: [{ type: 'array', items: { type: 'string' } }, { type: 'null' }] },
                     section: { type: 'string' },
                     data: { type: 'json' },
                     config: { type: 'json' },
                     availableSections: { type: 'array', items: { type: 'string' } },
                     operation: { type: 'string' },
                     ok: { type: 'boolean' },
-                    backupPath: { type: 'string' },
+                    backupPath: { oneOf: [{ type: 'string' }, { type: 'null' }] },
                     error: { type: 'string' },
                 },
             },
@@ -100,7 +100,7 @@ export function registerConfigTool(ctx) {
                     operation: 'write',
                     ok: true,
                     found: true,
-                    backupPath: result.backupPath ?? undefined,
+                    backupPath: result.backupPath ?? null,
                     config: config,
                 };
             }
@@ -112,7 +112,7 @@ export function registerConfigTool(ctx) {
                 return {
                     found: hasOverride,
                     valid: errors.length === 0,
-                    errors: errors.length > 0 ? errors : undefined,
+                    errors: errors.length > 0 ? errors : null,
                     section: 'validation_report',
                 };
             }

package/dist/tools/context.js

@@ -7,6 +7,8 @@ import { resolveProjectRoot } from "../config-loader.js";
 const MAX_SKILL_DIR_LOOKUP_DEPTH = 12;
 /** Maximum number of image attachments relayed into the context in one call. */
 const MAX_ATTACHMENTS = 8;
+/** Maximum intrinsic width/height (px) accepted for an attached image. */
+const MAX_ATTACHMENT_DIMENSION = 16384;
 /**
  * Validate and normalize one raw image-attachment entry passed by the
  * orchestrator. The top-level model observes user-attached images in its own
@@ -33,8 +35,8 @@ export function normalizeAttachment(raw) {
     }
     for (const dim of ['width', 'height']) {
         if (entry[dim] !== undefined) {
-            if (typeof entry[dim] !== 'number' || !Number.isInteger(entry[dim]) || entry[dim] < 0 || entry[dim] > 16384) {
-                return { ok: false, error: `attachment.${dim} must be an integer in [0, 16384]` };
+            if (typeof entry[dim] !== 'number' || !Number.isInteger(entry[dim]) || entry[dim] < 0 || entry[dim] > MAX_ATTACHMENT_DIMENSION) {
+                return { ok: false, error: `attachment.${dim} must be an integer in [0, ${MAX_ATTACHMENT_DIMENSION}]` };
             }
             out[dim] = entry[dim];
         }

package/dist/tools/review.js

@@ -182,7 +182,7 @@ export function registerReviewTool(ctx) {
                     operation: 'aggregate',
                     mode,
                     report: report,
-                    schemaValidation: schemaValidation,
+                    schemaValidation: (schemaValidation ?? null),
                 };
             }
             if (args.operation === 'meta-review') {

package/dist/tools/triage.js

@@ -262,7 +262,7 @@ export function registerTriageTool(ctx) {
                     skipped: { type: 'integer' },
                     count: { type: 'integer' },
                     path: { type: 'string' },
-                    backupPath: { type: 'string' },
+                    backupPath: { oneOf: [{ type: 'string' }, { type: 'null' }] },
                     entries: { type: 'json' },
                     errors: { type: 'array', items: { type: 'string' } },
                     error: { type: 'string' },
@@ -321,7 +321,7 @@ export function registerTriageTool(ctx) {
                     skipped: result.skipped,
                     count: result.count,
                     path: result.configPath,
-                    backupPath: result.backupPath ?? undefined,
+                    backupPath: result.backupPath ?? null,
                 };
             }
             return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.9.0",
+  "version": "2.9.2",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus a dry-run pure-review mode with multi-round convergence and a meta-review that audits the report and emits a final review report.",
   "type": "module",
   "license": "MIT",

package/src/config-loader.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
 import yaml from 'js-yaml'
 import type { IterateConfig } from './types.ts'
@@ -185,9 +186,43 @@ export type ProjectRootResult = { ok: true; root: string } | { ok: false; reason
  */
 export function resolveProjectRoot(input?: string): ProjectRootResult {
   const raw = (input ?? '').trim()
-  const root = raw ? resolve(raw) : resolve(process.cwd())
+  const root = raw ? resolve(raw) : resolve(effectiveCwd())
   if (!root || root === sep) {
     return { ok: false, reason: 'Refusing filesystem root as project root.' }
   }
   return { ok: true, root }
+}
+
+/**
+ * Resolve the default working directory for tools invoked without an explicit
+ * `path`. Prefers the process cwd, but a daemon-managed web server can start
+ * with cwd = `/` (e.g. launchd), which is not a usable project root. In that
+ * case fall back to the session workspace encoded in `DSH_SESSION_JSONL`
+ * (`…/sessions/<encoded-workspace>/<session-id>/session.jsonl.zstd`), where
+ * the workspace directory is `--`-wrapped with `/` → `-` and percent-encoded
+ * bytes spelled as `~<hex>` (e.g. `/Volumes/Eng-Dev/iterate-skill` →
+ * `--Volumes-Eng-Dev-iterate-skill--`).
+ */
+function effectiveCwd(): string {
+  let cwd = ''
+  try {
+    cwd = process.cwd()
+  } catch {
+    // cwd may be unreadable (deleted dir) — fall through to session workspace
+  }
+  if (cwd && cwd !== sep && cwd !== homedir()) return cwd
+  const session = process.env.DSH_SESSION_JSONL
+  if (session) {
+    const m = session.match(/\/sessions\/([^/]+)\//)
+    const encoded = m ? m[1] : undefined
+    if (encoded && encoded.startsWith('--') && encoded.endsWith('--')) {
+      try {
+        const decoded = decodeURIComponent(encoded.slice(2, -2).replace(/~/g, '%'))
+        if (decoded && decoded.startsWith(sep)) return decoded
+      } catch {
+        // malformed encoding — fall through to cwd
+      }
+    }
+  }
+  return cwd || sep
 }

package/src/skill-prompt.ts

@@ -91,7 +91,7 @@ for (let r = 1; r <= maxRounds; r++) {
       : ''
     const raw = await parallel(dims.map(dim => () => agent(
       'Review dimension "' + dim + '".' +
-      (attachments.length > 0 ? ' User-attached images are part of the evidence (reproduce/verify against them): ' + JSON.stringify(attachments) + '.' : '') +
+      (attachments.length > 0 ? ' User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
       ' Already-known findings (do NOT re-report): ' +
       JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.',
       Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
@@ -191,11 +191,13 @@ const checkpoint = (ckRes && ckRes.checkpoint) ? ckRes.checkpoint : null
 const startRound = (checkpoint && typeof checkpoint.round === 'number') ? checkpoint.round + 1 : 1
 // Track how many times this checkpoint has already been resumed (interruption recovery).
 const resumeCount = (checkpoint && typeof checkpoint.resumeCount === 'number') ? checkpoint.resumeCount : 0
+// The effective count AFTER this recovery: this run counts as one more resume.
+const effectiveResumeCount = checkpoint ? resumeCount + 1 : 0
 if (checkpoint) {
   // A previous run left a checkpoint — record the recovery so the decision log
   // shows the resume, then continue where it left off.
   await agent(
-    'Call iterate_decision_log({operation:"append", type:"resume", round:' + startRound + ', data:{resumedFromRound:' + checkpoint.round + ', resumeCount:' + (resumeCount + 1) + '}})',
+    'Call iterate_decision_log({operation:"append", type:"resume", round:' + startRound + ', data:{resumedFromRound:' + checkpoint.round + ', resumeCount:' + effectiveResumeCount + '}})',
     Object.assign({ label: 'log:resume' }, backend)
   )
 }
@@ -217,7 +219,8 @@ const knownIntentional = (plan.knownIntentional || [])   // config personalizati
 const dims = plan.dimensions.map(d => d.id)
 const maxRounds = plan.maxReviewRounds
 const rounds = []          // findings per review round (each on the then-current code state)
-const architectural = []   // findings deliberately left unfixed (reported at the end)
+// Restore previously-unfixed architectural findings when resuming an interrupted run.
+const architectural = (checkpoint && Array.isArray(checkpoint.findings)) ? checkpoint.findings : []   // findings deliberately left unfixed (reported at the end)
 let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? checkpoint.fixedCount : 0
 let converged = false
 let abortedByValidation = false
@@ -236,7 +239,7 @@ for (let r = startRound; r <= maxRounds; r++) {
       : ''
     const raw = await parallel(dims.map(dim => () => agent(
       'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed). ' +
-      (attachments.length > 0 ? ' User-attached images are part of the evidence (reproduce/verify against them): ' + JSON.stringify(attachments) + '.' : '') +
+      (attachments.length > 0 ? ' User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
       'Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.',
       Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
     )))
@@ -342,7 +345,7 @@ for (let r = startRound; r <= maxRounds; r++) {
 
   // Persist progress so an interrupted run can resume from the next round.
   await agent(
-    'Call iterate_checkpoint({ operation: "save", mode: "normal", round:' + r + ', maxRounds:' + maxRounds + ', fixedCount:' + fixedCount + ', architecturalCount:' + architectural.length + ', resumeCount:' + resumeCount + ', findings:' + JSON.stringify(architectural) + ' }) and return the checkpoint JSON.',
+    'Call iterate_checkpoint({ operation: "save", mode: "normal", round:' + r + ', maxRounds:' + maxRounds + ', fixedCount:' + fixedCount + ', architecturalCount:' + architectural.length + ', resumeCount:' + effectiveResumeCount + ', findings:' + JSON.stringify(architectural) + ' }) and return the checkpoint JSON.',
     Object.assign({ label: 'checkpoint:save:r' + r }, backend)
   )
 

package/src/tools/checkpoint.ts

@@ -173,7 +173,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
 
         if (args.operation === 'load') {
           const checkpoint = readCheckpoint(projectRoot)
-          return { operation: 'load', ok: true, checkpoint: (checkpoint as unknown as JsonValue | null) ?? undefined }
+          return { operation: 'load', ok: true, checkpoint: checkpoint as unknown as JsonValue | null }
         }
 
         if (args.operation === 'clear') {
@@ -245,7 +245,7 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
           additionalProperties: false,
           properties: {
             ok: { type: 'boolean', required: true },
-            mode: { type: 'string' },
+            mode: { oneOf: [{ type: 'string' }, { type: 'null' }] },
             currentRound: { type: 'integer' },
             totalRounds: { type: 'integer' },
             fixedCount: { type: 'integer' },
@@ -255,7 +255,7 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
             hasCheckpoint: { type: 'boolean' },
             interrupted: { type: 'boolean', description: 'True when a checkpoint exists, meaning the previous run was interrupted before finishing.' },
             resumeCount: { type: 'integer', description: 'How many times the current checkpoint has already been resumed.' },
-            lastUpdated: { type: 'string' },
+            lastUpdated: { oneOf: [{ type: 'string' }, { type: 'null' }] },
             error: { type: 'string' },
           },
         },
@@ -285,7 +285,7 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
         })
         return {
           ok: true,
-          mode: status.mode ?? undefined,
+          mode: status.mode ?? null,
           currentRound: status.currentRound,
           totalRounds: status.totalRounds,
           fixedCount: status.fixedCount,
@@ -295,7 +295,7 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
           hasCheckpoint: status.hasCheckpoint,
           interrupted: status.interrupted,
           resumeCount: status.resumeCount,
-          lastUpdated: status.lastUpdated ?? undefined,
+          lastUpdated: status.lastUpdated ?? null,
         }
       },
     }),

package/src/tools/config.ts

@@ -60,14 +60,14 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           properties: {
             found: { type: 'boolean', required: true },
             valid: { type: 'boolean' },
-            errors: { type: 'array', items: { type: 'string' } },
+            errors: { oneOf: [{ type: 'array', items: { type: 'string' } }, { type: 'null' }] },
             section: { type: 'string' },
             data: { type: 'json' },
             config: { type: 'json' },
             availableSections: { type: 'array', items: { type: 'string' } },
             operation: { type: 'string' },
             ok: { type: 'boolean' },
-            backupPath: { type: 'string' },
+            backupPath: { oneOf: [{ type: 'string' }, { type: 'null' }] },
             error: { type: 'string' },
           },
         },
@@ -113,7 +113,7 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
             operation: 'write',
             ok: true,
             found: true,
-            backupPath: result.backupPath ?? undefined,
+            backupPath: result.backupPath ?? null,
             config: config as unknown as JsonValue,
           }
         }
@@ -127,7 +127,7 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           return {
             found: hasOverride,
             valid: errors.length === 0,
-            errors: errors.length > 0 ? errors : undefined,
+            errors: errors.length > 0 ? errors : null,
             section: 'validation_report',
           }
         }

package/src/tools/context.ts

@@ -10,6 +10,9 @@ const MAX_SKILL_DIR_LOOKUP_DEPTH = 12
 /** Maximum number of image attachments relayed into the context in one call. */
 const MAX_ATTACHMENTS = 8
 
+/** Maximum intrinsic width/height (px) accepted for an attached image. */
+const MAX_ATTACHMENT_DIMENSION = 16384
+
 /** A validated, normalized image-attachment entry carried into review context. */
 export interface NormalizedAttachment {
   name?: string
@@ -50,8 +53,8 @@ export function normalizeAttachment(raw: unknown): AttachmentValidationResult {
   }
   for (const dim of ['width', 'height'] as const) {
     if (entry[dim] !== undefined) {
-      if (typeof entry[dim] !== 'number' || !Number.isInteger(entry[dim]) || entry[dim] < 0 || entry[dim] > 16384) {
-        return { ok: false, error: `attachment.${dim} must be an integer in [0, 16384]` }
+      if (typeof entry[dim] !== 'number' || !Number.isInteger(entry[dim]) || entry[dim] < 0 || entry[dim] > MAX_ATTACHMENT_DIMENSION) {
+        return { ok: false, error: `attachment.${dim} must be an integer in [0, ${MAX_ATTACHMENT_DIMENSION}]` }
       }
       out[dim] = entry[dim]
     }

package/src/tools/review.ts

@@ -213,7 +213,7 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             operation: 'aggregate',
             mode,
             report: report as unknown as JsonValue,
-            schemaValidation: schemaValidation as unknown as JsonValue | undefined,
+            schemaValidation: (schemaValidation ?? null) as unknown as JsonValue | null,
           }
         }
 

package/src/tools/triage.ts

@@ -302,7 +302,7 @@ export function registerTriageTool(ctx: { tools: { register: (def: ReturnType<ty
             skipped: { type: 'integer' },
             count: { type: 'integer' },
             path: { type: 'string' },
-            backupPath: { type: 'string' },
+            backupPath: { oneOf: [{ type: 'string' }, { type: 'null' }] },
             entries: { type: 'json' },
             errors: { type: 'array', items: { type: 'string' } },
             error: { type: 'string' },
@@ -363,7 +363,7 @@ export function registerTriageTool(ctx: { tools: { register: (def: ReturnType<ty
             skipped: result.skipped,
             count: result.count,
             path: result.configPath,
-            backupPath: result.backupPath ?? undefined,
+            backupPath: result.backupPath ?? null,
           }
         }