@agent_forge/forge-dsh 1.78.0 → 1.79.1

package/README.md

@@ -25,25 +25,30 @@ the forge binary — the plugin itself has **zero runtime dependencies**.
 | `agent/session-start` | `SessionStart`¹ | context via `agent.inject()` |
 | `agent/turn-stopping` | `Stop` | `agent.steer(reason)` → another step |
 
-¹ `source:'compact'` additionally fires forge's `PostCompact` group — DSH rc.7
-exposes no dedicated compaction point.
+¹ `source:'compact'` additionally fires forge's `PostCompact` group — the preview
+builds expose no dedicated compaction point.
 
 DSH tool names map onto the Claude Code names forge dispatches on
-(`write/edit/str_replace_editor→Write/Edit`, `bash/pwsh→Bash`, `read→Read`,
+(`write/edit/str_replace_editor→Write/Edit`, `bash/pwsh→Bash`, `read/read_image→Read`,
 `skill→Skill`); unmapped tools pass ungated. The wired hook roster mirrors
 forge's canonical spec (`lib/spec.json`, drift-guarded by a Go test in the Forge
 repo) — freeze-guard, task-guard, assertion-check, read-before-edit, bash-guard,
 hazard-guard, auto-compile, workflow-test-guard, file-sentinel, tool-track,
 test-nudge, failure-track (PostToolUseFailure), subagent-track (SubagentStop),
-task-verify, review-stop, skill-trigger, and the session-start group.
+task-verify, review-stop, skill-trigger, doc-lint, conventions-write, gate-cmd-form,
+task-drift, resume-reinject, compact-resume, conventions-context, and the
+session-start group.
 failure-track/subagent-track are mirrored in the spec but inert until DSH
-exposes the corresponding event points (rc.7 has neither).
+exposes the corresponding event points (the preview builds have neither).
 
 ## Requirements
 
 - 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.
+- DeepSeek Harness `0.1.0-rc.7` – `0.2.1-rc.2`, Node.js ≥ 18. The bridge contract is
+  pinned to `0.1.0-rc.7` ([`contract.json`](./contract.json)); `0.2.1-rc.2` is the
+  desktop build this plugin runs on (pre-tool interception verified live there; a
+  full five-event regression across the range is still pending).
 - 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`.
@@ -57,45 +62,67 @@ dsh plugin --profile web add @agent_forge/forge-dsh
 # or straight from the Forge repo (subdirectory install)
 dsh plugin --profile web add "github:MjxUpUp/Forge#main&path:/plugins/forge-dsh"
 
-# local development
-dsh plugin --profile web add "link:$(pwd)"
+# local development (run from this directory; `link:.` works on Windows too)
+dsh plugin --profile web add "link:."
 ```
 
-Restart `dsh web` after install. Check status inside a session with `/forge-status`.
+The plugin hot-loads into a running dsh — adding or removing the bundle reloads the
+profile. If a given build does not pick it up, restart the host once. Start a new
+session to pick up the SessionStart context, and check the bridge's state with
+`/forge-status` (probe result, wired groups, recent verdicts). To uninstall:
+`dsh plugin --profile <name> remove @agent_forge/forge-dsh` (the desktop app's profile
+is `desktop`), or keep it installed but inert with `enabled:false`.
 
 ## Config
 
+Keys go on the bundle entry in the profile's `cordis.patch.yml` — the user-editable
+patch layer. Do not edit the generated `cordis.yml`: the loader rewrites that root on
+every boot, so anything written there is lost (the desktop app manages its own profile
+under `~/.dsh/profiles/<profile>/`):
 ```yaml
-# profile patch
-- insert:
-    - id: forge-quality
-      name: "@agent_forge/forge-dsh"
-      config:
-        forgeBin: forge      # binary name/path (env FORGE_BIN overrides the default)
-        timeoutMs: 30000     # per-hook ceiling; timeout kills and FAILS OPEN
-        enabled: true        # false unwires every listener
-        debug: false         # log fail-open hook errors to console.error
+# ~/.dsh/profiles/<profile>/cordis.patch.yml
+- id: forge-quality
+  name: "@agent_forge/forge-dsh"
+  config:
+    forgeBin: forge      # binary name/path; FORGE_BIN only fills in when this key is absent
+    timeoutMs: 30000     # per-hook ceiling; timeout kills and FAILS OPEN
+    enabled: true        # false unwires every listener
+    debug: false         # log fail-open hook errors to console.error
 ```
 
 ## Fail-open contract
 
