iterate-plugin 2.9.1 → 2.9.3

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';
 /**
@@ -166,11 +167,69 @@ export function validateConfig(config) {
  * path is unsafe; callers must short-circuit on the failure and return a
  * structured error instead of proceeding.
  */
-export function resolveProjectRoot(input) {
+/**
+ * Resolve a caller-supplied project root to a safe absolute path.
+ *
+ * Resolution order for the default (no explicit `path`) case:
+ *   1. `sessionCwd` — the absolute working directory the calling DSH session
+ *      was created in (`exec.agent.session.header.cwd`). This is the
+ *      authoritative workspace for the current conversation and is immune to
+ *      where the web-service process happened to start.
+ *   2. the process cwd, when it is a usable directory (not `/` or the home
+ *      dir — launchd/daemon-managed servers start with cwd=`/`);
+ *   3. the session workspace decoded from `DSH_SESSION_JSONL` (present when
+ *      the DSH runtime injects per-session env into tool sub-processes).
+ */
+export function resolveProjectRoot(input, sessionCwd) {
     const raw = (input ?? '').trim();
-    const root = raw ? resolve(raw) : resolve(process.cwd());
+    const root = raw ? resolve(raw) : resolve(effectiveCwd(sessionCwd));
     if (!root || root === sep) {
         return { ok: false, reason: 'Refusing filesystem root as project root.' };
     }
     return { ok: true, root };
 }
+/**
+ * Thin adapter for tool `execute(args, exec)` bodies: pull the session cwd
+ * from the DSH run context and hand it to {@link resolveProjectRoot}.
+ */
+export function resolveProjectRootForExec(exec, input) {
+    return resolveProjectRoot(input, exec?.agent?.session?.header?.cwd);
+}
+/**
+ * Resolve the default working directory for tools invoked without an explicit
+ * `path`. Prefers the caller-provided session cwd, then the process cwd, then
+ * 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(sessionCwd) {
+    if (sessionCwd && sessionCwd !== sep && sessionCwd !== homedir())
+        return sessionCwd;
+    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/tools/checkpoint.js

@@ -10,7 +10,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { resolveProjectRoot } from "../config-loader.js";
+import { resolveProjectRootForExec } from "../config-loader.js";
 import { checkpointPath, iterateDir } from "../paths.js";
 import { readRegistry } from "./fix.js";
 import { readDecisionEntries } from "./decision-log.js";
@@ -142,14 +142,14 @@ export function registerCheckpointTool(ctx) {
                 { type: 'text', text: JSON.stringify(value, null, 2) },
             ],
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok)
                 return { operation: args.operation, ok: false, error: resolved.reason };
             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' },
                 },
             },
@@ -246,8 +246,8 @@ export function registerStatusTool(ctx) {
                 return [{ type: 'text', text: lines.filter(Boolean).join('\n') }];
             },
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok)
                 return { ok: false, error: resolved.reason };
             const projectRoot = resolved.root;
@@ -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

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { loadEffectiveConfig, validateConfig, resolveProjectRoot } from "../config-loader.js";
+import { loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFile, } from "../config-write.js";
 /**
  * Register the `iterate_config` tool.
@@ -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' },
                 },
             },
@@ -62,8 +62,8 @@ export function registerConfigTool(ctx) {
                 { type: 'text', text: JSON.stringify(value, null, 2) },
             ],
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok) {
                 return { found: false, error: resolved.reason };
             }
@@ -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

@@ -2,7 +2,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { resolveProjectRoot } from "../config-loader.js";
+import { resolveProjectRootForExec } from "../config-loader.js";
 /** How many ancestor directories we walk up looking for a SKILL.md. */
 const MAX_SKILL_DIR_LOOKUP_DEPTH = 12;
 /** Maximum number of image attachments relayed into the context in one call. */
@@ -235,8 +235,8 @@ export function registerContextTool(ctx) {
                 return [{ type: 'text', text: parts.join('\n\n') }];
             },
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok) {
                 return { found: false, error: resolved.reason, searched: [] };
             }

package/dist/tools/decision-log.js

@@ -1,7 +1,7 @@
 import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { resolveProjectRoot } from "../config-loader.js";
