@boyingliu01/xp-gate 0.35.24 → 0.36.0

package/hooks/gate-9.sh

@@ -1,3 +1,22 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ⚠️  DEAD CODE — NOT EXECUTED. Read this before changing anything here.       
+# ============================================================================
+# This file is NOT sourced by githooks/pre-commit or githooks/pre-push (both
+# source count = 0; verify with: grep -c "gate-9.sh" githooks/pre-commit).
+# It is shipped by githooks/install.sh but never runs.
+#
+# The gate that actually runs semgrep SAST is githooks/gate-10.sh, and it
+# reports as `gate10_sast`. Gate 9 in the report is `gate9_build_integrity`
+# (Build Integrity), a different gate entirely.
+#
+# This mislabelling is not cosmetic: in #717 a C# SAST fix was first written
+# into THIS file, where it changed nothing, while .cs stayed ungoverned. The
+# C# ruleset loading that works lives in gate-10.sh. Do not relocate it here.
+#
+# Kept rather than deleted because githooks/install.sh:GATE_SCRIPTS ships it;
+# removing it is a separate change. See issue #717 walkthrough MC-03.
+# ============================================================================
 # ============================================================================
 # GATE 9: Semgrep SAST Security Scan
 # Detects security vulnerabilities (SQL injection, XSS, etc.) in staged files
@@ -112,8 +131,22 @@ EOF
     # code is demoted to "did the tool itself run". --error stays OFF: it would
     # add nothing the JSON does not already provide, and keeping it off leaves
     # failure exit codes unambiguous for the #475 diagnostics path.
+    # #717: p/security-audit carries NO C# rules. Measured: a .cs file with a
+    # textbook SQL injection (string-concatenated SqlCommand) and a
+    # Process.Start command injection produced 0 findings under
+    # p/security-audit and 1 ERROR under p/csharp. Since gate-9.sh:45 lists
+    # `cs` in the file filter, .cs was accepted and then scanned by a ruleset
+    # that cannot see C# -- the identical "filter looks like coverage" defect
+    # this issue removed from Gate 4. p/csharp is loaded IN ADDITION to
+    # p/security-audit (not instead of: the security-audit rules still apply
+    # to the other languages in a mixed commit).
+    SEMGREP_RULES=(--config=p/security-audit)
+    if printf "%s
+" "$SEMGREP_FILES" | grep -qE ".cs$"; then
+      SEMGREP_RULES+=(--config=p/csharp)
+    fi
     SEMGREP_STDOUT_FILE=$(mktemp)
-    SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
+    SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan "${SEMGREP_RULES[@]}" --json --disable-version-check "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
     SEMGREP_EXIT=$?
 
     # One node pass over the JSON: first line = verdict counts, remaining lines =
@@ -191,7 +224,9 @@ console.log("");});
       echo "  ❌ BLOCKED — blocking-severity vulnerability found"
       echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
       echo "$FINDING_DETAILS"
-      echo "  Run 'semgrep scan --config=p/security-audit' to review all findings."
+      # #717: name BOTH rulesets. A C# finding comes from p/csharp, so
+      # pointing the author at p/security-audit alone reproduces zero hits.
+      echo "  Run 'semgrep scan --config=p/security-audit --config=p/csharp' to review all findings."
       GATE_9_STATUS="FAIL"
       exit 1
     else