-Blocks are read from forge's stdout JSON (`decision:"block"`), never from exit
-codes — a forge internal error (exit 1) is indistinguishable from a deny otherwise.
-Every infrastructure failure (forge missing, spawn error, unparseable output,
-timeout) **fails open**: a forge outage never locks the agent out of its own tools.
-Such failures are silent by design; surface them with `/forge-status` or `debug:true`.
-
-Two latency trade-offs to know: hooks run **serially** per event (up to five per
+Blocks are read from forge's stdout JSON (`decision:"block"`), never inferred from
+exit codes: the verdict reason and its `additionalContext` exist only in that JSON,
+and forge reuses exit 2 for hard errors as well. Every infrastructure failure (forge
+missing, spawn error, unparseable output, timeout) **fails open**: a forge outage
+never locks the agent out of its own tools. Such hook-run failures are silent by
+design; surface them with `/forge-status` or `debug:true`.
+
+A missing `forge` binary is the one exception to that silence: each session start
+probes `forge --version` once (until a probe succeeds — the answer is then cached
+for the process lifetime) and, when the probe fails, injects a visible notice
+naming the configured `forgeBin`. Without it an uninstalled CLI would look exactly
+like a healthy plugin gating nothing. The notice is informational, not a switch —
+while the binary is missing, every hook attempt fails open on its own, so gates are
+inactive whether or not the probe ran. Installing forge needs no host restart: the
+next session probes again and gating resumes.
+
+Two latency trade-offs to know: hooks run **serially** per event (up to six per
 group), so a slow hook chain delays the tool call — and a gate that legitimately
 exceeds `timeoutMs` (e.g. `auto-compile` cold-building a large project past 30s)
 silently loses that run's feedback to fail-open (visible in `/forge-status`).
 Raise `timeoutMs` on big projects.
 
+`/forge-status` reports the probe line after the header: `probe: ok (forge version …)`,
+`probe: FAILED — gates inactive (…)`, or `not run yet` before the process's first
+session start.
+
 ## Known watch items (dsh preview)
 
-- **No stop-hook loop guard** in rc.7 — a permanently-failing Stop gate steers at
-  every stop boundary. forge's Stop gates are self-limiting once their gate passes,
-  but a stuck gate loops the turn.
+- **No stop-hook loop guard** in the preview builds (`0.1.0-rc.7` – `0.2.1-rc.2`) —
+  a permanently-failing Stop gate steers at every stop boundary. forge's Stop gates
+  are self-limiting once their gate passes, but a stuck gate loops the turn.
 - **SessionStart context is best-effort** (emit mode, detached): it may miss the
   first request of a very short-lived session — same limitation the official
   bridges document (`TODO(session-start-gating)`).

package/lib/index.js

@@ -28,8 +28,9 @@
  * @module @agent_forge/forge-dsh
  */
 import { readFileSync } from "node:fs";
+import { probeForge } from "./runner.js";
 import { runHookGroup, preExecuteDecision, postExecuteDecision, preStepDecision, turnStoppingOutcome, sessionStartOutcome } from "./decisions.js";
-import { buildEventPayload, buildToolPayload, matchedCommands, promptText, toCCToolName } from "./tools.js";
+import { buildEventPayload, buildToolPayload, matchedCommands, pluginMessage, promptText, toCCToolName } from "./tools.js";
 
 const spec = JSON.parse(readFileSync(new URL("./spec.json", import.meta.url), "utf8"));
 
@@ -66,6 +67,49 @@ function apply(ctx, config = {}) {
     }
   };
 
