@wrongstack/tools 0.274.0 → 0.275.1

package/dist/builtin.js

@@ -1,6 +1,6 @@
 import { spawn, execFileSync } from 'node:child_process';
 import * as Core from '@wrongstack/core';
-import { buildChildEnv, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, isPrivateIPv4, isPrivateIPv6, assessCommitSafety, compileGlob, expectDefined, recordPackageAction, detectPackageEcosystem, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, mutateTasks, formatTaskList, formatPlan, toErrorMessage as toErrorMessage$2, computeTaskItemProgress, loadPlan, savePlan, loadTasks, saveTasks, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
+import { buildChildEnv, getDesignKitLoader, isDesignStack, loadActiveKit, applyTokenOverrides, setActiveKit, recordKitChoice, recordOverrides, setDesignOverrides, materializeTokens, runDesignVerify, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, isPrivateIPv4, isPrivateIPv6, assessCommitSafety, compileGlob, expectDefined, recordPackageAction, detectPackageEcosystem, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, mutateTasks, formatTaskList, formatPlan, toErrorMessage as toErrorMessage$2, computeTaskItemProgress, loadPlan, savePlan, loadTasks, saveTasks, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
 import * as fs from 'node:fs';
 import { statSync, mkdirSync, createWriteStream } from 'node:fs';
 import * as fs2 from 'node:fs/promises';
@@ -280,6 +280,7 @@ var CircuitBreaker = class {
     if (this.state === "open") return;
     this.state = "open";
     this.openedAt = Date.now();
+    this.window = [];
     try {
       this.onTrip?.();
     } catch {
@@ -319,7 +320,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
@@ -380,12 +381,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. */
@@ -549,13 +573,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(() => {
@@ -578,27 +603,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?.();
@@ -633,6 +643,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() {
@@ -1506,17 +1544,18 @@ function getPersistentProcessRegistry() {
 }
 
 // src/bash-kill-guard.ts
+var isWin2 = 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];
@@ -1525,15 +1564,43 @@ function extractKillCommand(command) {
 }
 function isKillRelatedCommand(cmd) {
   const normalized = cmd.toLowerCase().replace(/\s+/g, " ").trim();
+  if (isWin2) {
+    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 (isWin2) {
+    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";
@@ -1577,28 +1644,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() {
@@ -1675,7 +1720,7 @@ async function checkAndBlockKillCommand(command) {
   }
   return { blocked: false };
 }
-function pickShell(platform3, command, env) {
+function pickShell(platform4, 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";
@@ -1729,7 +1774,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, `;`, `&`, `|`, `(`, `{`, `,`.
@@ -1874,10 +1919,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]
       });
@@ -1906,7 +1951,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 = "";
@@ -1924,7 +1969,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) {
@@ -1942,7 +1987,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));
       }
@@ -1983,6 +2029,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, {
@@ -1993,7 +2047,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 {
@@ -2010,7 +2064,8 @@ var bashTool = {
         command: redactCommand(input.command),
         startedAt: Date.now(),
         sessionId: ctx.session?.id,
-        child
+        child,
+        processGroupLeader: detached && child.pid === pid
       });
     }
     let buf = "";
@@ -2019,7 +2074,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) {
@@ -2039,34 +2094,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;
@@ -2075,7 +2118,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 });
     }
@@ -2163,6 +2206,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 now = Date.now();
@@ -2174,7 +2225,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();
@@ -2184,6 +2235,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 });
+    }
   }
 };
 
@@ -5134,6 +5217,229 @@ var codebaseStatsTool = {
     };
   }
 };