+import { resolveProjectRootForExec } from "../config-loader.js";
 const LOG_DIR = '.iterate';
 const LOG_FILE = 'decision-log.jsonl';
 /** All valid DecisionLogEntry `type` values (must stay in sync with Types). */
@@ -147,8 +147,8 @@ export function registerDecisionLogTool(ctx) {
                 { type: 'text', text: JSON.stringify(value, null, 2) },
             ],
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok) {
                 return { operation: args.operation, error: resolved.reason };
             }

package/dist/tools/fix.js

@@ -19,7 +19,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { loadEffectiveConfig, resolveProjectRoot } from "../config-loader.js";
+import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { countTouchedMethods } from "../method-scope.js";
 import { fixBackupPath, fixRegistryPath, fixesDir } from "../paths.js";
 import { appendDecisionEntry } from "./decision-log.js";
@@ -272,8 +272,8 @@ export function registerFixTool(ctx) {
                 { type: 'text', text: value.ok ? `${value.diffSummary ?? 'fixed'} @ ${value.file} (id: ${value.id})` : `fix failed: ${value.error}` },
             ],
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok)
                 return { ok: false, error: resolved.reason };
             const projectRoot = resolved.root;
@@ -433,8 +433,8 @@ export function registerDiffTool(ctx) {
                 return [{ type: 'text', text }];
             },
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok)
                 return { ok: false, error: resolved.reason };
             const projectRoot = resolved.root;
@@ -520,8 +520,8 @@ export function registerRollbackTool(ctx) {
                 { type: 'text', text: value.ok ? `reverted fix ${value.id} in ${value.file}` : `rollback failed: ${value.error}` },
             ],
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok)
                 return { ok: false, error: resolved.reason };
             const projectRoot = resolved.root;

package/dist/tools/history.js

@@ -8,7 +8,7 @@
  * Complements `iterate_status` (compact summary) with the actual detail.
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { resolveProjectRoot } from "../config-loader.js";
+import { resolveProjectRootForExec } from "../config-loader.js";
 import { readDecisionEntries } from "./decision-log.js";
 import { readRegistry } from "./fix.js";
 const DEFAULT_LIMIT = 50;
@@ -117,8 +117,8 @@ export function registerHistoryTool(ctx) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok)
                 return { ok: false, kind: 'history', error: resolved.reason };
             const projectRoot = resolved.root;

package/dist/tools/prune.js

@@ -20,7 +20,7 @@
 import { existsSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { resolveProjectRoot } from "../config-loader.js";
+import { resolveProjectRootForExec } from "../config-loader.js";
 import { readDecisionEntries, appendDecisionEntry } from "./decision-log.js";
 import { readRegistry, removeRecord, recomputeRoundCounts } from "./fix.js";
 import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from "../paths.js";
@@ -225,8 +225,8 @@ export function registerPruneTool(ctx) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok)
                 return { ok: false, dryRun: true, error: resolved.reason };
             const projectRoot = resolved.root;

package/dist/tools/review.js

@@ -1,5 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { loadEffectiveConfig, resolveProjectRoot } from "../config-loader.js";
+import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { buildReviewPlan, buildReviewReport, sanitizeRounds, validateRoundsSchema, } from "../review.js";
 import { buildFinalReviewReport, metaReviewReport } from "../meta-review.js";
 import { evidenceToPlain, verifyFindings } from "../evidence.js";
@@ -106,8 +106,8 @@ export function registerReviewTool(ctx) {
                 { type: 'text', text: JSON.stringify(value, null, 2) },
             ],
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok) {
                 return { operation: args.operation, error: resolved.reason };
             }
@@ -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

@@ -2,7 +2,7 @@ import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import yaml from 'js-yaml';
-import { resolveProjectRoot } from "../config-loader.js";
+import { resolveProjectRootForExec } from "../config-loader.js";
 const CONFIG_FILE = 'iterate.config.yaml';
 /** Personalization key that holds the known-intentional list. */
 const PERSONALIZATION_KEY = 'personalization';
@@ -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' },
@@ -272,8 +272,8 @@ export function registerTriageTool(ctx) {
                 { type: 'text', text: JSON.stringify(value, null, 2) },
             ],
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok) {
                 return { operation: args.operation, error: resolved.reason };
             }
@@ -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/dist/tools/validate.js