+  // A missing forge binary used to be completely silent: every hook failed
+  // open, so the plugin looked installed but gated nothing. Probe once per
+  // session start (retrying on later sessions, since installing forge needs no
+  // host restart) and surface the failure through agent.inject — the same
+  // channel forge's own advisories use. Once a probe succeeds the answer is
+  // cached for the process lifetime; forgeBin is static config per plugin
+  // instance, so it cannot go stale.
+  let forgeReady = false;
+  let lastProbe;
+  let probeInFlight;
+  const noticedAgents = new WeakSet();
+  const missingForgeNotice = (error) =>
+    `[forge-dsh] forge CLI not found (forgeBin: ${opts.forgeBin}). ` +
+    "Forge gates are OFF for this session — every action runs unguarded (fail-open). " +
+    "Install it with `npm install -g @agent_forge/forge`, then start a new session; " +
+    "if it lives elsewhere, set forgeBin in the profile patch." +
+    (error === undefined ? "" : `\nProbe error: ${error}`);
+  const ensureForge = async (agent) => {
+    if (forgeReady) return true;
+    if (probeInFlight === undefined) {
+      probeInFlight = probeForge({ forgeBin: opts.forgeBin, timeoutMs: Math.min(opts.timeoutMs, 5000) })
+        .finally(() => {
+          probeInFlight = undefined;
+        });
+    }
+    const probe = await probeInFlight;
+    lastProbe = probe;
+    if (probe.ok) {
+      forgeReady = true;
+      return true;
+    }
+    if (debug) console.error(`[forge-dsh] forge probe failed: ${probe.error}`);
+    if (agent != null && !noticedAgents.has(agent)) {
+      noticedAgents.add(agent);
+      try {
+        await agent.inject?.(pluginMessage(missingForgeNotice(probe.error)));
+      } catch {
+        // a throwing (or rejecting) inject must never interrupt session start
+      }
+    }
+    return false;
+  };
+
   // PreToolUse — deny short-circuits the tool call.
   ctx.effect(() => ctx.on("tools/pre-execute", async (exec, next) => {
     const commands = matchedCommands(spec.PreToolUse, toCCToolName(exec?.name ?? ""));
@@ -102,6 +146,7 @@ function apply(ctx, config = {}) {
     const agent = payload?.agent;
     const source = payload?.source;
     (async () => {
+      await ensureForge(agent);
       const start = await runHookGroup(
         matchedCommands(spec.SessionStart, ""),
         buildEventPayload("SessionStart", agent, { source }),
@@ -170,9 +215,14 @@ function apply(ctx, config = {}) {
               if (r.errors.length > 0) parts.push(`FAIL-OPEN: ${r.errors.join("; ")}`);
               return parts.join("  ");
             }).join("\n");
+        const probeLine = lastProbe === undefined
+          ? "not run yet (no session start in this process)"
+          : lastProbe.ok
+            ? `ok${lastProbe.version === undefined ? "" : ` (${lastProbe.version.slice(0, 80)})`}`
+            : `FAILED — gates inactive (${lastProbe.error})`;
         return {
           kind: "success",
-          text: `# Forge quality gates\n\nforgeBin: ${opts.forgeBin}  timeoutMs: ${opts.timeoutMs}\n\n## Wired groups\n${groups}\n\n## Verdict summary (last ${recentRuns.length} runs)\n  runs=${summary.runs}  blocked=${summary.blocked}  fail-open=${summary.failOpen}  contexts=${summary.contexts}\n\n## Recent runs (last 10)\n${runs}`,
+          text: `# Forge quality gates\n\nforgeBin: ${opts.forgeBin}  timeoutMs: ${opts.timeoutMs}\nprobe: ${probeLine}\n\n## Wired groups\n${groups}\n\n## Verdict summary (last ${recentRuns.length} runs)\n  runs=${summary.runs}  blocked=${summary.blocked}  fail-open=${summary.failOpen}  contexts=${summary.contexts}\n\n## Recent runs (last 10)\n${runs}`,
         };
       },
     }), "forge: status command");

package/lib/runner.js

@@ -108,40 +108,7 @@ export function runForgeHook(command, payload, opts = {}) {
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
-      // 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
-        }
-      }
+      killTree(child, plan.shell);
       resolve({ block: false, error: `timeout after ${timeoutMs}ms` });
     }, timeoutMs);
     const settle = (verdict) => {
@@ -199,6 +166,114 @@ export function runForgeHook(command, payload, opts = {}) {
   });
 }
 
