@agent_forge/forge-dsh 0.1.0 → 0.1.1

package/README.md

@@ -35,6 +35,9 @@ task-verify, review-stop, skill-trigger, and the session-start group.
 - The `forge` CLI on `PATH` (`npm install -g @agent_forge/forge`), with the project
   initialized (`forge init`) for task gates to have state to enforce.
 - DeepSeek Harness `0.1.0-rc.x` (verified against `0.1.0-rc.7`), Node.js ≥ 18.
+- Windows works out of the box: npm lays out `forge` as a `forge.cmd` shim, which
+  the plugin spawns through `cmd.exe` (a bare spawn cannot execute it); timeout
+  kills tear down the whole child tree via `taskkill /T`.
 
 ## Install
 
@@ -93,7 +96,7 @@ Raise `timeoutMs` on big projects.
 
 ```sh
 npm install   # dev-only: @deepseek-ai/cordis for the wiring tests
-npm test      # 33 tests: mapping, runner, decision folding, real-cordis wiring
+npm test      # mapping, runner (incl. cross-OS planSpawn units), decision folding, real-cordis wiring
 ```
 
 `test/doubles/fake-forge.mjs` stands in for the forge binary; the wiring suite

package/lib/runner.js

@@ -29,6 +29,38 @@ import { spawn } from "node:child_process";
  * @property {string} [error]   - infrastructure failure note (fail-open path).
  */
 
+/**
+ * Plan the spawn for one hook invocation, platform-aware. Exported for the
+ * cross-OS unit tests — CI's Linux runners cannot execute the win32 route, so
+ * the planning logic must be assertable without spawning.
+ *
+ * Windows: npm lays out forge as forge + forge.cmd (no forge.exe), and
+ * CreateProcess cannot execute a .cmd shim — a bare spawn("forge") is ENOENT
+ * and EVERY gate silently fails open. cmd.exe resolves forge.cmd via PATHEXT
+ * (and a bare forge.exe directly), so win32 routes through it. argv holds
+ * spec constants only (safe charset). The binary is operator config and is
+ * quoted, never escaped — see the metacharacter note inside planSpawn.
+ *
+ * @param {string} forgeBin - binary name/path from config.
+ * @param {string[]} argv - hook arguments (spec constants).
+ * @param {string} [platform] - process.platform override (tests).
+ * @returns {{file: string, args: string[], shell: boolean}}
+ */
+export function planSpawn(forgeBin, argv, platform = process.platform) {
+  if (platform !== "win32") {
+    return { file: forgeBin, args: argv, shell: false };
+  }
+  // cmd.exe metacharacters: an unquoted & | ( ) < > ^ , ; = splits or redirects
+  // the token ("C:\A&B\forge.cmd" would execute a stray "B\forge.cmd"), so quote
+  // on any of them, not just spaces. Two things quoting cannot neutralize:
+  // %VAR% expansion (cmd expands it even inside quotes) and ! with delayed
+  // expansion (off by default). Both are accepted residual risk because
+  // forgeBin is trusted operator config — the same trust level as PATH itself.
+  const needsQuotes = /[&|()<>^,;=\s]/.test(forgeBin);
+  const file = needsQuotes && !forgeBin.includes('"') ? `"${forgeBin}"` : forgeBin;
+  return { file, args: argv, shell: true };
+}
+
 /**
  * Run one forge hook command.
  *
@@ -44,14 +76,26 @@ export function runForgeHook(command, payload, opts = {}) {
   const forgeBin = opts.forgeBin ?? "forge";
   const timeoutMs = opts.timeoutMs ?? 30000;
   const parts = command.split(" "); // ["forge","hook","task-guard"]
-  const argv = [forgeBin, ...parts.slice(1)];
+  const plan = planSpawn(forgeBin, parts.slice(1));
   return new Promise((resolve) => {
     let child;
     try {
-      child = spawn(argv[0], argv.slice(1), {
-        stdio: ["pipe", "pipe", "pipe"],
-        cwd: opts.cwd,
-      });
+      if (plan.shell) {
+        // Single command STRING (not file+args): passing an args array with
+        // shell:true is DEP0190 — args are concatenated unescaped. The pieces
+        // here are spec constants plus the pre-quoted binary (planSpawn), so
+        // the joined line is exactly what cmd.exe should parse.
+        child = spawn([plan.file, ...plan.args].join(" "), {
+          stdio: ["pipe", "pipe", "pipe"],
+          cwd: opts.cwd,
+          shell: true,
+        });
+      } else {
+        child = spawn(plan.file, plan.args, {
+          stdio: ["pipe", "pipe", "pipe"],
+          cwd: opts.cwd,
+        });
+      }
     } catch (error) {
       resolve({ block: false, error: note(error) });
       return;
@@ -64,10 +108,39 @@ export function runForgeHook(command, payload, opts = {}) {
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
-      try {
-        child.kill();
-      } catch {
-        // already exited — nothing to kill
+      // On the win32 shell route the direct child is cmd.exe and the forge
+      // grandchild holds the task index lock AND the inherited stdio pipes:
+      // killing only the shell ORPHANS the grandchild (a dead parent's tree
+      // is unfindable for /T) — it survives with the pipes open, pinning this
+      // process's event loop forever. taskkill /T /F is therefore the primary
+      // kill: it tears down shell + descendants atomically. kill() (wrapper
+      // only) is the FALLBACK for when taskkill itself fails — spawn error
+      // (not on PATH) or nonzero exit (access denied); killing just the
+      // wrapper then still beats killing nothing. Non-shell routes kill the
+      // forge process directly.
+      if (plan.shell && child.pid) {
+        const fallback = () => {
+          try {
+            child.kill();
+          } catch {
+            // already exited — nothing to kill
+          }
+        };
+        try {
+          const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+          killer.on("error", fallback);
+          killer.on("close", (c) => {
+            if (c !== 0) fallback();
+          });
+        } catch {
+          fallback();
+        }
+      } else {
+        try {
+          child.kill();
+        } catch {
+          // already exited — nothing to kill
+        }
       }
       resolve({ block: false, error: `timeout after ${timeoutMs}ms` });
     }, timeoutMs);
@@ -79,9 +152,19 @@ export function runForgeHook(command, payload, opts = {}) {
     };
     child.stdout.on("data", (d) => (out += d.toString()));
     child.on("error", (error) => settle({ block: false, error: note(error) }));
-    child.on("close", () => {
+    child.on("close", (code, signal) => {
       const text = out.trim();
-      if (text === "") return settle({ block: false });
+      if (text === "") {
+        // Exit 0 with no stdout is forge's clean silent allow. A NONZERO exit
+        // with no stdout is an infrastructure failure: on the win32 cmd.exe
+        // route a missing binary prints its error to stderr and exits — the
+        // spawn "error" event never fires because cmd.exe itself started
+        // fine. Fail open WITH an error note so /forge-status surfaces it.
+        // signal kills report code === null ("exited with code null" reads
+        // like a bug; name the signal instead).
+        const how = code === null ? `signal ${signal}` : `code ${code}`;
+        return settle(code === 0 ? { block: false } : { block: false, error: `forge exited with ${how} and no output` });
+      }
       try {
         const j = JSON.parse(text);
         const context = j?.hookSpecificOutput?.additionalContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent_forge/forge-dsh",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Forge quality gates for DeepSeek Harness (dsh): task gates, read-before-edit, bash hazard interception and quality scoring, driven by the forge CLI through DSH's typed interception points.",
   "repository": {
     "type": "git",