@@ -1,6 +1,6 @@
 import { exec } from 'node:child_process';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { loadEffectiveConfig, isCommandAllowed, flattenCommands, resolveProjectRoot, } from "../config-loader.js";
+import { loadEffectiveConfig, isCommandAllowed, flattenCommands, resolveProjectRootForExec, } from "../config-loader.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 /** Hard ceiling on a single validation command's runtime, so a model cannot
  *  pin the tool open indefinitely via an unbounded `timeout` argument. */
@@ -103,8 +103,8 @@ export function registerValidateTool(ctx) {
                 },
             ],
         },
-        async execute(args) {
-            const resolved = resolveProjectRoot(args.path);
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
             if (!resolved.ok) {
                 return {
                     allowed: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "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'
@@ -183,11 +184,69 @@ export type ProjectRootResult = { ok: true; root: string } | { ok: false; reason
  * path is unsafe; callers must short-circuit on the failure and return a
  * structured error instead of proceeding.
  */
-export function resolveProjectRoot(input?: string): ProjectRootResult {
+/**
+ * Resolve a caller-supplied project root to a safe absolute path.
+ *
+ * Resolution order for the default (no explicit `path`) case:
+ *   1. `sessionCwd` — the absolute working directory the calling DSH session
+ *      was created in (`exec.agent.session.header.cwd`). This is the
+ *      authoritative workspace for the current conversation and is immune to
+ *      where the web-service process happened to start.
+ *   2. the process cwd, when it is a usable directory (not `/` or the home
+ *      dir — launchd/daemon-managed servers start with cwd=`/`);
+ *   3. the session workspace decoded from `DSH_SESSION_JSONL` (present when
+ *      the DSH runtime injects per-session env into tool sub-processes).
+ */
+export function resolveProjectRoot(input?: string, sessionCwd?: string): ProjectRootResult {
   const raw = (input ?? '').trim()
-  const root = raw ? resolve(raw) : resolve(process.cwd())
+  const root = raw ? resolve(raw) : resolve(effectiveCwd(sessionCwd))
   if (!root || root === sep) {
     return { ok: false, reason: 'Refusing filesystem root as project root.' }
   }
   return { ok: true, root }
+}
+
+/**
+ * Thin adapter for tool `execute(args, exec)` bodies: pull the session cwd
+ * from the DSH run context and hand it to {@link resolveProjectRoot}.
+ */
+export function resolveProjectRootForExec(
+  exec: { agent?: { session?: { header?: { cwd?: string } } } } | undefined,
+  input?: string,
+): ProjectRootResult {
+  return resolveProjectRoot(input, exec?.agent?.session?.header?.cwd)
+}
+
+/**
+ * Resolve the default working directory for tools invoked without an explicit
+ * `path`. Prefers the caller-provided session cwd, then the process cwd, then
+ * 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(sessionCwd?: string): string {
+  if (sessionCwd && sessionCwd !== sep && sessionCwd !== homedir()) return sessionCwd
+  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/tools/checkpoint.ts

@@ -12,7 +12,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import { resolveProjectRoot } from '../config-loader.ts'
+import { resolveProjectRootForExec } from '../config-loader.ts'
 import { checkpointPath, iterateDir } from '../paths.ts'
 import { readRegistry } from './fix.ts'
 import { readDecisionEntries } from './decision-log.ts'
@@ -166,14 +166,14 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
         ],
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) return { operation: args.operation, ok: false, error: resolved.reason }
         const projectRoot = resolved.root
 
         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' },
           },
         },
@@ -274,8 +274,8 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
         },
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) return { ok: false, error: resolved.reason }
         const projectRoot = resolved.root
         const status = computeStatus({
@@ -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

@@ -1,7 +1,7 @@
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import { loadEffectiveConfig, validateConfig, resolveProjectRoot } from '../config-loader.ts'
+import { loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from '../config-loader.ts'
 import {
   applyConfigUpdates,
   readRawConfig,
@@ -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' },
           },
         },
@@ -76,8 +76,8 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
         ],
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) {
           return { found: false, error: resolved.reason }
         }
@@ -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

@@ -2,7 +2,7 @@ import { readFileSync, existsSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { resolveProjectRoot } from '../config-loader.ts'
+import { resolveProjectRootForExec } from '../config-loader.ts'
 
 /** How many ancestor directories we walk up looking for a SKILL.md. */
 const MAX_SKILL_DIR_LOOKUP_DEPTH = 12
@@ -257,8 +257,8 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
         },
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) {
           return { found: false, error: resolved.reason, searched: [] }
         }

package/src/tools/decision-log.ts

@@ -2,7 +2,7 @@ import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import { resolveProjectRoot } from '../config-loader.ts'
+import { resolveProjectRootForExec } from '../config-loader.ts'
 import type { DecisionLogEntry } from '../types.ts'
 
 const LOG_DIR = '.iterate'
@@ -159,8 +159,8 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
         ],
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) {
           return { operation: args.operation, error: resolved.reason }
         }

package/src/tools/fix.ts

@@ -21,7 +21,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import { loadEffectiveConfig, resolveProjectRoot } from '../config-loader.ts'
+import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
 import { countTouchedMethods } from '../method-scope.ts'
 import { fixBackupPath, fixRegistryPath, fixesDir } from '../paths.ts'
 import { appendDecisionEntry } from './decision-log.ts'
@@ -284,8 +284,8 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         ],
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) return { ok: false, error: resolved.reason }
         const projectRoot = resolved.root
         const { config } = loadEffectiveConfig(projectRoot)