+/**
+ * Kill a spawned forge and, on the win32 shell route, its whole process tree.
+ *
+ * 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.
+ *
+ * @param {import("node:child_process").ChildProcess} child
+ * @param {boolean} shell - planSpawn's shell flag for this child.
+ */
+function killTree(child, shell) {
+  if (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", (code) => {
+        if (code !== 0) fallback();
+      });
+    } catch {
+      fallback();
+    }
+  } else {
+    try {
+      child.kill();
+    } catch {
+      // already exited — nothing to kill
+    }
+  }
+}
+
+/**
+ * Probe whether the configured forge binary is runnable: one `forge --version`
+ * spawn, stdout captured, bounded by `timeoutMs` (default 5000 — a probe must
+ * never hold up session start for a hook-sized 30s). Fail-open like the hook
+ * path: resolves `{ok:false, error}` instead of throwing, so a missing or
+ * broken binary can be reported to the user rather than silently voiding every
+ * gate.
+ *
+ * The `--version` subcommand does not read stdin (verified against forge
+ * 1.79.0), so stdin is ignored; a hung probe is killed with the same
+ * tree-safe kill as a hook.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.forgeBin="forge"]
+ * @param {number} [opts.timeoutMs=5000]
+ * @returns {Promise<{ok: boolean, version?: string, error?: string}>}
+ */
+export function probeForge(opts = {}) {
+  const forgeBin = opts.forgeBin ?? "forge";
+  const timeoutMs = opts.timeoutMs ?? 5000;
+  const plan = planSpawn(forgeBin, ["--version"]);
+  return new Promise((resolve) => {
+    let child;
+    try {
+      const args = plan.shell ? [[plan.file, ...plan.args].join(" ")] : [plan.file, plan.args];
+      child = spawn(...args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        ...(plan.shell ? { shell: true } : {}),
+      });
+    } catch (error) {
+      resolve({ ok: false, error: note(error) });
+      return;
+    }
+    let out = "";
+    let err = "";
+    let settled = false;
+    let timer;
+    const finish = (verdict) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(verdict);
+    };
+    timer = setTimeout(() => {
+      killTree(child, plan.shell);
+      finish({ ok: false, error: `timeout after ${timeoutMs}ms` });
+    }, timeoutMs);
+    child.stdout.on("data", (d) => (out += d.toString()));
+    child.stderr.on("data", (d) => (err += d.toString()));
+    child.on("error", (error) => finish({ ok: false, error: note(error) }));
+    child.on("close", (code) => {
+      if (code === 0) {
+        const version = out.trim();
+        finish(version === "" ? { ok: true } : { ok: true, version });
+        return;
+      }
+      // A missing binary on the win32 cmd.exe route exits nonzero with its
+      // message on stderr (cmd.exe itself spawned fine, so no 'error' event);
+      // keep that tail — it is the only diagnostic the user sees.
+      const tail = err.trim().slice(0, 200);
+      finish({ ok: false, error: `forge --version exited with code ${code}${tail === "" ? "" : `: ${tail}`}` });
+    });
+  });
+}
+
 function note(error) {
   return (error instanceof Error ? error.message : String(error)).slice(0, 300);
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@agent_forge/forge-dsh",
-  "version": "1.78.0",
+  "version": "1.79.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",
     "url": "https://github.com/MjxUpUp/Forge",
     "directory": "plugins/forge-dsh"
   },
+  "homepage": "https://github.com/MjxUpUp/Forge/tree/main/plugins/forge-dsh",
   "type": "module",
   "main": "lib/index.js",
   "files": [