@wrongstack/tools 0.273.1 → 0.275.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import * as fs7 from 'node:fs/promises';
 import * as Core from '@wrongstack/core';
-import { toErrorMessage, atomicWrite, unifiedDiff, detectNewlineStyle, normalizeToLf, toStyle, compileGlob, expectDefined, buildChildEnv, isPrivateIPv4, isPrivateIPv6, loadPlan, setPlanItemStatus, savePlan, loadTasks, saveTasks, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, mutateTasks, formatTaskList, formatPlan, assessCommitSafety, recordPackageAction, detectPackageEcosystem, computeTaskItemProgress, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
+import { toErrorMessage, atomicWrite, unifiedDiff, detectNewlineStyle, normalizeToLf, toStyle, compileGlob, expectDefined, buildChildEnv, isPrivateIPv4, isPrivateIPv6, loadPlan, setPlanItemStatus, savePlan, loadTasks, saveTasks, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, mutateTasks, formatTaskList, formatPlan, assessCommitSafety, recordPackageAction, detectPackageEcosystem, getDesignKitLoader, isDesignStack, loadActiveKit, applyTokenOverrides, setActiveKit, recordKitChoice, recordOverrides, setDesignOverrides, materializeTokens, runDesignVerify, computeTaskItemProgress, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
 import * as path from 'node:path';
 import { resolve, sep, dirname, join } from 'node:path';
 import { spawn, execFileSync } from 'node:child_process';
@@ -375,7 +375,7 @@ var writeTool = {
       if (existed) {
         if (!ctx.hasRead(absPath)) {
           prev = await fs7.readFile(absPath, "utf8");
-          ctx.recordRead(absPath, stat12.mtimeMs);
+          ctx.recordRead(absPath, stat12.mtimeMs, "write");
         } else {
           prev = await fs7.readFile(absPath, "utf8");
         }
@@ -389,7 +389,7 @@ var writeTool = {
     const diff = existed ? unifiedDiff(prev, input.content, { fromFile: input.path, toFile: input.path }) : `+++ ${input.path}
 + (new file, ${input.content.split("\n").length} lines)`;
     const stat11 = await fs7.stat(absPath);
-    ctx.recordRead(absPath, stat11.mtimeMs);
+    ctx.recordRead(absPath, stat11.mtimeMs, "write");
     ctx.session.recordFileChange({
       path: absPath,
       action: existed ? "modified" : "created",
@@ -486,7 +486,7 @@ var editTool = {
     const newFile = toStyle(newFileLf, style);
     await atomicWrite(absPath, newFile, { mode: updated.mode & 511 });
     const written = await fs7.stat(absPath);
-    ctx.recordRead(absPath, written.mtimeMs);
+    ctx.recordRead(absPath, written.mtimeMs, "write");
     ctx.session.recordFileChange({
       path: absPath,
       action: "modified",
@@ -778,7 +778,27 @@ async function globNative(pattern, base, extraGlob) {
   await walk(base);
   return results;
 }
+
+// src/_concurrency.ts
+async function mapWithConcurrency(items, limit, fn) {
+  if (items.length === 0) return [];
+  const effectiveLimit = Math.max(1, Math.min(limit | 0, items.length));
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  const worker2 = async () => {
+    while (true) {
+      const i = nextIndex++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i]);
+    }
+  };
+  await Promise.all(Array.from({ length: effectiveLimit }, worker2));
+  return results;
+}
+
+// src/glob.ts
 var DEFAULT_IGNORE2 = ["node_modules", ".git", "dist", "build", ".next", "coverage", ".turbo"];
+var WALK_CONCURRENCY = 16;
 var globTool = {
   name: "glob",
   category: "Filesystem",
@@ -816,6 +836,22 @@ var globTool = {
     const re = compileGlob(input.pattern);
     const results = [];
     let truncated = false;
+    const pushResult = async (full) => {
+      if (truncated || results.length >= limit) {
+        truncated = true;
+        return;
+      }
+      try {
+        const st = await fs7.stat(full);
+        if (truncated || results.length >= limit) {
+          truncated = true;
+          return;
+        }
+        results.push({ rel: full, mtime: st.mtimeMs });
+        if (results.length >= limit) truncated = true;
+      } catch {
+      }
+    };
     const walk = async (dir, relPrefix) => {
       if (results.length >= limit) {
         truncated = true;
@@ -827,6 +863,8 @@ var globTool = {
       } catch {
         return;
       }
+      const subdirs = [];
+      const matchedFiles = [];
       for (const e of entries) {
         const name = e.name;
         if (DEFAULT_IGNORE2.includes(name)) continue;
@@ -834,22 +872,36 @@ var globTool = {
         const rel = relPrefix ? `${relPrefix}/${name}` : name;
         const full = path.join(dir, name);
         if (e.isDirectory()) {
-          await walk(full, rel);
-          if (truncated) return;
+          subdirs.push({ full, rel });
         } else if (e.isFile()) {
-          if (re.test(rel) || re.test(name)) {
-            try {
-              const st = await fs7.stat(full);
-              results.push({ rel: full, mtime: st.mtimeMs });
-              if (results.length >= limit) {
-                truncated = true;
-                return;
-              }
-            } catch {
+          re.lastIndex = 0;
+          const relMatch = re.test(rel);
+          re.lastIndex = 0;
+          const nameMatch = re.test(name);
+          if (relMatch || nameMatch) {
+            matchedFiles.push(full);
+          }
+        } else if (e.isSymbolicLink()) {
+          try {
+            const st = await fs7.stat(full);
+            if (st.isDirectory()) {
+              subdirs.push({ full, rel });
+            } else if (st.isFile()) {
+              re.lastIndex = 0;
+              const relMatch = re.test(rel);
+              re.lastIndex = 0;
+              const nameMatch = re.test(name);
+              if (relMatch || nameMatch) matchedFiles.push(full);
             }
+          } catch {
           }
         }
+        if (truncated) return;
       }
+      await mapWithConcurrency(matchedFiles, WALK_CONCURRENCY, pushResult);
+      if (truncated) return;
+      const remainingSubdirs = truncated ? [] : subdirs;
+      await mapWithConcurrency(remainingSubdirs, WALK_CONCURRENCY, ({ full, rel }) => walk(full, rel));
     };
     await walk(base, "");
     results.sort((a, b) => b.mtime - a.mtime);
@@ -866,6 +918,8 @@ async function readGitignore(dir) {
 }
 var DEFAULT_IGNORE3 = ["node_modules", ".git", "dist", "build", ".next", "coverage"];
 var NATIVE_SCAN_CONCURRENCY = 32;
+var NATIVE_READ_CHUNK_BYTES = 64 * 1024;
+var NATIVE_MAX_FILE_BYTES = 1e6;
 var grepTool = {
   name: "grep",
   category: "Search",
@@ -1090,7 +1144,8 @@ async function runNative(input, base, mode, limit, signal) {
   const re = compiled.regex;
   const globRe = input.glob ? compileGlob(input.glob) : null;
   const matches = [];
-  const fileMatches = /* @__PURE__ */ new Map();
+  const countOnlyFirstHit = mode === "count" && limit === 1;
+  const maxBytes = mode === "content" ? NATIVE_MAX_FILE_BYTES : Math.min(NATIVE_MAX_FILE_BYTES, 256 * 1024);
   let total = 0;
   let stopped = false;
   const scanFile = async (full, name) => {
@@ -1099,34 +1154,79 @@ async function runNative(input, base, mode, limit, signal) {
     if (globRe) globRe.lastIndex = 0;
     try {
       const stat11 = await fs7.stat(full);
-      if (stat11.size > 1e6 || stopped || signal.aborted) return;
-      const head = await fs7.readFile(full);
-      if (isBinaryBuffer(head) || stopped || signal.aborted) return;
-      const text = head.toString("utf8");
-      const lines = text.split(/\r?\n/);
-      let fileHits = 0;
-      for (let i = 0; i < lines.length; i++) {
-        if (stopped || signal.aborted) break;
-        const ln = capSubject(lines[i] ?? "");
-        re.lastIndex = 0;
-        if (re.test(ln)) {
-          fileHits++;
-          total++;
-          if (mode === "content" && matches.length < limit) {
-            matches.push(`${full}:${i + 1}:${ln}`);
+      if (!stat11.isFile() || stat11.size > maxBytes || stopped || signal.aborted) return;
+      const file = await fs7.open(full, "r");
+      try {
+        let bytesReadTotal = 0;
+        let lineNumber = 0;
+        let fileHits = 0;
+        let leftover = "";
+        let binaryChecked = false;
+        const buffer = Buffer.allocUnsafe(Math.min(NATIVE_READ_CHUNK_BYTES, maxBytes));
+        while (!stopped && !signal.aborted && bytesReadTotal < maxBytes) {
+          const remaining = maxBytes - bytesReadTotal;
+          const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, remaining), null);
+          if (bytesRead === 0) break;
+          const chunk = buffer.subarray(0, bytesRead);
+          if (!binaryChecked) {
+            binaryChecked = true;
+            if (isBinaryBuffer(chunk)) return;
+          }
+          bytesReadTotal += bytesRead;
+          const text = leftover + chunk.toString("utf8");
+          const lines = text.split(/\r?\n/);
+          leftover = lines.pop() ?? "";
+          for (const rawLine of lines) {
+            if (stopped || signal.aborted) break;
+            lineNumber++;
+            const ln = capSubject(rawLine);
+            re.lastIndex = 0;
+            if (!re.test(ln)) continue;
+            fileHits++;
+            total++;
+            if (mode === "content") {
+              if (matches.length < limit) matches.push(`${full}:${lineNumber}:${ln}`);
+            } else if (mode === "files_with_matches") {
+              if (fileHits === 1 && matches.length < limit) matches.push(full);
+              break;
+            } else if (fileHits === 1 && matches.length < limit) {
+              matches.push(`${full}:${countOnlyFirstHit ? 1 : 0}`);
+            }
+            if (countOnlyFirstHit || mode !== "content" && matches.length >= limit) {
+              stopped = true;
+              break;
+            }
           }
+          if (mode === "files_with_matches" && fileHits > 0) break;
         }
-      }
-      if (fileHits > 0) {
-        fileMatches.set(full, fileHits);
-        if (mode === "files_with_matches" && matches.length < limit) {
-          matches.push(full);
+        if (!stopped && !signal.aborted && leftover.length > 0) {
+          lineNumber++;
+          const ln = capSubject(leftover);
+          re.lastIndex = 0;
+          if (re.test(ln)) {
+            fileHits++;
+            total++;
+            if (mode === "content") {
+              if (matches.length < limit) matches.push(`${full}:${lineNumber}:${ln}`);
+            } else if (mode === "files_with_matches") {
+              if (matches.length < limit) matches.push(full);
+            } else if (matches.length < limit) {
+              matches.push(`${full}:${countOnlyFirstHit ? 1 : fileHits}`);
+            }
+          }
         }
-        if (mode === "count" && matches.length < limit) {
-          matches.push(`${full}:${fileHits}`);
+        if (fileHits > 0) {
+          if (mode === "count") {
+            const idx = matches.findIndex((entry) => entry.startsWith(`${full}:`));
+            if (idx !== -1) matches[idx] = `${full}:${fileHits}`;
+          }
+          if (mode === "files_with_matches" && matches.length >= limit) stopped = true;
         }
+        if (mode === "content" && matches.length >= limit) stopped = true;
+        if (mode === "count" && matches.length >= limit && (countOnlyFirstHit || mode !== "count")) stopped = true;
+      } finally {
+        await file.close();
       }
-      if (matches.length >= limit) stopped = true;
     } catch {
     }
   };
@@ -1139,18 +1239,20 @@ async function runNative(input, base, mode, limit, signal) {
       return;
     }
     const files = [];
+    const subdirs = [];
     for (const e of entries) {
       if (stopped) return;
       if (DEFAULT_IGNORE3.includes(e.name)) continue;
       if (e.isSymbolicLink()) continue;
       const full = path.join(dir, e.name);
       if (e.isDirectory()) {
-        await walk(full);
+        subdirs.push(full);
       } else if (e.isFile()) {
         files.push({ full, name: e.name });
       }
     }
     await mapWithConcurrency(files, NATIVE_SCAN_CONCURRENCY, ({ full, name }) => scanFile(full, name));
+    await mapWithConcurrency(subdirs, Math.min(16, NATIVE_SCAN_CONCURRENCY), walk);
   };
   await walk(base);
   return {
@@ -1160,20 +1262,6 @@ async function runNative(input, base, mode, limit, signal) {
     used: "native"
   };
 }
-async function mapWithConcurrency(items, concurrency, fn) {
-  if (items.length === 0) return;
-  let next = 0;
-  const workerCount = Math.min(Math.max(1, concurrency), items.length);
-  const workers = Array.from({ length: workerCount }, async () => {
-    for (; ; ) {
-      const idx = next++;
-      if (idx >= items.length) return;
-      const item = items[idx];
-      if (item !== void 0) await fn(item);
-    }
-  });
-  await Promise.all(workers);
-}
 var SPOOL_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
 var SPOOL_WRITE_HWM_BYTES = 4 * 1024 * 1024;
 var sweepStarted = false;
@@ -1215,7 +1303,7 @@ function createOutputSpool(opts) {
   let filePath = null;
   let failed = false;
   let finalized = false;
-  const open = () => {
+  const open2 = () => {
     if (stream || failed) return;
     try {
       const dir = toolOutputDir();
@@ -1248,7 +1336,7 @@ function createOutputSpool(opts) {
           return;
         }
         head += text;
-        open();
+        open2();
         head = "";
         return;
       }
@@ -1434,6 +1522,7 @@ var CircuitBreaker = class {
     if (this.state === "open") return;
     this.state = "open";
     this.openedAt = Date.now();
+    this.window = [];
     try {
       this.onTrip?.();
     } catch {
@@ -1473,7 +1562,7 @@ var SENSITIVE_FLAG_PATTERNS = [
   /--(?:token|password|passwd|pwd|secret|api[-_]?key|api[-_]?secret|auth|credential|private[-_]?key|access[-_]?key|github[-_]?token|gh[-_]?token|bearer|jwt|oauth|pin|pincode|passphrase|access[-_]?token)(?:[=\s,][^\s]*)?/gi,
   // -f "value" style short flags
   /(?<!\w)-t(?:\s+|\s*=\s*)[^\s,]+/,
-  /(?<!\w)-p(?:ssword)?(?:\s+|\s*=\s*)[^\s,]+/gi,
+  /(?<!\w)-(?:p|password)(?:\s+|\s*=\s*)[^\s,]+/gi,
   // env var–style secrets: TOKEN=x, API_KEY=y, etc.
   /(?:TOKEN|API_KEY|API_SECRET|AUTH_TOKEN|GITHUB_TOKEN|GH_TOKEN|BEARER|JWT|OAUTH|CREDENTIAL|SECRET|PRIVATE_KEY|PASSWORD|PASSWD)\s*[=:]\s*[^\s,]+/gi,
   // Generic high-entropy look: base64 strings >32 chars or hex strings >32 digits — but only
@@ -1534,12 +1623,35 @@ var ProcessRegistryImpl = class {
   register(info) {
     this.processes.set(info.pid, { ...info, killed: false, protected: info.protected ?? false });
   }
+  _isSafeSignalPid(pid) {
+    return Number.isInteger(pid) && pid > 1 && pid !== process.pid && pid !== process.ppid;
+  }
+  _canSignalProcessGroup(p) {
+    return os2.platform() !== "win32" && p.processGroupLeader === true && this._isSafeSignalPid(p.pid) && typeof p.child.pid === "number" && p.child.pid === p.pid;
+  }
+  _killChildDirect(p, signal) {
+    try {
+      p.child.kill(signal);
+    } catch {
+    }
+  }
+  _killPosix(p, signal) {
+    if (this._canSignalProcessGroup(p)) {
+      try {
+        process.kill(-p.pid, signal);
+        return;
+      } catch {
+      }
+    }
+    this._killChildDirect(p, signal);
+  }
   /** Unregister a process by PID. Called on 'close' / 'exit' events. */
   unregister(pid) {
     this.processes.delete(pid);
   }
   /** Get a single process by PID. */
   get(pid) {
+    this._pruneStale(pid);
     return this.processes.get(pid);
   }
   /** Get all tracked processes. */
@@ -1703,13 +1815,14 @@ var ProcessRegistryImpl = class {
    *  Returns true if the process was found and kill was attempted.
    */
   kill(pid, opts = {}) {
+    this._pruneStale(pid);
     const p = this.processes.get(pid);
     if (!p) return false;
     if (p.killed) return true;
     if (p.protected) return false;
     const { force = false, graceMs = DEFAULT_GRACE_MS } = opts;
-    const isWin3 = os2.platform() === "win32";
-    if (isWin3) {
+    const isWin4 = os2.platform() === "win32";
+    if (isWin4) {
       const liveRealChild = p.child.exitCode === null && typeof p.child.pid === "number";
       if (liveRealChild && killWin32Tree(pid)) {
         const fallback = setTimeout(() => {
@@ -1732,27 +1845,12 @@ var ProcessRegistryImpl = class {
     }
     try {
       if (force) {
-        try {
-          process.kill(-pid, "SIGKILL");
-        } catch {
-          p.child.kill("SIGKILL");
-        }
+        this._killPosix(p, "SIGKILL");
       } else {
-        try {
-          process.kill(-pid, "SIGTERM");
-        } catch {
-          p.child.kill("SIGTERM");
-        }
+        this._killPosix(p, "SIGTERM");
         const timer = setTimeout(() => {
           if (this.processes.has(pid) && !p.child.killed) {
-            try {
-              process.kill(-pid, "SIGKILL");
-            } catch {
-              try {
-                p.child.kill("SIGKILL");
-              } catch {
-              }
-            }
+            this._killPosix(p, "SIGKILL");
           }
         }, graceMs);
         timer.unref?.();
@@ -1787,6 +1885,34 @@ var ProcessRegistryImpl = class {
     }
     return killed;
   }
+  /**
+   * Check whether a tracked process entry is stale — the child has exited
+   * (exitCode !== null) AND it's been in the registry long enough that the
+   * OS may have reused the PID for a new, unrelated process.
+   *
+   * P3 #24 (before-release.md): on POSIX, PIDs are reused after process
+   * exit. If a tracked process exits but its 'close' event hasn't fired yet
+   * (or was missed), the registry still holds the entry. A new process
+   * gets the same PID, and PID-based lookups (get, kill, shouldBlockKill)
+   * may incorrectly protect or target the wrong process.
+   *
+   * The 60s threshold is conservative — the OS typically waits much longer
+   * before reusing a PID, but we want to clean up before that becomes a risk.
+   */
+  _isStaleEntry(entry) {
+    return entry.child.exitCode !== null && Date.now() - entry.startedAt > 6e4;
+  }
+  /**
+   * Remove a stale entry for a specific PID before any PID-based lookup.
+   * This prevents PID reuse from causing the registry to act on a dead
+   * process that has been replaced by a new one with the same PID.
+   */
+  _pruneStale(pid) {
+    const entry = this.processes.get(pid);
+    if (entry && this._isStaleEntry(entry)) {
+      this.processes.delete(pid);
+    }
+  }
 };
 var _registry;
 function getProcessRegistry() {
@@ -2211,17 +2337,18 @@ function resetPersistentProcessRegistry() {
 }
 
 // src/bash-kill-guard.ts
+var isWin = os2.platform() === "win32";
 function extractKillCommand(command) {
   const normalized = command.replace(/\s+/g, " ").trim();
   const shellCMatch = normalized.match(
-    /^(?:\/\w+)?\/?(?:bin|usr)\/(?:ba)?sh\s+-[c]\s+['"](.+?)['"]$/
+    /^(?:\S+(?:\s+\S+)?)?\s+-c\s+['"](.+?)['"]$/
   );
   if (shellCMatch?.[1]) {
     const inner = shellCMatch[1].trim();
     return isKillRelatedCommand(inner) ? inner : null;
   }
   const shellCUnquoted = normalized.match(
-    /^(?:\/\w+)?\/?(?:bin|usr)\/(?:ba)?sh\s+-[c]\s+(kill(?:\s+-[a-zA-Z]+)?(?:\s+\d+)+)$/
+    /^(?:\S+(?:\s+\S+)?)?\s+-c\s+(kill(?:\s+-[a-zA-Z]+)?(?:\s+\d+)+)$/
   );
   if (shellCUnquoted?.[1]) {
     return shellCUnquoted[1];
@@ -2230,15 +2357,43 @@ function extractKillCommand(command) {
 }
 function isKillRelatedCommand(cmd) {
   const normalized = cmd.toLowerCase().replace(/\s+/g, " ").trim();
+  if (isWin) {
+    if (/^taskkill\s/i.test(normalized)) return true;
+    if (/^tskill\s/i.test(normalized)) return true;
+    return false;
+  }
   if (/^kill(\s|$)/.test(normalized)) return true;
   if (/^(pkill|killall|pgrep|skill)\s/.test(normalized)) return true;
-  if (/^taskkill\s/i.test(normalized)) return true;
-  if (/^tskill\s/i.test(normalized)) return true;
   if (/^\/proc\/\d+\/(?:kill|fd)/.test(normalized)) return true;
   return false;
 }
 function parseKillCommand(command) {
   const normalized = command.replace(/\s+/g, " ").trim();
+  if (isWin) {
+    const taskkillMatch = normalized.match(/^taskkill\s+(?:\/[a-zA-Z]+\s+)*\/PID\s+(\d+)/i);
+    if (taskkillMatch?.[1]) {
+      const pidStr = taskkillMatch[1];
+      return {
+        pid: parseInt(pidStr, 10),
+        signal: normalized.includes("/F") ? "FORCE" : "TERM",
+        isGroupKill: false,
+        isAllKill: false,
+        originalCommand: command
+      };
+    }
+    const tskillMatch = normalized.match(/^tskill\s+(\d+)/i);
+    if (tskillMatch?.[1]) {
+      const pidStr = tskillMatch[1];
+      return {
+        pid: parseInt(pidStr, 10),
+        signal: "TERM",
+        isGroupKill: false,
+        isAllKill: false,
+        originalCommand: command
+      };
+    }
+    return null;
+  }
   const simpleMatch = normalized.match(/^kill\s+(?:(-[a-zA-Z]+)\s+)?(\d+|-?\d+)$/);
   if (simpleMatch) {
     const signal = simpleMatch[1] ?? "-TERM";
@@ -2282,28 +2437,6 @@ function parseKillCommand(command) {
   if (pgrepMatch) {
     return null;
   }
-  const taskkillMatch = normalized.match(/^taskkill\s+(?:\/[a-zA-Z]+\s+)*\/PID\s+(\d+)/i);
-  if (taskkillMatch?.[1]) {
-    const pidStr = taskkillMatch[1];
-    return {
-      pid: parseInt(pidStr, 10),
-      signal: normalized.includes("/F") ? "FORCE" : "TERM",
-      isGroupKill: false,
-      isAllKill: false,
-      originalCommand: command
-    };
-  }
-  const tskillMatch = normalized.match(/^tskill\s+(\d+)/i);
-  if (tskillMatch?.[1]) {
-    const pidStr = tskillMatch[1];
-    return {
-      pid: parseInt(pidStr, 10),
-      signal: "TERM",
-      isGroupKill: false,
-      isAllKill: false,
-      originalCommand: command
-    };
-  }
   return null;
 }
 async function getProtectedEntries() {
@@ -2380,7 +2513,7 @@ async function checkAndBlockKillCommand(command) {
   }
   return { blocked: false };
 }
-function pickShell(platform4, command, env) {
+function pickShell(platform5, command, env) {
   const override = env.get("WRONGSTACK_SHELL")?.trim().toLowerCase();
   if (override === "cmd" || override === "cmd.exe") return "cmd";
   if (override === "powershell" || override === "powershell.exe") return "powershell";
@@ -2434,7 +2567,7 @@ function looksLikePowerShellExtended(command) {
 }
 function wrapPowerShellScript(command) {
   const bootstrap = "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8;$ConfirmPreference='None';$WhatIfPreference=$false";
-  return "\uFEFF" + bootstrap + "\ntry {\n" + command + "\n} finally { exit $LASTEXITCODE }";
+  return bootstrap + "\n$ErrorActionPreference='Stop'\n" + command + "\nif ($LASTEXITCODE -is [int]) { exit $LASTEXITCODE }";
 }
 var PS_VERB_RE = new RegExp(
   // Boundaries: start-of-string, whitespace, `;`, `&`, `|`, `(`, `{`, `,`.
@@ -2624,10 +2757,10 @@ var bashTool = {
       }));
     }
     const timeoutMs = Math.max(1, Math.min(input.timeout_ms ?? DEFAULT_TIMEOUT_MS, 6e5));
-    const isWin3 = os2.platform() === "win32";
+    const isWin4 = os2.platform() === "win32";
     let plan;
     let winShellKind;
-    if (isWin3) {
+    if (isWin4) {
       const shell2 = pickShell("win32", input.command, {
         get: (k) => process.env[k]
       });
@@ -2656,7 +2789,7 @@ var bashTool = {
     const shell = plan.bin;
     const args = plan.useStdin ? [...plan.argv] : [...plan.argv, input.command];
     const env = buildChildEnv(ctx.session?.id);
-    const detached = !isWin3;
+    const detached = !isWin4;
     const startedAt = Date.now();
     if (input.background) {
       let buf2 = "";
@@ -2674,7 +2807,7 @@ var bashTool = {
         // apply: the child gets a hidden console that grandchildren inherit.
         // Windows children survive parent exit either way. POSIX keeps
         // detached for the process-group kill semantics.
-        detached: !isWin3,
+        detached: !isWin4,
         windowsHide: true
       });
       if (plan.useStdin) {
@@ -2692,7 +2825,8 @@ var bashTool = {
           command: redactCommand(input.command),
           startedAt: Date.now(),
           sessionId: ctx.session?.id,
-          child: child2
+          child: child2,
+          processGroupLeader: detached && child2.pid === pid2
         });
         child2.on("close", () => registry.unregister(pid2));
       }
@@ -2733,6 +2867,14 @@ var bashTool = {
           pid: pid2
         }
       };
+      ctx.recordSideEffect?.({
+        toolUseId: `bash-bg-${Date.now()}`,
+        toolName: "bash",
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        input: { command: redactCommand(input.command), background: true },
+        outcome: `launched (pid ${pid2 ?? "unknown"})`,
+        risk: "shell"
+      });
       return;
     }
     const child = spawn(shell, args, {
@@ -2743,7 +2885,7 @@ var bashTool = {
       stdio: [plan.useStdin ? "pipe" : "ignore", "pipe", "pipe"],
       detached,
       windowsHide: true,
-      ...isWin3 ? {} : { signal: opts.signal }
+      ...isWin4 ? {} : { signal: opts.signal }
     });
     if (plan.useStdin) {
       try {
@@ -2760,7 +2902,8 @@ var bashTool = {
         command: redactCommand(input.command),
         startedAt: Date.now(),
         sessionId: ctx.session?.id,
-        child
+        child,
+        processGroupLeader: detached && child.pid === pid
       });
     }
     let buf = "";
@@ -2769,7 +2912,7 @@ var bashTool = {
     const timers = [];
     const spool = createOutputSpool({ tool: "bash", thresholdBytes: MAX_OUTPUT });
     function killWithTimeout(child2, timeoutMs2) {
-      if (isWin3) {
+      if (isWin4) {
         if (typeof child2.pid === "number" && child2.exitCode === null && killWin32Tree(child2.pid)) {
           const fallback = setTimeout(() => {
             if (child2.exitCode === null) {
@@ -2789,34 +2932,22 @@ var bashTool = {
         }
         return;
       }
-      try {
-        if (typeof child2.pid === "number") {
-          try {
-            process.kill(-child2.pid, "SIGTERM");
-          } catch {
-            child2.kill("SIGTERM");
-          }
-        } else {
+      if (typeof child2.pid === "number") {
+        registry.kill(child2.pid, { graceMs: timeoutMs2 });
+      } else {
+        try {
           child2.kill("SIGTERM");
+        } catch {
         }
-      } catch {
-      }
-      const killTimer = setTimeout(() => {
-        try {
-          if (typeof child2.pid === "number") {
-            try {
-              process.kill(-child2.pid, "SIGKILL");
-            } catch {
-              child2.kill("SIGKILL");
-            }
-          } else {
+        const killTimer = setTimeout(() => {
+          try {
             child2.kill("SIGKILL");
+          } catch {
           }
-        } catch {
-        }
-      }, timeoutMs2);
-      timers.push(killTimer);
-      killTimer.unref?.();
+        }, timeoutMs2);
+        timers.push(killTimer);
+        killTimer.unref?.();
+      }
     }
     const timer = setTimeout(() => {
       timedOut = true;
@@ -2825,7 +2956,7 @@ var bashTool = {
     timers.push(timer);
     timer.unref?.();
     const onAbort = () => killWithTimeout(child, 2e3);
-    if (isWin3) {
+    if (isWin4) {
       if (opts.signal.aborted) onAbort();
       else opts.signal.addEventListener("abort", onAbort, { once: true });
     }
@@ -2913,6 +3044,14 @@ ${hint}` : ""),
               timed_out: timedOut
             }
           };
+          ctx.recordSideEffect?.({
+            toolUseId: `bash-${Date.now()}`,
+            toolName: "bash",
+            ts: (/* @__PURE__ */ new Date()).toISOString(),
+            input: { command: redactCommand(input.command) },
+            outcome: timedOut ? `timed out (exit ${c.code})` : `exit ${c.code}`,
+            risk: "shell"
+          });
           return;
         }
         const now2 = Date.now();
@@ -2924,7 +3063,7 @@ ${hint}` : ""),
     } finally {
       for (const t of timers) clearTimeout(t);
       spool.finalize();
-      if (isWin3) opts.signal.removeEventListener("abort", onAbort);
+      if (isWin4) opts.signal.removeEventListener("abort", onAbort);
       child.stdout?.off("data", onData);
       child.stderr?.off("data", onData);
       child.stdout?.destroy();
@@ -2934,6 +3073,38 @@ ${hint}` : ""),
         else killWithTimeout(child, 2e3);
       }
     }
+  },
+  /**
+   * Tool-level teardown fired by `ToolExecutor.runToolCleanup()` when the
+   * tool's run is aborted/timeout'd. The generator's `finally` block above
+   * already force-kills the direct child, but that only runs if the
+   * executor closes the async iterator (via `iter.return()`). When the
+   * executor tears down without iterating — or a re-entrant abort races
+   * with the generator — a bash-spawned process tree can survive in the
+   * ProcessRegistry with `killed === false`, continuing to write files,
+   * consume CPU, or hold inherited stdio pipes open for the rest of the
+   * session.
+   *
+   * This is the defensive layer the executor calls via `tool.cleanup()`
+   * (see `types/tool.ts`): kill every bash-owned process still tracked
+   * for this session that hasn't exited yet. `registry.kill()` already
+   * handles process-group / taskkill tree-kill and the SIGTERM→SIGKILL
+   * grace window, so this just scopes the registry's existing kill path
+   * to "this session's runaway bash children". Idempotent — a process
+   * that already exited is skipped by `kill()` (it returns false), and a
+   * `protected` infrastructure process (dev server the user intentionally
+   * backgrounded) is left alone by design.
+   */
+  async cleanup(_input, ctx) {
+    const registry = getProcessRegistry();
+    const sessionId = ctx.session?.id;
+    if (!sessionId) return;
+    for (const entry of registry.bySession(sessionId)) {
+      if (entry.name !== "bash") continue;
+      if (entry.child.exitCode !== null) continue;
+      if (entry.protected) continue;
+      registry.kill(entry.pid, { force: true });
+    }
   }
 };
 
@@ -2945,8 +3116,8 @@ function normalizeShell(value) {
   if (v === "pwsh" || v === "pwsh.exe") return "pwsh";
   return void 0;
 }
-function resolveSessionShell(platform4, env, deps = {}) {
-  if (platform4 !== "win32") return void 0;
+function resolveSessionShell(platform5, env, deps = {}) {
+  if (platform5 !== "win32") return void 0;
   const override = normalizeShell(env.get("WRONGSTACK_SHELL"));
   if (override) return override;
   const hasBinary = deps.hasBinary ?? ((bin) => resolveWin32Command(bin) !== bin);
@@ -2956,15 +3127,15 @@ function resolveSessionShell(platform4, env, deps = {}) {
 }
 function ensureSessionShell(opts = {}) {
   const env = opts.env ?? process.env;
-  const platform4 = opts.platform ?? process.platform;
-  if (platform4 !== "win32") return void 0;
+  const platform5 = opts.platform ?? process.platform;
+  if (platform5 !== "win32") return void 0;
   const existing = normalizeShell(env["WRONGSTACK_SHELL"]);
   if (existing) return existing;
-  const chosen = resolveSessionShell(platform4, { get: (k) => env[k] }, { hasBinary: opts.hasBinary }) ?? "cmd";
+  const chosen = resolveSessionShell(platform5, { get: (k) => env[k] }, { hasBinary: opts.hasBinary }) ?? "cmd";
   env["WRONGSTACK_SHELL"] = chosen;
   return chosen;
 }
-var isWin = process.platform === "win32";
+var isWin2 = process.platform === "win32";
 var DEFAULT_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
   // JS / TS toolchain
   "node",
@@ -2974,12 +3145,25 @@ var DEFAULT_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
   "npx",
   "bun",
   "deno",
+  "corepack",
   "tsc",
+  "tsx",
+  "ts-node",
+  "vite",
   "vitest",
   "jest",
   "biome",
   "eslint",
   "prettier",
+  "turbo",
+  "nx",
+  "webpack",
+  "rollup",
+  "parcel",
+  "next",
+  "astro",
+  "playwright",
+  "cypress",
   // version control
   "git",
   // Rust
@@ -2992,10 +3176,22 @@ var DEFAULT_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
   "python3",
   "pip",
   "pip3",
+  "pytest",
+  "ruff",
+  "mypy",
+  "uv",
+  "uvx",
+  "poetry",
+  "hatch",
+  "tox",
   // Ruby
   "ruby",
   "gem",
   "bundle",
+  // PHP
+  "php",
+  "composer",
+  "phpunit",
   // JVM
   "java",
   "javac",
@@ -3007,18 +3203,25 @@ var DEFAULT_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
   // C / C++ / native build
   "make",
   "cmake",
-  // containers / orchestration (read-only subcommands; see BLOCKED_ARG_PATTERNS)
+  // containers / orchestration
   "docker",
+  "podman",
   "kubectl",
   // common POSIX file/text utilities
+  "pwd",
   "ls",
   "cat",
   "head",
   "tail",
   "wc",
   "grep",
+  "rg",
   "find",
   "echo",
+  "sort",
+  "uniq",
+  "sed",
+  "awk",
   "mkdir",
   "cp",
   "mv",
@@ -3049,8 +3252,7 @@ var MAX_ARGS = 20;
 var MAX_OUTPUT2 = 2e5;
 var DEFAULT_TIMEOUT_MS2 = 3e4;
 var BLOCKED_ARG_PATTERNS = {
-  // python -c/--command executes arbitrary code; python -m runs modules
-  python: [/-c$/, /^--command$/, /^-m$/, /^--module$/],
+  python: [],
   // git --exec=<cmd> runs arbitrary commands via upload-pack/receive-pack;
   // -C <dir> changes working directory, bypassing cwd sandbox;
   // -c/--config <k>=<v> injects config that runs commands
@@ -3066,15 +3268,10 @@ var BLOCKED_ARG_PATTERNS = {
     /^--config=/,
     /^--config-env=/
   ],
-  // node -r/--require preloads arbitrary modules; --eval executes code
-  node: [/^-r$/, /^--require$/, /^-e$/, /^--eval$/, /^--prof-process$/],
-  // go run could execute arbitrary .go files; -ldflags could inject build-time code
-  go: [/^-ldflags$/],
-  // bun --preload is similar to node --require
-  bun: [/^--preload$/, /^run$/, /^bunx$/, /^create$/, /^init$/],
-  // docker build/run can create containers with host access;
-  // only allow read-only commands (ps, images, version)
-  docker: [/^build$/, /^run$/, /^exec$/, /^push$/, /^pull$/],
+  node: [],
+  go: [],
+  bun: [],
+  docker: [],
   // find -exec/-ok/-execdir execute arbitrary commands
   find: [/^-exec$/, /^-exec;$/, /^-ok$/, /^-ok;$/, /^-execdir$/, /^-execdir;$/, /^-exec=/, /^-ok=/, /^-execdir=/],
   // rm -rf / is catastrophic — block absolute paths, home, dot-dirs,
@@ -3082,15 +3279,49 @@ var BLOCKED_ARG_PATTERNS = {
   // `rm -rf ./src/*` expands to project files; `rm -rf ../../` escapes upward;
   // `rm -rf /*` targets the filesystem root. All are blocked.
   rm: [/^\//, /^~\//, /^~$/, /^\.$/, /^\.\.$/, /\*$/, /\/$/, /\/\*$/, /\.\//],
-  // npm run/exec/create/pack/publish can execute arbitrary scripts or publish malware
-  npm: [/^run$/, /^exec$/, /^create$/, /^init$/, /^pack$/, /^publish$/, /^deploy$/],
-  // pnpm run/dlx/exec/create can execute arbitrary scripts
-  pnpm: [/^run$/, /^dlx$/, /^exec$/, /^create$/, /^init$/, /^pack$/, /^publish$/, /^deploy$/],
-  // npx should only be used for --version; any package name is a vector for
-  // malicious package execution (typosquatting, dependency confusion)
-  npx: [/^[^\s]+$/]
+  // npm/pnpm subcommands are checked separately below. Matching every arg here
+  // over-blocked normal dev flows such as `pnpm vitest run ...`.
+  npm: [],
+  pnpm: [],
+  npx: []
+};
+var BLOCKED_SUBCOMMANDS = {
+  docker: /* @__PURE__ */ new Set(["push"]),
+  podman: /* @__PURE__ */ new Set(["push"]),
+  npm: /* @__PURE__ */ new Set(["publish", "deploy"]),
+  pnpm: /* @__PURE__ */ new Set(["publish", "deploy"]),
+  yarn: /* @__PURE__ */ new Set(["publish"])
+};
+var BLOCKED_SUBCOMMAND_SEQUENCES = {
+  yarn: [["npm", "publish"]]
 };
+function firstSubcommand(args) {
+  for (const arg of args) {
+    if (arg === "--") return null;
+    if (!arg.startsWith("-")) return arg;
+  }
+  return null;
+}
+function subcommandArgs(args) {
+  const out = [];
+  for (const arg of args) {
+    if (arg === "--") break;
+    if (!arg.startsWith("-")) out.push(arg);
+  }
+  return out;
+}
 function validateArgs(cmd, args) {
+  const blockedSubcommands = BLOCKED_SUBCOMMANDS[cmd];
+  const subcommand = firstSubcommand(args);
+  if (blockedSubcommands && subcommand && blockedSubcommands.has(subcommand)) {
+    return `Blocked subcommand "${subcommand}" for command "${cmd}"`;
+  }
+  const blockedSequences = BLOCKED_SUBCOMMAND_SEQUENCES[cmd];
+  if (blockedSequences) {
+    const actual = subcommandArgs(args);
+    const blocked2 = blockedSequences.find((seq) => seq.every((part, idx) => actual[idx] === part));
+    if (blocked2) return `Blocked subcommand "${blocked2.join(" ")}" for command "${cmd}"`;
+  }
   const blocked = BLOCKED_ARG_PATTERNS[cmd];
   if (!blocked) return null;
   for (const arg of args) {
@@ -3217,7 +3448,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     const startedAt = Date.now();
     const spool = createOutputSpool({ tool: `exec-${cmd}`, thresholdBytes: MAX_OUTPUT2 });
     const resolved = resolveWin32Command(cmd);
-    const needsShell = isWin && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
+    const needsShell = isWin2 && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
     const spawnCmd = needsShell ? cmd : resolved;
     if (needsShell) assertSafeWin32ShellArgs(args);
     let child;
@@ -3227,7 +3458,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
         env: buildChildEnv(sessionId),
         stdio: ["ignore", "pipe", "pipe"],
         windowsHide: true,
-        ...isWin ? {} : { signal },
+        ...isWin2 ? {} : { signal },
         ...needsShell ? { shell: true, windowsVerbatimArguments: true } : {}
       });
     } catch (err) {
@@ -3247,7 +3478,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       const isAbort = err && err.code === "ABORT_ERR";
       const stderrText = isAbort ? `Aborted: ${err.message}` : err.message;
       clearTimeout(timer);
-      if (isWin) signal.removeEventListener("abort", onAbort);
+      if (isWin2) signal.removeEventListener("abort", onAbort);
       if (typeof pid === "number") registry.unregister(pid);
       registry.afterCall(Date.now() - startedAt, true);
       spool.finalize();
@@ -3277,7 +3508,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       if (typeof pid === "number") registry.kill(pid, { force: true });
       else child.kill("SIGTERM");
     };
-    if (isWin) {
+    if (isWin2) {
       if (signal.aborted) onAbort();
       else signal.addEventListener("abort", onAbort, { once: true });
     }
@@ -3293,7 +3524,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      if (isWin) signal.removeEventListener("abort", onAbort);
+      if (isWin2) signal.removeEventListener("abort", onAbort);
       if (typeof pid === "number") registry.unregister(pid);
       const durationMs = Date.now() - startedAt;
       const exitCode = killed ? 124 : code ?? 1;
@@ -3457,7 +3688,7 @@ var fetchTool = {
     if (!final) throw new Error("fetch: stream ended without final event");
     return final;
   },
-  async *executeStream(input, _ctx, opts) {
+  async *executeStream(input, ctx, opts) {
     if (!input?.url) throw new Error("fetch: url is required");
     const u = new URL(input.url);
     if (u.protocol !== "https:" && u.protocol !== "http:") {
@@ -3529,6 +3760,14 @@ var fetchTool = {
           url: res.url
         }
       };
+      ctx.recordSideEffect?.({
+        toolUseId: `fetch-${Date.now()}`,
+        toolName: "fetch",
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        input: { url: input.url, format: input.format },
+        outcome: `HTTP ${res.status} (${ct})`,
+        risk: "network"
+      });
     } finally {
       clearTimeout(timer);
     }
@@ -4161,13 +4400,13 @@ ${formatTaskList(taskFile.tasks)}`
   }
 };
 function mkResult(plan, ok, message, todos) {
-  const open = plan.items.filter((i) => i.status !== "done").length;
+  const open2 = plan.items.filter((i) => i.status !== "done").length;
   const result = {
     ok,
     message,
     plan: formatPlan(plan),
     count: plan.items.length,
-    open
+    open: open2
   };
   if (todos !== void 0) result.todos = todos;
   return result;
@@ -4636,8 +4875,8 @@ var jsonTool = {
     };
   }
 };
-function query(data, path21) {
-  const parts = path21.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+function query(data, path22) {
+  const parts = path22.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
   let current = data;
   for (const part of parts) {
     if (current === null || current === void 0) return void 0;
@@ -5009,7 +5248,7 @@ async function walkDir(dir, depth, opts) {
     }
   }
 }
-var isWin2 = process.platform === "win32";
+var isWin3 = process.platform === "win32";
 async function* spawnStream(opts) {
   const max = opts.maxBytes ?? 2e5;
   const flushAt = opts.flushBytes ?? 4 * 1024;
@@ -5020,7 +5259,7 @@ async function* spawnStream(opts) {
   let error;
   const spool = createOutputSpool({ tool: opts.cmd, thresholdBytes: max });
   const resolved = resolveWin32Command(opts.cmd);
-  const needsShell = isWin2 && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
+  const needsShell = isWin3 && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
   const cmd = needsShell ? opts.cmd : resolved;
   if (needsShell) assertSafeWin32ShellArgs(opts.args);
   const child = spawn(cmd, opts.args, {
@@ -5028,7 +5267,7 @@ async function* spawnStream(opts) {
     env: buildChildEnv(),
     stdio: ["ignore", "pipe", "pipe"],
     windowsHide: true,
-    ...isWin2 ? {} : { signal: opts.signal },
+    ...isWin3 ? {} : { signal: opts.signal },
     ...needsShell ? { shell: true, windowsVerbatimArguments: true } : {}
   });
   const registry = getProcessRegistry();
@@ -5107,7 +5346,7 @@ async function* spawnStream(opts) {
     queue.push({ kind: "close", data: "", code: 124 });
     wake();
   };
-  if (isWin2) {
+  if (isWin3) {
     if (opts.signal.aborted) onAbort();
     else opts.signal.addEventListener("abort", onAbort, { once: true });
   }
@@ -5154,7 +5393,7 @@ async function* spawnStream(opts) {
     };
   } finally {
     spool.finalize();
-    if (isWin2) opts.signal.removeEventListener("abort", onAbort);
+    if (isWin3) opts.signal.removeEventListener("abort", onAbort);
     child.stdout?.off("data", onOut);
     child.stderr?.off("data", onErr);
     child.stdout?.destroy();
@@ -5740,6 +5979,14 @@ var installTool = {
         }
       }
     }
+    ctx.recordSideEffect?.({
+      toolUseId: `install-${Date.now()}`,
+      toolName: "install",
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      input: { packages: pkgList, cwd, dry_run: Boolean(input.dry_run) },
+      outcome: output.dry_run ? "dry run" : result.exitCode === 0 ? `installed ${pkgList.length || "all"} packages` : `failed (exit ${result.exitCode})`,
+      risk: "package"
+    });
     yield { type: "final", output };
   }
 };
@@ -6106,7 +6353,7 @@ async function dockerLogs(service, lines, filterRe, cwd, signal, since) {
 }
 var DOCKER_LOGS_TIMEOUT_MS = 3e3;
 var MAX_TAIL_LINES = 1e5;
-async function fileLogs(path21, lines, filterRe, stream) {
+async function fileLogs(path22, lines, filterRe, stream) {
   const { createInterface } = await import('node:readline');
   const { createReadStream } = await import('node:fs');
   const entries = [];
@@ -6115,7 +6362,7 @@ async function fileLogs(path21, lines, filterRe, stream) {
   let writeIdx = 0;
   let totalLines = 0;
   const rl = createInterface({
-    input: createReadStream(path21),
+    input: createReadStream(path22),
     crlfDelay: Number.POSITIVE_INFINITY
   });
   for await (const line of rl) {
@@ -6136,7 +6383,7 @@ async function fileLogs(path21, lines, filterRe, stream) {
     if (parsed) entries.push(parsed);
   }
   return {
-    source: path21,
+    source: path22,
     entries,
     total: entries.length,
     truncated: totalLines > effLines,
@@ -6508,6 +6755,229 @@ function substituteVars(content, name, vars) {
   }
   return result;
 }
+function normalizeOverrides(set) {
+  const out = {};
+  if (set && typeof set === "object") {
+    for (const [k, v] of Object.entries(set)) {
+      if (typeof v === "string") out[k] = v;
+    }
+  }
+  return out;
+}
+var designTool = {
+  name: "design",
+  category: "Design",
+  description: 'Browse, load, customize, and enforce curated frontend/mobile UI design kits. Use BEFORE writing UI code to commit to one coherent, modern, responsive, dark/light, accessible design. Actions: "list" (menu), "use" (load+pin a kit for a stack), "foundations" (baseline), "set" (override kit colors/tokens), "materialize" (write the tokens to a real theme file \u2014 CSS @theme/OKLCH or native), "verify" (scan UI files for off-palette colors).',
+  usageHint: 'Flow: `design {action:"use", kit:"minimal-clarity", stack:"web"}` \u2192 optionally `design {action:"set", set:{primary:"oklch(62% 0.2 25)"}}` \u2192 `design {action:"materialize"}` to write tokens to disk \u2192 implement against them \u2192 `design {action:"verify"}`.',
+  permission: "auto",
+  mutating: false,
+  capabilities: [],
+  timeoutMs: 15e3,
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["list", "use", "foundations", "set", "materialize", "verify"],
+        description: "list = menu; use = load+pin a kit; foundations = baseline; set = override colors/tokens; materialize = write tokens to a theme file; verify = scan UI for off-palette colors. Default: list."
+      },
+      kit: {
+        type: "string",
+        description: 'Kit id (required for "use"), e.g. "minimal-clarity", "neo-brutalist".'
+      },
+      stack: {
+        type: "string",
+        enum: ["web", "react-native", "flutter", "swiftui", "compose"],
+        description: "Target stack \u2014 narrows guidance + materialize format. Default: web."
+      },
+      set: {
+        type: "object",
+        description: 'Token overrides for "set"/"use": { "primary": "oklch(\u2026)", "dark.bg": "#111" }. Bare key = both themes; "light."/"dark." prefix = that theme only. Empty value clears an override.',
+        additionalProperties: { type: "string" }
+      },
+      out: {
+        type: "string",
+        description: "Materialize output path (project-relative). Defaults to a per-stack convention."
+      },
+      force: {
+        type: "boolean",
+        description: "Materialize: overwrite an existing file (default false \u2014 refuses to clobber)."
+      },
+      files: {
+        type: "array",
+        items: { type: "string" },
+        description: "Verify: explicit project-relative files to scan. Default: a bounded UI-file walk."
+      }
+    },
+    required: []
+  },
+  async execute(input, ctx) {
+    const loader = getDesignKitLoader(ctx.projectRoot);
+    const action = input.action ?? "list";
+    const stack = input.stack && isDesignStack(input.stack) ? input.stack : void 0;
+    if (action === "foundations") {
+      const text = await loader.foundationsText(stack);
+      return { action, stack, output: text || "No foundations document is installed." };
+    }
+    if (action === "use") {
+      const kitId = input.kit?.trim();
+      if (!kitId) {
+        const menu2 = await loader.menuText();
+        return { action, output: `No kit id provided.
+
+${menu2}` };
+      }
+      const manifest = await loader.find(kitId);
+      if (!manifest) {
+        const menu2 = await loader.menuText();
+        return { action, kit: kitId, output: `Kit "${kitId}" not found.
+
+${menu2}` };
+      }
+      const resolvedStack = stack ?? manifest.stacks[0] ?? "web";
+      const body = await loader.readBody(manifest.id, resolvedStack);
+      const rawTokens = await loader.readTokens(manifest.id);
+      const persisted = await loadActiveKit(ctx.projectRoot);
+      const keepOverrides = persisted?.kit === manifest.id ? persisted.overrides ?? {} : {};
+      const overrides = { ...keepOverrides, ...normalizeOverrides(input.set) };
+      const tokens = rawTokens ? applyTokenOverrides(rawTokens, overrides) : rawTokens;
+      setActiveKit(ctx, manifest.id, resolvedStack, overrides);
+      await recordKitChoice(
+        ctx.projectRoot,
+        manifest.id,
+        resolvedStack,
+        "design-tool",
+        (/* @__PURE__ */ new Date()).toISOString(),
+        Object.keys(overrides).length ? overrides : void 0
+      );
+      const ovLine = Object.keys(overrides).length ? `
+Active color overrides: ${Object.entries(overrides).map(([k, v]) => `${k}=${v}`).join(", ")}
+` : "";
+      const header = `# Active design kit: ${manifest.name} (${manifest.id}) \u2014 stack: ${resolvedStack}
+${manifest.aesthetic}
+${ovLine}
+Implement the UI faithfully to this spec. Keep light/dark, responsive, and WCAG AA.
+`;
+      const tokenBlock = tokens ? `
+## Token snapshot (overrides applied)
+\`\`\`json
+${JSON.stringify(tokens, null, 2)}
+\`\`\`
+Tip: run \`design {action:"materialize"}\` to write these tokens to a real theme file.
+` : "";
+      return {
+        action,
+        kit: manifest.id,
+        stack: resolvedStack,
+        output: `${header}${tokenBlock}
+${body}`
+      };
+    }
+    if (action === "set") {
+      const patch = normalizeOverrides(input.set);
+      if (Object.keys(patch).length === 0) {
+        return { action, output: 'No overrides given. Pass set:{ "primary": "oklch(\u2026)" }.' };
+      }
+      const merged = await recordOverrides(ctx.projectRoot, patch, (/* @__PURE__ */ new Date()).toISOString());
+      if (!merged) {
+        return {
+          action,
+          output: 'No active kit. Pick one first: `design {action:"use", kit:"<id>"}`.'
+        };
+      }
+      setDesignOverrides(ctx, merged);
+      return {
+        action,
+        output: `Overrides updated. Active overrides: ${Object.entries(merged).map(([k, v]) => `${k}=${v}`).join(", ")}
+These win over kit tokens. Run \`design {action:"materialize"}\` to write them to a theme file.`
+      };
+    }
+    if (action === "materialize") {
+      const active = await loadActiveKit(ctx.projectRoot);
+      if (!active) {
+        return {
+          action,
+          output: 'No active kit. Pick one first: `design {action:"use", kit:"<id>"}`.'
+        };
+      }
+      const resolvedStack = stack ?? (active.stack && isDesignStack(active.stack) ? active.stack : "web");
+      const rawTokens = await loader.readTokens(active.kit);
+      if (!rawTokens) {
+        return { action, kit: active.kit, output: `Kit "${active.kit}" has no tokens.json.` };
+      }
+      const tokens = applyTokenOverrides(rawTokens, active.overrides);
+      const result = materializeTokens({
+        tokens,
+        stack: resolvedStack,
+        kitId: active.kit,
+        outPath: input.out
+      });
+      const abs = path.join(ctx.projectRoot, result.path);
+      let exists = false;
+      try {
+        await fs7.access(abs);
+        exists = true;
+      } catch {
+      }
+      if (exists && !input.force) {
+        return {
+          action,
+          kit: active.kit,
+          stack: resolvedStack,
+          path: result.path,
+          output: `${result.path} already exists. Re-run with force:true to overwrite, or write this ${result.format} yourself:
+
+\`\`\`
+${result.content}
+\`\`\``
+        };
+      }
+      await fs7.mkdir(path.dirname(abs), { recursive: true });
+      await fs7.writeFile(abs, result.content);
+      return {
+        action,
+        kit: active.kit,
+        stack: resolvedStack,
+        path: result.path,
+        output: `Wrote ${result.format} to ${result.path}. Import these tokens in your UI so the kit palette is the source of truth. ${exists ? "(overwrote existing file)" : ""}`
+      };
+    }
+    if (action === "verify") {
+      const active = await loadActiveKit(ctx.projectRoot);
+      if (!active) {
+        return {
+          action,
+          output: 'No active kit to verify against. Pick one: `design {action:"use", kit:"<id>"}`.'
+        };
+      }
+      const rawTokens = await loader.readTokens(active.kit);
+      if (!rawTokens) {
+        return { action, kit: active.kit, output: `Kit "${active.kit}" has no tokens.json.` };
+      }
+      const tokens = applyTokenOverrides(rawTokens, active.overrides);
+      const report = await runDesignVerify(ctx.projectRoot, tokens, input.files);
+      const pct = Math.round(report.score * 100);
+      const top = report.violations.slice(0, 25).map((v) => `  ${v.file}:${v.line} \u2014 ${v.reason}: ${v.snippet}`).join("\n");
+      const summary = `Adherence: ${pct}% on-palette across ${report.filesScanned} file(s). ${report.violations.length} violation(s).` + (report.violations.length ? `
+${top}${report.violations.length > 25 ? `
+  \u2026and ${report.violations.length - 25} more` : ""}
+
+Replace off-palette colors with kit tokens (or the materialized CSS vars / token utilities).` : "\nNo off-palette colors found \u2014 UI adheres to the kit palette.");
+      return {
+        action,
+        kit: active.kit,
+        output: summary,
+        score: report.score,
+        violations: report.violations.length
+      };
+    }
+    const menu = await loader.menuText();
+    return {
+      action: "list",
+      output: (menu || "No design kits are installed.") + '\n\nLoad one with `design {action:"use", kit:"<id>", stack:"<stack>"}`.'
+    };
+  }
+};
 
 // src/tool-search.ts
 var toolSearchTool = {
@@ -8039,6 +8509,8 @@ var IndexStore = class {
     this.db.exec("CREATE INDEX IF NOT EXISTS idx_s_kind ON symbols(kind)");
     this.db.exec("CREATE INDEX IF NOT EXISTS idx_s_lang ON symbols(lang)");
     this.db.exec("CREATE INDEX IF NOT EXISTS idx_s_file ON symbols(file)");
+    this.db.exec("CREATE INDEX IF NOT EXISTS idx_s_lang_kind ON symbols(lang, kind)");
+    this.db.exec("CREATE INDEX IF NOT EXISTS idx_s_file_fk ON symbols(file_fk)");
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS refs (
         id INTEGER PRIMARY KEY,
@@ -8951,9 +9423,9 @@ async function syncGoParse(filePath, content, lang) {
   }
 }
 async function parseSymbols3(opts) {
-  const { file, lang } = opts;
+  const { file, content, lang } = opts;
   try {
-    return await syncPyParse(file, lang);
+    return await syncPyParse(file, content, lang);
   } catch {
     return { file, lang, symbols: [], mtimeMs: Date.now() };
   }
@@ -9021,8 +9493,7 @@ syms = []
 errors = []
 
 try:
-    with open(sys.argv[1], "r", encoding="utf-8") as f:
-        source = f.read()
+    source = sys.stdin.read()
     tree = ast.parse(source, filename=sys.argv[1])
 except Exception as e:
     errors.append(str(e))
@@ -9162,16 +9633,21 @@ visitor.visit(tree)
 
 print(json.dumps([s.to_dict() for s in syms]))
 `;
-async function syncPyParse(filePath, lang) {
+var _cachedScriptPath = null;
+async function syncPyParse(filePath, content, lang) {
   try {
-    const tmpDir = path.join(os2.tmpdir(), "ws-py-parse");
-    await fs7.mkdir(tmpDir, { recursive: true });
-    const scriptPath = path.join(tmpDir, "parse.py");
-    await fs7.writeFile(scriptPath, PY_PARSE_SCRIPT, "utf8");
-    const proc = spawn("python", [scriptPath, filePath], {
+    if (!_cachedScriptPath) {
+      const tmpDir = path.join(os2.tmpdir(), "ws-py-parse");
+      await fs7.mkdir(tmpDir, { recursive: true });
+      _cachedScriptPath = path.join(tmpDir, "parse.py");
+      await fs7.writeFile(_cachedScriptPath, PY_PARSE_SCRIPT, "utf8");
+    }
+    const proc = spawn("python", [_cachedScriptPath, filePath], {
       stdio: ["pipe", "pipe", "pipe"],
       windowsHide: true
     });
+    proc.stdin?.write(content);
+    proc.stdin?.end();
     let stdout = "";
     proc.stdout?.on("data", (chunk) => {
       stdout += chunk.toString();
@@ -9838,7 +10314,7 @@ async function parseFile(file, content, lang) {
     case "go":
       return parseSymbols2({ file, content, lang: "go" });
     case "py":
-      return parseSymbols3({ file, lang: "py" });
+      return parseSymbols3({ file, content, lang: "py" });
     case "rs":
       return parseSymbols4({ file, content, lang: "rs" });
     case "json":
@@ -9869,10 +10345,12 @@ async function runIndexerWithStore(store, opts) {
   let symbolsIndexed = 0;
   const isGitIgnored = await loadGitignoreMatcher(projectRoot);
   let files;
+  let discoveredFiles = null;
   if (opts.files && opts.files.length > 0) {
     files = opts.files.map((f) => path.resolve(projectRoot, f)).filter((f) => !isGitIgnored(path.relative(projectRoot, f).replace(/\\/g, "/"), false));
   } else {
     files = await findSourceFiles(projectRoot, ignore, isGitIgnored, signal);
+    discoveredFiles = new Set(files);
   }
   if (langs && langs.length > 0) {
     const langSet = new Set(langs);
@@ -9990,11 +10468,11 @@ async function runIndexerWithStore(store, opts) {
       filesIndexed++;
     }
   }
-  for (const [file_] of existingMeta) {
-    try {
-      await fs7.stat(file_);
-    } catch {
-      store.deleteFile(file_);
+  if (discoveredFiles) {
+    for (const [file_] of existingMeta) {
+      if (!discoveredFiles.has(file_)) {
+        store.deleteFile(file_);
+      }
     }
   }
   const durationMs = Date.now() - startMs;
@@ -11031,7 +11509,8 @@ var TIER2_TOOLS = [
   planTool,
   taskTool,
   installTool,
-  auditTool
+  auditTool,
+  designTool
 ];
 var TIER3_TOOLS = [
   outdatedTool,
@@ -11076,6 +11555,7 @@ var builtinTools = [
   logsTool,
   documentTool,
   scaffoldTool,
+  designTool,
   toolSearchTool,
   toolUseTool,
   batchToolUseTool,
@@ -11249,6 +11729,6 @@ var TOOL_ICON_CONFIG = {
 };
 var FALLBACK_ICON = "fallback";
 
-export { CircuitBreaker, CircuitOpenError, FALLBACK_ICON, IndexCircuitBreaker, IndexTimeoutError, OPTIONAL_TOOLS, TIER1_TOOLS, TIER2_TOOLS, TIER3_TOOLS, TOOL_ICON_CONFIG, TOOL_ICON_MAP, _resetProcessRegistry, auditTool, bashTool, batchToolUseTool, builtinTools, builtinToolsPack, cancelPendingReindexes, codebaseIndexStats, codebaseIndexTool, codebaseSearchTool, codebaseStatsTool, configureExecPolicy, createGlobalPsSlashCommand, createModeTool, diffTool, documentTool, editTool, enqueueReindex, ensureSessionShell, execTool, fetchTool, forgetTool, formatGlobalStatus, formatInstanceList, formatInstanceSummary, formatTool, getExecAllowlist, getIndexState, getInstanceCount, getPersistentProcessRegistry, getProcessGuardian, getProcessRegistry, getToolIcon, gitTool, globTool, grepTool, indexCircuitBreaker, installTool, isExecCommandAllowed, isIndexReady, isIndexableFile, isIndexing, jsonTool, lintTool, listInstances, logsTool, normalizeShell, onIndexStateChange, outdatedTool, patchTool, planTool, readTool, relatedMemoryTool, rememberTool, replaceTool, resetExecPolicy, resetIndexCircuitBreaker, resetPersistentProcessRegistry, resolveSessionShell, runStartupIndex, scaffoldTool, searchCodebaseIndex, searchMemoryTool, searchTool, shutdownCodebaseIndexHost, startProcessGuardian, stopProcessGuardian, testTool, todoTool, toolHelpTool, toolSearchTool, toolUseTool, treeTool, typecheckTool, writeTool };
+export { CircuitBreaker, CircuitOpenError, FALLBACK_ICON, IndexCircuitBreaker, IndexTimeoutError, OPTIONAL_TOOLS, TIER1_TOOLS, TIER2_TOOLS, TIER3_TOOLS, TOOL_ICON_CONFIG, TOOL_ICON_MAP, _resetProcessRegistry, auditTool, bashTool, batchToolUseTool, builtinTools, builtinToolsPack, cancelPendingReindexes, codebaseIndexStats, codebaseIndexTool, codebaseSearchTool, codebaseStatsTool, configureExecPolicy, createGlobalPsSlashCommand, createModeTool, designTool, diffTool, documentTool, editTool, enqueueReindex, ensureSessionShell, execTool, fetchTool, forgetTool, formatGlobalStatus, formatInstanceList, formatInstanceSummary, formatTool, getExecAllowlist, getIndexState, getInstanceCount, getPersistentProcessRegistry, getProcessGuardian, getProcessRegistry, getToolIcon, gitTool, globTool, grepTool, indexCircuitBreaker, installTool, isExecCommandAllowed, isIndexReady, isIndexableFile, isIndexing, jsonTool, lintTool, listInstances, logsTool, normalizeShell, onIndexStateChange, outdatedTool, patchTool, planTool, readTool, relatedMemoryTool, rememberTool, replaceTool, resetExecPolicy, resetIndexCircuitBreaker, resetPersistentProcessRegistry, resolveSessionShell, runStartupIndex, scaffoldTool, searchCodebaseIndex, searchMemoryTool, searchTool, shutdownCodebaseIndexHost, startProcessGuardian, stopProcessGuardian, testTool, todoTool, toolHelpTool, toolSearchTool, toolUseTool, treeTool, typecheckTool, writeTool };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map