@@ -454,8 +454,8 @@ export function registerDiffTool(ctx: { tools: { register: (def: ReturnType<type
         },
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) return { ok: false, error: resolved.reason }
         const projectRoot = resolved.root
         const registry = readRegistry(projectRoot)
@@ -544,8 +544,8 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
         ],
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) return { ok: false, error: resolved.reason }
         const projectRoot = resolved.root
         const id = typeof args.id === 'string' ? args.id : ''

package/src/tools/history.ts

@@ -10,7 +10,7 @@
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import { resolveProjectRoot } from '../config-loader.ts'
+import { resolveProjectRootForExec } from '../config-loader.ts'
 import { readDecisionEntries } from './decision-log.ts'
 import { readRegistry } from './fix.ts'
 import type { DecisionLogEntry, FixRegistry } from '../types.ts'
@@ -136,8 +136,8 @@ export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<t
         },
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) return { ok: false, kind: 'history', error: resolved.reason }
         const projectRoot = resolved.root
 

package/src/tools/prune.ts

@@ -22,7 +22,7 @@ import { existsSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'node
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import { resolveProjectRoot } from '../config-loader.ts'
+import { resolveProjectRootForExec } from '../config-loader.ts'
 import { readDecisionEntries, appendDecisionEntry } from './decision-log.ts'
 import { readRegistry, removeRecord, recomputeRoundCounts } from './fix.ts'
 import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from '../paths.ts'
@@ -265,8 +265,8 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
         },
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) return { ok: false, dryRun: true, error: resolved.reason }
         const projectRoot = resolved.root
         const retainDays = clampRetainDays(args.retainDays as number | undefined)

package/src/tools/review.ts

@@ -1,6 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import { loadEffectiveConfig, resolveProjectRoot } from '../config-loader.ts'
+import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
 import {
   buildReviewPlan,
   buildReviewReport,
@@ -131,8 +131,8 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
         ],
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) {
           return { operation: args.operation, error: resolved.reason }
         }
@@ -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

@@ -3,7 +3,7 @@ import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import yaml from 'js-yaml'
-import { resolveProjectRoot } from '../config-loader.ts'
+import { resolveProjectRootForExec } from '../config-loader.ts'
 import type { KnownIntentional } from '../types.ts'
 
 const CONFIG_FILE = 'iterate.config.yaml'
@@ -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' },
@@ -313,8 +313,8 @@ export function registerTriageTool(ctx: { tools: { register: (def: ReturnType<ty
         ],
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) {
           return { operation: args.operation, error: resolved.reason }
         }
@@ -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,
           }
         }
 

package/src/tools/validate.ts

@@ -4,7 +4,7 @@ import {
   loadEffectiveConfig,
   isCommandAllowed,
   flattenCommands,
-  resolveProjectRoot,
+  resolveProjectRootForExec,
 } from '../config-loader.ts'
 import type { ValidationResult } from '../types.ts'
 
@@ -126,8 +126,8 @@ export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<
         ],
       },
 
-      async execute(args) {
-        const resolved = resolveProjectRoot(args.path)
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) {
           return {
             allowed: false,