+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 = path3.join(ctx.projectRoot, result.path);
+      let exists = false;
+      try {
+        await fs2.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 fs2.mkdir(path3.dirname(abs), { recursive: true });
+      await fs2.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>"}`.'
+    };
+  }
+};
 var diffTool = {
   name: "diff",
   category: "Filesystem",
@@ -5508,7 +5814,7 @@ var editTool = {
     const newFile = toStyle(newFileLf, style);
     await atomicWrite(absPath, newFile, { mode: updated.mode & 511 });
     const written = await fs2.stat(absPath);
-    ctx.recordRead(absPath, written.mtimeMs);
+    ctx.recordRead(absPath, written.mtimeMs, "write");
     ctx.session.recordFileChange({
       path: absPath,
       action: "modified",
@@ -5551,7 +5857,7 @@ function findSimilarity(haystack, needle) {
   }
   return line;
 }
-var isWin2 = process.platform === "win32";
+var isWin3 = process.platform === "win32";
 var DEFAULT_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
   // JS / TS toolchain
   "node",
@@ -5561,12 +5867,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
@@ -5579,10 +5898,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",
@@ -5594,18 +5925,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",
@@ -5621,8 +5959,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
@@ -5638,15 +5975,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,
@@ -5654,15 +5986,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) {
@@ -5789,7 +6155,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 = isWin2 && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
+    const needsShell = isWin3 && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
     const spawnCmd = needsShell ? cmd : resolved;
     if (needsShell) assertSafeWin32ShellArgs(args);
     let child;
@@ -5799,7 +6165,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
         env: buildChildEnv(sessionId),
         stdio: ["ignore", "pipe", "pipe"],
         windowsHide: true,
-        ...isWin2 ? {} : { signal },
+        ...isWin3 ? {} : { signal },
         ...needsShell ? { shell: true, windowsVerbatimArguments: true } : {}
       });
     } catch (err) {
@@ -5819,7 +6185,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 (isWin2) signal.removeEventListener("abort", onAbort);
+      if (isWin3) signal.removeEventListener("abort", onAbort);
       if (typeof pid === "number") registry.unregister(pid);
       registry.afterCall(Date.now() - startedAt, true);
       spool.finalize();
@@ -5849,7 +6215,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       if (typeof pid === "number") registry.kill(pid, { force: true });
       else child.kill("SIGTERM");
     };
-    if (isWin2) {
+    if (isWin3) {
       if (signal.aborted) onAbort();
       else signal.addEventListener("abort", onAbort, { once: true });
     }
@@ -5865,7 +6231,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      if (isWin2) signal.removeEventListener("abort", onAbort);
+      if (isWin3) signal.removeEventListener("abort", onAbort);
       if (typeof pid === "number") registry.unregister(pid);
       const durationMs = Date.now() - startedAt;
       const exitCode = killed ? 124 : code ?? 1;
@@ -6029,7 +6395,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:") {
@@ -6101,6 +6467,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);
     }
@@ -7193,6 +7567,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 };
   }
 };
@@ -7282,8 +7664,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;
@@ -7560,7 +7942,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 = [];
@@ -7569,7 +7951,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) {
@@ -7590,7 +7972,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,
@@ -10155,7 +10537,7 @@ var writeTool = {
       if (existed) {
         if (!ctx.hasRead(absPath)) {
           prev = await fs2.readFile(absPath, "utf8");
-          ctx.recordRead(absPath, stat12.mtimeMs);
+          ctx.recordRead(absPath, stat12.mtimeMs, "write");
         } else {
           prev = await fs2.readFile(absPath, "utf8");
         }
@@ -10169,7 +10551,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 fs2.stat(absPath);
-    ctx.recordRead(absPath, stat11.mtimeMs);
+    ctx.recordRead(absPath, stat11.mtimeMs, "write");
     ctx.session.recordFileChange({
       path: absPath,
       action: existed ? "modified" : "created",
@@ -10228,7 +10610,8 @@ var TIER2_TOOLS = [
   planTool,
   taskTool,
   installTool,
-  auditTool
+  auditTool,
+  designTool
 ];
 var TIER3_TOOLS = [
   outdatedTool,
@@ -10273,6 +10656,7 @@ var builtinTools = [
   logsTool,
   documentTool,
   scaffoldTool,
+  designTool,
   toolSearchTool,
   toolUseTool,
   batchToolUseTool,