package/hooks/gate-registry.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# ============================================================================
+# GATE REGISTRY — the single source of truth for "which gate is which"
+# ============================================================================
+#
+# WHY THIS FILE EXISTS
+#
+# Gate numbers alone are not self-describing, and the numbers are not stable
+# facts about the repository — they are labels. Three sources disagreed about
+# what "Gate 9" is:
+#
+#   root AGENTS.md      -> Semgrep SAST          (WRONG)
+#   githooks/AGENTS.md  -> Build Integrity       (right)
+#   pre-commit actual   -> Build Integrity       (right)
+#
+# In issue #717 a C# SAST fix was written into githooks/gate-9.sh, because the
+# root document said Gate 9 was SAST. SAST is gate 10. gate-9.sh is not sourced
+# by any hook and never executes, so the fix changed nothing while appearing to
+# land. The defect was not "the number was hard to remember" — it was that
+# nothing connected a gate's NAME to the FILE that runs it.
+#
+# This registry makes that connection explicit and testable. The drift test
+# (githooks/__tests__/gate-registry.test.bats) asserts every `impl` below
+# against the code, so a document that disagrees with reality, or a fix that
+# lands in a file nobody sources, fails immediately.
+#
+# COLUMNS
+#   name    stable semantic id — use this in prose, commits, and tests
+#   number  display label only. Mirrors the report key (gateN_*) for backward
+#           compatibility; do NOT treat it as the identity of the gate.
+#   impl    where the gate actually runs. One of:
+#             <script>.sh   a file sourced/executed by pre-commit
+#             inline        implemented inside pre-commit itself
+#   blocks  YES  the gate can reject a commit
+#           NO   the gate reports but cannot reject
+#
+# USAGE
+#   source githooks/gate-registry.sh
+#   gate_name_for_file gate-10.sh      # -> sast
+#   gate_impl sast                     # -> gate-10.sh
+#   gate_number sast                   # -> 10
+#   gate_can_block sast                # -> YES
+#   gate_registry_dump                 # -> one line per gate
+#
+# ⚠️ Adding a gate: add a row here AND update the drift test's expectations.
+#    A gate that exists only in pre-commit and not here is a gate nobody can
+#    look up by name — which is how #717's wrong-file patch happened.
+# ============================================================================
+
+# name|number|impl|blocks
+GATE_REGISTRY_ROWS=(
+  "version-consistency|0|inline|YES"
+  "code-quality|1|inline|NO"
+  "duplicate-code|2|inline|NO"
+  "complexity|3|gate-3.sh|YES"
+  "principles|4|gate-4.sh|YES"
+  "tests-coverage|5|inline|YES"
+  "architecture|6|inline|YES"
+  "iac-security|7|gate-7.sh|YES"
+  "secret-scanning|8|gate-8.sh|YES"
+  "build-integrity|9|inline|NO"
+  "sast|10|gate-10.sh|YES"
+  "sprint-flow|11|sprint-gate.sh|YES"
+  "file-hygiene|12|gate-12-file-hygiene.sh|NO"
+  "compiler-strictness|13|gate-13-compiler-strictness.sh|YES"
+)
+
+# Human-readable title for each name. Kept separate from the row above so the
+# title can change without touching the lookup keys.
+_gate_title() {
+  case "$1" in
+    version-consistency) echo "Version Consistency" ;;
+    code-quality)        echo "Code Quality (Static + Lint)" ;;
+    duplicate-code)      echo "Duplicate Code" ;;
+    complexity)          echo "Cyclomatic Complexity" ;;
+    principles)          echo "Clean Code + SOLID" ;;
+    tests-coverage)      echo "Tests + Coverage" ;;
+    architecture)        echo "Architecture + Boy Scout Rule" ;;
+    iac-security)        echo "IaC Security Scanning" ;;
+    secret-scanning)     echo "Secret Scanning" ;;
+    build-integrity)     echo "Build Integrity" ;;
+    sast)                echo "SAST Security Scan" ;;
+    sprint-flow)         echo "Sprint Flow Enforcement" ;;
+    file-hygiene)        echo "File Hygiene Check" ;;
+    compiler-strictness) echo "Compiler Strictness" ;;
+    *) return 1 ;;
+  esac
+}
+
+# ---------------------------------------------------------------------------
+# Lookups. Each returns non-zero when the name is unknown, so a typo fails
+# loudly instead of silently matching nothing.
+# ---------------------------------------------------------------------------
+
+# gate_row <name> -> echoes the raw row, or returns 1.
+gate_row() {
+  local want="$1" row
+  for row in "${GATE_REGISTRY_ROWS[@]}"; do
+    case "$row" in
+      "$want"\|*) printf '%s\n' "$row"; return 0 ;;
+    esac
+  done
+  return 1
+}
+
+# _gate_field <name> <1-based field index>
+_gate_field() {
+  local row
+  row=$(gate_row "$1") || return 1
+  printf '%s\n' "$row" | cut -d'|' -f"$2"
+}
+
+gate_number()  { _gate_field "$1" 2; }
+gate_impl()    { _gate_field "$1" 3; }
+gate_blocks()  { _gate_field "$1" 4; }
+gate_can_block() { [ "$(gate_blocks "$1")" = "YES" ] && echo YES || echo NO; }
+gate_title()   { _gate_title "$1"; }
+
+# gate_name_for_number <N> -> echoes the semantic name.
+gate_name_for_number() {
+  local want="$1" row
+  for row in "${GATE_REGISTRY_ROWS[@]}"; do
+    case "$row" in
+      *\|"$want"\|*) printf '%s\n' "${row%%|*}"; return 0 ;;
+    esac
+  done
+  return 1
+}
+
+# gate_name_for_file <file> -> semantic name of the gate implemented by <file>.
+# Returns 1 for `inline` gates and unknown files. This is the lookup that would
+# have caught #717: gate-9.sh resolves to build-integrity, not sast.
+gate_name_for_file() {
+  local want="$1" row impl name
+  for row in "${GATE_REGISTRY_ROWS[@]}"; do
+    name="${row%%|*}"
+    impl=$(printf '%s\n' "$row" | cut -d'|' -f3)
+    [ "$impl" = "$want" ] && { printf '%s\n' "$name"; return 0; }
+  done
+  return 1
+}
+
+# List every script the registry claims the hook runs.
+gate_all_impls() {
+  local row impl
+  for row in "${GATE_REGISTRY_ROWS[@]}"; do
+    impl=$(printf '%s\n' "$row" | cut -d'|' -f3)
+    [ "$impl" != "inline" ] && printf '%s\n' "$impl"
+  done
+}
+
+gate_registry_dump() {
+  local row name num impl blocks
+  for row in "${GATE_REGISTRY_ROWS[@]}"; do
+    name="${row%%|*}"
+    num=$(printf '%s\n' "$row" | cut -d'|' -f2)
+    impl=$(printf '%s\n' "$row" | cut -d'|' -f3)
+    blocks=$(printf '%s\n' "$row" | cut -d'|' -f4)
+    printf '%-3s %-22s %-34s %-6s %s\n' "$num" "$name" "$(_gate_title "$name")" "$blocks" "$impl"
+  done
+}

package/hooks/lib/test-failure.sh

@@ -31,6 +31,20 @@ has_real_failure_marker() {
 is_runner_infrastructure_error() {
   local _out="$1"
   [ -n "$_out" ] || return 1
+  # #717: dotnet/VSTest's testhost failing to START is the same class of event
+  # -- the runner could not run, so no test was judged. Its signature is a
+  # Win32Exception from ProcessManager.OpenProcess (the testhost cannot open a
+  # handle to its own parent) followed by "Testhost process exited with error".
+  # Without this arm, a .NET repo on a machine with that permission fault would
+  # report "Tests FAILED" on every commit for a reason that has nothing to do
+  # with its tests.
+  #
+  # A real dotnet failure ("Failed!", "Failed: 3") never carries these strings,
+  # so the has_real_failure_marker guard below still lets genuine failures block.
+  if printf '%s' "$_out" | grep -qE 'Win32Exception|Testhost.*(exited with error|已退出)|test host.*(could not|did not) start'; then
+    has_real_failure_marker "$_out" && return 1
+    return 0
+  fi
   printf '%s' "$_out" | grep -qE 'Unhandled Error' || return 1
   has_real_failure_marker "$_out" && return 1
   return 0
@@ -116,10 +130,21 @@ handle_test_failure() {
   local _ctx="$2"
   if is_runner_infrastructure_error "$_out"; then
     echo ""
-    echo "⏭️  SKIPPED - vitest runner infrastructure error (no test failed)"
-    echo "    Detected: Unhandled Errors with 0 failed tests."
-    echo "    Known Windows issue: EPERM on vitest temp/ssr cache (#454)."
-    echo "    Workaround: npx vitest run --no-file-parallelism <targets>"
+    # The advice has to match the runner that failed (#717). A C# developer
+    # handed the vitest EPERM workaround would chase a cache problem in a
+    # language they are not using, and the real cause -- the testhost could not
+    # open a handle to its own parent -- would never be named.
+    if printf '%s' "$_out" | grep -qE 'Win32Exception|Testhost.*(exited with error|已退出)|test host.*(could not|did not) start'; then
+      echo "⏭️  SKIPPED - dotnet test host could not start (no test was judged)"
+      echo "    Detected: VSTest testhost exited before running a test."
+      echo "    This is an environment fault, NOT a test verdict -- it must not block."
+      echo "    Check: antivirus / endpoint protection blocking process handles, or run the suite outside this path."
+    else
+      echo "⏭️  SKIPPED - vitest runner infrastructure error (no test failed)"
+      echo "    Detected: Unhandled Errors with 0 failed tests."
+      echo "    Known Windows issue: EPERM on vitest temp/ssr cache (#454)."
+      echo "    Workaround: npx vitest run --no-file-parallelism <targets>"
+    fi
     TESTS_SKIPPED=true
     TESTS_EXIT_CODE=0
     return 0

package/hooks/pre-commit

@@ -271,6 +271,17 @@ if [ -z "$GATE_DIR" ]; then
   GATE_DIR="$ADAPTER_DIR"
 fi
 
+# Gate registry (#717 walkthrough): binds each gate's NAME to the file that
+# runs it, so a gate can be referred to by what it does rather than by a
+# positional number. Optional by design — a consumer repo installed from an
+# older package will not have it, and the hooks must keep working there.
+_GATE_REGISTRY="$GATE_DIR/gate-registry.sh"
+[ -f "$_GATE_REGISTRY" ] || _GATE_REGISTRY="$(git rev-parse --show-toplevel 2>/dev/null)/githooks/gate-registry.sh"
+if [ -f "$_GATE_REGISTRY" ]; then
+  # shellcheck source=/dev/null
+  . "$_GATE_REGISTRY"
+fi
+
 # Trap: ensure quality report generated on ANY exit (pass or fail).
 # Using a guard prevents recursion when 'exit' is called from inside the trap.
 # IMPORTANT: Captures exit status FIRST so generate_quality_report cannot override it.
@@ -1267,6 +1278,14 @@ if [ -z "$PROJECT_LANGS" ] && [ -z "$_CONFIG_LANGS" ]; then
   if [ "$(_detect_ext_lang "ps1" "psm1")" = "1" ]; then
     PROJECT_LANGS="$PROJECT_LANGS powershell"
   fi
+  # #717: without this arm a staged .cs file never produced a `csharp` entry in
+  # PROJECT_LANGS, so the per-language loop at the adapter-routing site had no
+  # turn in which to resolve adapters/csharp.sh -- the adapter was unreachable
+  # no matter how correct it was. Detection on extensions (not manifests) is why
+  # one arm is enough: a repo staging .cs always lands here.
+  if [ "$(_detect_ext_lang "cs" "csx")" = "1" ]; then
+    PROJECT_LANGS="$PROJECT_LANGS csharp"
+  fi
   # IaC: .tf, .tfvars, Dockerfile, docker-compose*, .yaml/.yml in kube context
   if echo "$CHANGED_FILES" | grep -qE '(\.tf$|\.tfvars$|Dockerfile|docker-compose)' 2>/dev/null; then
     PROJECT_LANGS="$PROJECT_LANGS iac"
@@ -2256,7 +2275,18 @@ else
         if [ "$LINT_EXIT" -ne 0 ]; then
           echo "ℹ️  Lint check had issues (may be non-blocking)"
         fi
-    
+
+        # #717: rc=2 is the adapters' "could not execute" channel (no toolchain,
+        # or a tool that refused to start), distinct from rc=1 "ran and found
+        # problems". Collapsing both into one SKIPPED line -- as this branch did
+        # -- makes a permanently-broken analyzer indistinguishable from a clean
+        # one, which is the silent-failure shape #717 is about. The gate still
+        # does not block (tool-missing must not block), but the reason is now
+        # named in the log instead of implied.
+        if [ "$ANALYSIS_EXIT" -eq 2 ] || [ "$LINT_EXIT" -eq 2 ]; then
+          echo "⏭️  SKIPPED - Code quality (${CURRENT_LANG} toolchain could not execute — NOT a pass)"
+        fi
+
         if [ "$ANALYSIS_EXIT" -eq 0 ] && [ "$LINT_EXIT" -eq 0 ]; then
           echo "✅ PASSED - Language-specific code quality checks."
         else
@@ -4307,8 +4337,72 @@ JAVAARCHROOTS
           fi
         fi
         ;;
+      "csharp")
+        # #717: C# had no arm at all, so it fell through to the `*)` default
+        # below and was reported as "not configured for csharp" -- a language
+        # the gate silently could not measure, with no way to configure it
+        # either, because the config file was never looked for.
+        #
+        # Architecture for .NET is normally expressed as *tests* (NetArchTest,
+        # ArchUnitNET, or a plain xUnit project asserting layering). There is no
+        # universal CLI, so this arm keys off a config the project opts into,
+        # exactly like the Go arm's arch-go.yaml.
+        if [ -f "arch-csharp.yaml" ] || [ -f ".xp-gate/arch-csharp.yaml" ]; then
+          _cs_arch_cfg="arch-csharp.yaml"
+          [ -f "$_cs_arch_cfg" ] || _cs_arch_cfg=".xp-gate/arch-csharp.yaml"
+          # Find an architecture test project: a .csproj whose name or contents
+          # mention architecture tests. Guessing one fixed path is the #602
+          # defect, which reported "not configured" for repos that had them.
+          _cs_arch_proj=""
+          while IFS= read -r _p; do
+            [ -n "$_p" ] || continue
+            if grep -qiE "architecture|archunit|netarchtest" "$_p" 2>/dev/null; then
+              _cs_arch_proj="$_p"
+              break
+            fi
+          done <<CSARCHPROJ
+$(git ls-files '*.csproj' 2>/dev/null)
+CSARCHPROJ
+
+          if [ -z "$_cs_arch_proj" ]; then
+            echo "     ℹ️  No architecture test project found - skipping C# architecture"
+            echo "     ⏭️  SKIPPED - C# architecture validation (no arch test project)"
+            if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+              GATE_6_REASON_BY_LANG["$CURRENT_LANG"]="architecture_not_configured"
+            fi
+          elif ! command -v dotnet >/dev/null 2>&1; then
+            echo "     ⏭️  SKIPPED - C# architecture validation (dotnet SDK not installed)"
+            if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+              GATE_6_REASON_BY_LANG["$CURRENT_LANG"]="tool_missing"
+            fi
+          else
+            echo "     Running C# architecture tests ($_cs_arch_proj)..."
+            # Same reading as the Go/Java arms (#630/#602): the checker's own
+            # status decides the verdict. Piping into `tail` and printing
+            # "completed" unconditionally is the fail-open shape those issues
+            # removed; PIPESTATUS[0] is what keeps this arm from repeating it.
+            dotnet test "$_cs_arch_proj" --nologo 2>&1 | tail -20
+            _cs_arch_rc="${PIPESTATUS[0]}"
+            if [ "$_cs_arch_rc" -ne 0 ]; then
+              echo ""
+              echo "❌ BLOCKED - C# architecture violations ($_cs_arch_proj, exit $_cs_arch_rc)"
+              echo "Fix the layering violation(s) above before committing."
+              if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+                GATE_6_REASON_BY_LANG["$CURRENT_LANG"]="architecture_tests_failed"
+              fi
+              exit 1
+            fi
+            echo "     ✅ C# architecture validation completed."
+          fi
+        else
+          echo "     ℹ️  No arch-csharp.yaml found - skipping C# architecture"
+          echo "     ⏭️  SKIPPED - C# architecture validation (no config)"
+          if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+            GATE_6_REASON_BY_LANG["$CURRENT_LANG"]="architecture_not_configured"
+          fi
+        fi
+        ;;
       *)
-        echo "     ℹ️  Architecture validation not configured for $CURRENT_LANG"
         echo "     ⏭️  SKIPPED - Architecture validation (not configured for $CURRENT_LANG)"
         # #537: archlint ships no detector for this language. Say so in a way
         # the quality report can read, instead of leaving the dimension silent.
@@ -4987,6 +5081,19 @@ if [ -n "$MIRROR_STAGED" ] && printf '%s\n' "$MIRROR_STAGED" | grep -qE '^(githo
       # each other, and the only way past was to edit a generated file by hand.
       case "$_mf" in
         */__tests__/*) continue ;;
+        # AGENTS.md is documentation, not a hook artifact: sync-package-content.js
+        # copies the hook suite, and no AGENTS.md exists under hooks/. Demanding a
+        # mirror for it reported a BLOCK on every doc edit (harmless only because
+        # GATE_FAILED was never read -- see below).
+        */AGENTS.md) continue ;;
+        # `githooks/adapters/` mirrors to `src/npm-package/adapters/`, NOT under
+        # `hooks/` -- that is what scripts/check-hook-mirror.sh declares (line 6)
+        # and what sync-package-content.js writes. The blanket `githooks/*` rule
+        # below sent it to `src/npm-package/hooks/adapters/<f>`, a path that has
+        # never existed, so ANY edit to an adapter was un-committable with
+        # "has no mirror at". It stayed hidden because nobody had edited an
+        # adapter since this gate was narrowed to diff files.
+        githooks/adapters/*) _mm="src/npm-package/adapters/${_mf#githooks/adapters/}" ;;
         githooks/*) _mm="src/npm-package/hooks/${_mf#githooks/}" ;;
         plugins/*/src/*) _mm=$(printf '%s' "$_mf" | sed 's|^plugins/\([^/]*\)/src/|src/npm-package/plugins/\1/src/|') ;;
         *) continue ;;
@@ -5006,7 +5113,15 @@ if [ -n "$MIRROR_STAGED" ] && printf '%s\n' "$MIRROR_STAGED" | grep -qE '^(githo
       echo "❌ BLOCKED - Gate 12b: $MIRROR_FAIL mirror parity violation(s)."
       echo "   The mirror is what gets published; a mirror-only fix is silently"
       echo "   reverted by the next prepack (v0.27.3 shipped that bug)."
-      GATE_FAILED=1
+      # BLOCKS, and must actually block. This used to set GATE_FAILED=1, a
+      # variable that appears exactly once in this file -- the assignment --
+      # and is read nowhere, so the gate printed BLOCKED on every doc edit and
+      # let the commit through. A gate that reports a verdict nobody consumes is
+      # the same failure as a filter that accepts a file no adapter claims:
+      # it looks like enforcement. exit is the contract every other blocking
+      # gate here uses (see Gate 13: `exit "$_g13_worst"`).
+      GATE_12_STATUS=WARN
+      exit 1
     else
       echo "✅ PASSED - Gate 12b: mirror parity (touched files)"
     fi
@@ -5061,6 +5176,10 @@ elif [ -f "$GATE_DIR/gate-13-compiler-strictness.sh" ] || [ -f "$(git rev-parse
 
     gate13_run_cpp_analysis;   _g13_rc=$?; _g13_note "$_g13_rc"
     gate13_run_java_analysis;  _g13_rc=$?; _g13_note "$_g13_rc"
+    # #717: C# joins the same reduce-the-worst loop. Without this call the
+    # function would exist but never execute -- the "silently skipped" shape
+    # #717 is about, one level up.
+    gate13_run_csharp_analysis; _g13_rc=$?; _g13_note "$_g13_rc"
     gate13_run_analyzer;       _g13_rc=$?; _g13_note "$_g13_rc"
 
     exit "$_g13_worst"

package/lib/__tests__/agent-runtime-journal.test.js

@@ -58,27 +58,41 @@ function journalText(events) {
 function toolPair(callId, name, args, startT, endT, result = {}, pos = {}) {
   const turn = pos.turn ?? 1;
   const step = pos.step ?? 1;
-  return [
-    { type: 'tool/call', time: startT, data: { turn, step, callId, name, arguments: JSON.stringify(args) } },
-    {
-      type: 'tool/result',
-      time: endT,
-      data: {
-        turn,
-        step,
-        message: {
-          role: 'tool',
-          toolCallId: callId,
-          isError: !!result.isError,
-          content: [{ type: 'text', text: result.text ?? 'ok' }],
-        },
-      },
-    },
-  ];
+  const call = {
+    type: 'tool/call',
+    time: startT,
+    data: { turn, step, callId, name, arguments: JSON.stringify(args) },
+  };
+  // Built separately so the pair stays flat: inlining it put the event five
+  // objects deep, which trips clean-code.deep-nesting (max 4) on every run.
+  const reply = {
+    type: 'tool/result',
+    time: endT,
+    data: { turn, step, message: toolResultMessage(callId, result) },
+  };
+  return [call, reply];
+}
+
+/** The `message` payload of a tool/result event. */
+function toolResultMessage(callId, result) {
+  return {
+    role: 'tool',
+    toolCallId: callId,
+    isError: !!result.isError,
+    content: [{ type: 'text', text: result.text ?? 'ok' }],
+  };
 }
 
 describe('parseSessionBuffer', () => {
-  it('reads a zstd-compressed session journal', () => {
+  // `zlib.zstdCompressSync` / `zstdDecompressSync` landed in Node 22. CI pins
+  // Node 20.x, so without this guard the test throws "zstdCompressSync is not a
+  // function" there and turns Gate 5 red on a machine difference rather than a
+  // code defect. Locally (Node 24) it passed, which is exactly why the gap
+  // survived. Feature-detected rather than version-sniffed, so a backport or a
+  // future rename cannot silently disable the coverage.
+  const hasZstd = typeof zlib.zstdCompressSync === 'function' && typeof zlib.zstdDecompressSync === 'function';
+
+  it.skipIf(!hasZstd)('reads a zstd-compressed session journal', () => {
     const events = toolPair('c1', 'read', { file_path: '/a.ts' }, 1000, 1010);
     const buf = zlib.zstdCompressSync(Buffer.from(journalText(events), 'utf8'));
     const parsed = parseSessionBuffer(buf);
@@ -86,6 +100,16 @@ describe('parseSessionBuffer', () => {
     expect(parsed[0].type).toBe('tool/call');
   });
 
+  it('skips a zstd-magic buffer it cannot decode, rather than throwing', () => {
+    // The counterpart to the test above: on a runtime without zstd the magic
+    // number still gets recognised, `zstdDecompressSync` is missing, and the
+    // catch must degrade to "no events" instead of crashing the whole journal.
+    // This runs on every Node version, so the degraded path is never untested.
+    const magic = Buffer.from([0x28, 0xb5, 0x2f, 0xfd, 0x00, 0x00, 0x00, 0x00]);
+    expect(() => parseSessionBuffer(magic)).not.toThrow();
+    expect(parseSessionBuffer(magic)).toEqual([]);
+  });
+
   it('reads an uncompressed journal too, so fixtures need no encoder', () => {
     const events = toolPair('c1', 'read', { file_path: '/a.ts' }, 1000, 1010);
     const parsed = parseSessionBuffer(Buffer.from(journalText(events), 'utf8'));

package/lib/__tests__/check-single-file.test.js

@@ -43,6 +43,32 @@ function runCheck(relPath) {
   return { stdout, status, elapsed: Date.now() - started };
 }
 
+/**
+ * 量一次「同一 CLI 做最少的事」要多久——只解析参数并打印版本，不跑任何 gate。
+ * 用作 AC-653-05 的相对基线：Node 启动 + bin 模块加载 + 依赖解析的固有成本，
+ * 这部分与机器负载同步伸缩，减掉它才能量出 check 自己的开销。
+ *
+ * 取三次的最小值：最小值受负载尖峰影响最小，比平均值稳定得多。
+ */
+function measure(args) {
+  let best = Infinity;
+  for (let i = 0; i < 3; i += 1) {
+    const started = Date.now();
+    try {
+      execFileSync(process.execPath, [CLI, ...args], {
+        cwd: REPO,
+        encoding: 'utf8',
+        timeout: 120000,
+        stdio: 'pipe',
+      });
+    } catch {
+      // --version 不该失败；真失败时这一次不计入，别把错误吞成 0ms。
+    }
+    best = Math.min(best, Date.now() - started);
+  }
+  return best;
+}
+
 describe('check --gates 单文件自检 (#653)', () => {
   it('AC-653-04: 传文件路径时 gate 真的执行，而不是报 spawn 失败', () => {
     const target = 'src/npm-package/lib/doctor-brief.js';
@@ -54,10 +80,35 @@ describe('check --gates 单文件自检 (#653)', () => {
     expect(stdout).toMatch(/principles/i);
   });
 
-  it('AC-653-05: 单文件自检在 2 秒内给出结论', () => {
+  it('AC-653-05: 单文件自检的增量开销远小于一次完整 pre-commit', () => {
+    // #653 的价值主张：提交前自检要快过等一轮完整 pre-commit（几分钟）。
+    // "快路径"如果慢就不叫快路径。
+    //
+    // 但这里不能用绝对墙钟阈值。原实现写 `elapsed < 2000`，实测同一台机器：
+    //   裸跑 `node bin/xp-gate.js check ...` 654–822ms（远快于阈值）
+    //   在 vitest 里跑同一命令           2191–2352ms（偶尔超阈值）
+    // 它测的是「机器此刻有多空」，不是「这个功能够不够快」——并行跑测试时翻红、
+    // 空闲时变绿，红绿与功能无关（#722）。一个随负载漂移的断言，既不能证明快，
+    // 也不能证明慢。
+    //
+    // 改成相对判定：先用 `--version` 量出「同一 CLI、同一 Node 启动、同一份模块
+    // 加载」的固有成本，再看 check 是它的几倍。两者对机器快慢同步伸缩，比值因此
+    // 稳定。实测：
+    //   空闲    check 852ms  / base 172ms = 4.95x
+    //   重负载  check 2563ms / base 445ms = 5.76x   （4 个 CPU 密集进程并行）
+    // 比值只涨 16%，而绝对时间涨 3 倍——所以比值才是与负载无关的那个量。
+    //
+    // 门槛取 12x：它意味着 check 花的时间不超过「启动 CLI 本身」的一打倍——
+    // 一次完整 pre-commit 是分钟级，12x 启动成本仍是亚秒到一秒级，离「慢」很远；
+    // 同时留足余量，不会因为机器一时抖动就翻红。
+    const baseline = measure(['--version']);
     const { elapsed } = runCheck('src/npm-package/lib/doctor-brief.js');
-    // #653's whole value proposition: self-check before committing beats waiting
-    // for a 3-minute pre-commit. A slow "fast path" is not a fast path.
-    expect(elapsed).toBeLessThan(2000);
+    const ratio = elapsed / baseline;
+
+    expect(ratio).toBeLessThan(12);
+    // 翻红时把三个数字一起打出来，能立刻分辨是「基线被拖慢」还是「check 真变慢」。
+    expect(
+      `${elapsed}ms / ${baseline}ms = ${ratio.toFixed(1)}x`,
+    ).toMatch(/^\d+ms \/ \d+ms = [\d.]+x$/);
   });
 });

package/lib/__tests__/detect-deps-dsh-profile.test.js

@@ -104,3 +104,46 @@ describe('PLATFORM_PROFILES covers dsh (#635)', () => {
     expect(getSkillsDirs('claude-code')[0]).toBe(path.join(tmpHome, '.claude', 'skills'));
   });
 });
+
+/**
+ * @test REQ-725
+ * @intent 多平台共存时 detectPlatform() 按优先级短路返回单个平台，install-skill/
+ *         update-skill 与 doctor 都只拿它选中的目录，其余平台（含 detectPlatform()
+ *         从不返回的 dsh）被永久冻结。detectInstalledPlatforms() 是「检测所有已安装
+ *         agent」的原始能力：按 PLATFORM_PROFILES 里目录真实存在的平台返回全集。
+ * @covers AC-725-01, AC-725-06
+ */
+describe('detectInstalledPlatforms (#725 detect-all)', () => {
+  let tmpHome;
+  let originalHome;
+
+  beforeEach(() => {
+    originalHome = process.env.HOME;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'xpgate-detectall-'));
+    process.env.HOME = tmpHome;
+    vi.resetModules();
+    delete require.cache[require.resolve('../detect-deps')];
+    delete require.cache[require.resolve('../shared-paths')];
+  });
+
+  afterEach(() => {
+    process.env.HOME = originalHome;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  it('returns every platform whose directory exists, including dsh', () => {
+    fs.mkdirSync(path.join(tmpHome, '.qoder'), { recursive: true });
+    fs.mkdirSync(path.join(tmpHome, '.config', 'opencode'), { recursive: true });
+    fs.mkdirSync(path.join(tmpHome, '.dsh'), { recursive: true });
+
+    const { detectInstalledPlatforms } = require('../detect-deps');
+    const installed = detectInstalledPlatforms();
+    expect(installed).toEqual(expect.arrayContaining(['opencode', 'qoder', 'dsh']));
+    expect(installed).not.toContain('claude-code');
+  });
+
+  it('returns an empty list when no platform directory exists', () => {
+    const { detectInstalledPlatforms } = require('../detect-deps');
+    expect(detectInstalledPlatforms()).toEqual([]);
+  });
+});