@goodandready/dsh-approval-gate 0.1.18 → 0.1.19

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.19
+
+- Security: Структурированная категоризация рисков операций по 5 стандартизированным бакетам (`READ_ONLY`, `WORKSPACE`, `EGRESS`, `SYSTEM`, `SECRETS`) в `lib/risk.js` с приоритетной оценкой чувствительности путей, команд и сетевых направлений (Refs: #58).
+- Security: Многомерное тегирование рисков (`risk_tags`: `read-only`, `file-mutation`, `network`, `git`, `credentials`, `package-manager`, `system-mutation`, `privilege-escalation`, `destructive`) для детального анализа и обогащения решений безопасности (Refs: #70).
+- Resilience: Трекер задержки семантического классификатора (`ClassifierLatencyTracker` в `lib/latency.js`) со скользящим окном p95/avg и автоматическим переходом на детерминированные правила при превышении SLA (`classifier-sla-fallback` -> `ask`) (Refs: #57).
+- Resilience: Плавный fallback при несовместимости эндпоинта с OpenAI JSON-mode (`isShapeRejectError`), извлечение JSON из markdown/raw-ответов (`extractJsonPayload`) и повторный запрос без `response_format` для Ollama/vLLM (Refs: #59).
+- Security: Строгая Schemastery-схема вердиктов классификатора (`ClassifierVerdictSchema`, `validateClassifierResponse`) с fail-closed защитой от некорректных/неполных ответов модели (`malformed-classifier-response` -> `ask`) (Refs: #66).
+
 ## 0.1.18
 
 - Security: Эвристический предохранитель размера аргументов (`computePayloadSize` / `maxPayloadBytes`, по умолчанию 64 КБ) для предотвращения переполнения контекста LLM-ревьюера и обхода инспекции (`payload-too-large` -> `ask`) (Refs: #71).

package/lib/classifier.js

@@ -4,6 +4,7 @@
 
 import { redactCredentials, redactUrl } from "./redact.js";
 import { CircuitBreaker } from "./breaker.js";
+import Schema from "@deepseek-ai/schemastery";
 
 // Additional regex patterns for sensitive tokens & API keys (#115)
 const OPENAI_KEY_PATTERN = /\bsk-[a-zA-Z0-9_\-]{20,}\b/g;
@@ -244,7 +245,104 @@ export function isLowRiskExecution(execution) {
 }
 
 /**
- * Standalone resilient LLM Classifier client (#127, #129, #118, #115, #117).
+ * Checks whether an error is caused by endpoint rejection of JSON-mode / response_format (#59).
+ * Common in local LLM runtimes like Ollama, vLLM, and older endpoints.
+ *
+ * @param {any} err
+ * @returns {boolean}
+ */
+export function isShapeRejectError(err) {
+  if (!err) return false;
+  const status = err.status || (err.response && err.response.status);
+  if (status === 400 || status === 415 || status === 422) return true;
+  const msg = String(err.message || "").toLowerCase();
+  return (
+    msg.includes("response_format") ||
+    msg.includes("json_object") ||
+    msg.includes("unsupported parameter") ||
+    msg.includes("schema")
+  );
+}
+
+/**
+ * Robust JSON extraction from raw strings, handling markdown code blocks and raw JSON (#59).
+ *
+ * @param {string} content
+ * @returns {any | null}
+ */
+export function extractJsonPayload(content) {
+  if (!content || typeof content !== "string") return null;
+  const trimmed = content.trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // Check markdown code block
+    const mdMatch = /```(?:json)?\s*([\s\S]*?)\s*```/i.exec(trimmed);
+    if (mdMatch && mdMatch[1]) {
+      try {
+        return JSON.parse(mdMatch[1].trim());
+      } catch {
+        // continue
+      }
+    }
+    // Check bracketed JSON
+    const braceMatch = /\{[\s\S]*\}/.exec(trimmed);
+    if (braceMatch) {
+      try {
+        return JSON.parse(braceMatch[0]);
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Strict Schemastery schema for validating structured classifier decisions (#66).
+ */
+export const ClassifierVerdictSchema = Schema.object({
+  verdict: Schema.union(["allow", "deny", "ask"]).required(),
+  reason: Schema.string().default("classifier-evaluated"),
+  riskScore: Schema.number().default(0.5),
+  tags: Schema.array(Schema.string()).default([]),
+});
+
+/**
+ * Validates and normalizes structured classifier response (#66).
+ *
+ * @param {any} parsed
+ * @returns {{ valid: boolean, verdict?: "allow" | "deny" | "ask", reason?: string, riskScore?: number, tags?: string[], error?: string }}
+ */
+export function validateClassifierResponse(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { valid: false, error: "Response is not a valid JSON object" };
+  }
+  const rawVerdict = String(parsed.verdict || "").toLowerCase().trim();
+  if (!["allow", "deny", "ask"].includes(rawVerdict)) {
+    return { valid: false, error: `Invalid verdict '${parsed.verdict}', expected allow|deny|ask` };
+  }
+  const reason = typeof parsed.reason === "string" && parsed.reason.trim()
+    ? parsed.reason.trim()
+    : `classifier-${rawVerdict}`;
+  const riskScore = typeof parsed.riskScore === "number" && !isNaN(parsed.riskScore)
+    ? Math.max(0, Math.min(1, parsed.riskScore))
+    : (rawVerdict === "deny" ? 1.0 : (rawVerdict === "ask" ? 0.6 : 0.1));
+  const tags = Array.isArray(parsed.tags)
+    ? parsed.tags.filter((t) => typeof t === "string" && t.trim()).map((t) => t.trim())
+    : [];
+
+  return {
+    valid: true,
+    verdict: rawVerdict,
+    reason,
+    riskScore,
+    tags,
+  };
+}
+
+/**
+ * Standalone resilient LLM Classifier client (#127, #129, #118, #115, #117, #59, #66).
  */
 export class LlmClassifier {
   /**
@@ -256,6 +354,7 @@ export class LlmClassifier {
    *   timeoutPolicy?: "strict" | "permissive",
    *   maxRetries?: number,
    *   maxContextChars?: number,
+   *   supportsJsonMode?: boolean,
    *   fetch?: typeof globalThis.fetch
    * }} [options]
    */
@@ -267,11 +366,12 @@ export class LlmClassifier {
     this.timeoutPolicy = options.timeoutPolicy === "permissive" ? "permissive" : "strict";
     this.maxRetries = typeof options.maxRetries === "number" ? options.maxRetries : 2;
     this.maxContextChars = typeof options.maxContextChars === "number" ? options.maxContextChars : 1000;
+    this.supportsJsonMode = options.supportsJsonMode !== false;
     this.fetch = options.fetch || globalThis.fetch;
   }
 
   /**
-   * Builds prompt messages with sanitized credentials and bounded context size (#115, #117).
+   * Builds prompt messages with sanitized credentials and bounded context size (#115, #117, #66).
    *
    * @param {any} execution
    * @param {any} [context]
@@ -286,7 +386,7 @@ export class LlmClassifier {
         role: "system",
         content:
           "You are a security approval gate classifier. Analyze the provided tool execution request. " +
-          "Respond strictly in valid JSON format: {\"verdict\": \"allow\"|\"deny\"|\"ask\", \"reason\": \"<short explanation>\"}.",
+          "Respond strictly in valid JSON format: {\"verdict\": \"allow\"|\"deny\"|\"ask\", \"reason\": \"<short explanation>\", \"riskScore\": <0.0-1.0>, \"tags\": [\"<tag>\"]}.",
       },
       {
         role: "user",
@@ -296,11 +396,11 @@ export class LlmClassifier {
   }
 
   /**
-   * Classifies an execution request using the configured LLM endpoint (#118, #127, #129, #115, #117).
+   * Classifies an execution request using the configured LLM endpoint (#118, #127, #129, #115, #117, #59, #66).
    *
    * @param {any} execution
    * @param {any} [context]
-   * @returns {Promise<{ verdict: "allow" | "deny" | "ask", reason: string, timeout?: boolean, error?: any }>}
+   * @returns {Promise<{ verdict: "allow" | "deny" | "ask", reason: string, riskScore?: number, tags?: string[], timeout?: boolean, error?: any }>}
    */
   async classify(execution, context = {}) {
     if (!this.endpoint || typeof this.fetch !== "function") {
@@ -308,15 +408,19 @@ export class LlmClassifier {
     }
 
     const messages = this.formatMessages(execution, context);
-    const body = JSON.stringify({
-      model: this.model,
-      messages,
-      temperature: 0.1,
-      response_format: { type: "json_object" },
-    });
 
-    try {
-      const response = await withLlmRetry(
+    const callApi = async (useJsonMode) => {
+      const payload = {
+        model: this.model,
+        messages,
+        temperature: 0.1,
+      };
+      if (useJsonMode) {
+        payload.response_format = { type: "json_object" };
+      }
+      const body = JSON.stringify(payload);
+
+      return withLlmRetry(
         async () => {
           const controller = new AbortController();
           const timer = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -354,23 +458,49 @@ export class LlmClassifier {
           retryOn: shouldRetryLlmError,
         }
       );
+    };
+
+    try {
+      let response;
+      if (this.supportsJsonMode) {
+        try {
+          response = await callApi(true);
+        } catch (err) {
+          if (isShapeRejectError(err)) {
+            this.supportsJsonMode = false;
+            response = await callApi(false);
+          } else {
+            throw err;
+          }
+        }
+      } else {
+        response = await callApi(false);
+      }
 
       const content = response?.choices?.[0]?.message?.content;
       if (!content) {
         return { verdict: "ask", reason: "classifier-empty-response" };
       }
 
-      let parsed;
-      try {
-        parsed = JSON.parse(content);
-      } catch {
+      const parsed = extractJsonPayload(content);
+      if (!parsed) {
         return { verdict: "ask", reason: "classifier-invalid-json" };
       }
 
-      const verdict = ["allow", "deny", "ask"].includes(parsed.verdict) ? parsed.verdict : "ask";
+      const validated = validateClassifierResponse(parsed);
+      if (!validated.valid) {
+        return {
+          verdict: "ask",
+          reason: "malformed-classifier-response",
+          detail: validated.error,
+        };
+      }
+
       return {
-        verdict,
-        reason: parsed.reason || `classifier-${verdict}`,
+        verdict: validated.verdict,
+        reason: validated.reason,
+        riskScore: validated.riskScore,
+        tags: validated.tags,
       };
     } catch (err) {
       const isTimeout = CircuitBreaker.isFaultOrTimeout(err) || Boolean(err?.isTimeout);

package/lib/engine.js

@@ -20,6 +20,8 @@ import { BlockCounters } from "./counters.js";
 import { ContractGuard } from "./contract-guard.js";
 import { OverengineeringGuard } from "./overengineering.js";
 import { extractFilePath, DEFAULT_FILE_WRITE_TOOLS } from "./dispatcher.js";
+import { categorizeRiskBucket, extractRiskTags } from "./risk.js";
+import { ClassifierLatencyTracker } from "./latency.js";
 
 /**
  * Determine whether an operation belongs to a critical risk category requiring lockedAsk (#52).
@@ -123,6 +125,7 @@ export class SecurityEngine {
       : (options.maxFilesPerSession !== undefined || options.maxCreatedFilesPerSession !== undefined
           ? new OverengineeringGuard(options)
           : null);
+    this.latencyTracker = options.latencyTracker || new ClassifierLatencyTracker(options);
   }
 
   /**
@@ -152,9 +155,9 @@ export class SecurityEngine {
         if (this.auditLogger) this.auditLogger.appendAuditLine({ sessionId, execution, decision: exhDecision, dryRun: this.dryRun });
 
         if (this.dryRun) {
-          return { verdict: "allow", stage: "P0", dryRun: true, originalVerdict: "deny", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit };
+          return this._enrichDecision({ verdict: "allow", stage: "P0", dryRun: true, originalVerdict: "deny", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit }, execution, context);
         }
-        return exhDecision;
+        return this._enrichDecision(exhDecision, execution, context);
       }
 
       // Check Verdict Cache (#63, #119)
@@ -163,7 +166,7 @@ export class SecurityEngine {
         const cached = this.cache.get(cacheKey);
         if (cached) {
           if (this.dryRun && (cached.verdict === "deny" || cached.verdict === "ask")) {
-            return {
+            return this._enrichDecision({
               verdict: "allow",
               stage: cached.stage,
               dryRun: true,
@@ -172,14 +175,15 @@ export class SecurityEngine {
               detail: cached.detail,
               hit: cached.hit,
               cached: true,
-            };
+            }, execution, context);
           }
           if (this.counters) this.counters.record(cached, execution);
-          return cached;
+          return this._enrichDecision(cached, execution, context);
         }
       }
 
       let decision = this._evaluateWaterfall(execution, context, sessionId, toolName, command);
+      this._enrichDecision(decision, execution, context);
 
       // Post-decision hooks: ledger, retryGuard, cache
       if (decision.verdict === "deny") {
@@ -212,6 +216,7 @@ export class SecurityEngine {
             hit: auditDenyHit,
             auditFailed: true,
           };
+          this._enrichDecision(decision, execution, context);
         }
       }
 
@@ -222,7 +227,7 @@ export class SecurityEngine {
 
       // Shadow Mode (#128)
       if (this.dryRun && (decision.verdict === "deny" || decision.verdict === "ask")) {
-        return {
+        return this._enrichDecision({
           verdict: "allow",
           stage: decision.stage,
           dryRun: true,
@@ -231,7 +236,7 @@ export class SecurityEngine {
           detail: decision.detail,
           hit: decision.hit,
           lockedAsk: decision.lockedAsk,
-        };
+        }, execution, context);
       }
 
       return decision;
@@ -244,12 +249,12 @@ export class SecurityEngine {
         hit: { ask: true, reason: "inspect-error", detail: String(err && err.message || err) },
       };
       if (this.counters) this.counters.record(errDecision, execution);
-      return errDecision;
+      return this._enrichDecision(errDecision, execution, context);
     }
   }
 
   /**
-   * Asynchronous evaluation supporting async classifiers (#129, #118).
+   * Asynchronous evaluation supporting async classifiers and latency SLA tracking (#129, #118, #57).
    *
    * @param {{ name: string, arguments?: any }} execution
    * @param {{ sessionId?: string, knobs?: any, cwd?: string }} [context]
@@ -259,15 +264,31 @@ export class SecurityEngine {
     if (this.classifier) {
       let resolvedVerdict = null;
       let caughtError = null;
-      try {
-        if (typeof this.classifier.classify === "function") {
-          resolvedVerdict = await this.classifier.classify(execution, context);
-        } else if (typeof this.classifier === "function") {
-          const res = this.classifier(execution, context);
-          resolvedVerdict = res && typeof res.then === "function" ? await res : res;
+
+      if (this.latencyTracker && this.latencyTracker.isDegraded()) {
+        resolvedVerdict = {
+          verdict: "ask",
+          reason: "classifier-sla-fallback",
+          detail: `Classifier latency p95 (${this.latencyTracker.getP95()}ms) exceeded SLA (${this.latencyTracker.slaMs}ms) (#57)`,
+        };
+      } else {
+        const start = Date.now();
+        try {
+          if (typeof this.classifier.classify === "function") {
+            resolvedVerdict = await this.classifier.classify(execution, context);
+          } else if (typeof this.classifier === "function") {
+            const res = this.classifier(execution, context);
+            resolvedVerdict = res && typeof res.then === "function" ? await res : res;
+          }
+          if (this.latencyTracker) {
+            this.latencyTracker.recordSample(Date.now() - start);
+          }
+        } catch (err) {
+          caughtError = err;
+          if (this.latencyTracker) {
+            this.latencyTracker.recordSample(Date.now() - start);
+          }
         }
-      } catch (err) {
-        caughtError = err;
       }
 
       const originalClassifier = this.classifier;
@@ -509,4 +530,28 @@ export class SecurityEngine {
     if (this.cache) this.cache.clearSession(sessionId);
     return this.breaker.resume(sessionId, reason);
   }
+
+  /**
+   * Enriches decision with risk bucket (#58) and operational risk tags (#70).
+   * @private
+   */
+  _enrichDecision(decision, execution, context) {
+    if (!decision) return decision;
+    if (!decision.riskBucket) {
+      decision.riskBucket = categorizeRiskBucket(execution, context);
+    }
+    if (!decision.riskTags || !Array.isArray(decision.riskTags)) {
+      decision.riskTags = extractRiskTags(execution, context);
+    }
+    return decision;
+  }
+
+  getLatencyMetrics() {
+    return this.latencyTracker ? this.latencyTracker.getMetrics() : null;
+  }
+
+  resetLatencyTracker() {
+    if (this.latencyTracker) this.latencyTracker.reset();
+  }
 }
+

package/lib/index.js

@@ -3,6 +3,7 @@ import { BandsEngine } from "./bands.js";
 import { AuditLogger } from "./audit-log.js";
 import { DeclarativeRulesEngine } from "./rules-loader.js";
 import { LlmClassifier } from "./classifier.js";
+import { ClassifierLatencyTracker } from "./latency.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -236,6 +237,8 @@ export const Config = Schema.object({
   isolateTempRoots: Schema.boolean().default(true).volatile(),
   /** Maximum allowed created files per session to prevent overengineering (#89). */
   maxFilesPerSession: Schema.number().default(10).volatile(),
+  /** Maximum latency in ms before classifier degrades to deterministic rules (#57). */
+  classifierSlaMs: Schema.number().default(2000).volatile(),
   /** Task contract boundary rules (#87). */
   taskContract: Schema.any().volatile(),
   /** Security engine instance (internal/testing). */
@@ -301,6 +304,9 @@ export function apply(ctx, config) {
     bands: new BandsEngine({ toolRegistry: ctx && ctx.tools }),
     classifier,
     timeoutPolicy: cfg.classifierTimeoutPolicy || "strict",
+    latencyTracker: new ClassifierLatencyTracker({
+      slaMs: cfg.classifierSlaMs !== undefined ? cfg.classifierSlaMs : 2000,
+    }),
     defaultVerdict: cfg.defaultVerdict || "allow",
     dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
     auditFailClosed: Boolean(cfg.auditFailClosed),
@@ -326,6 +332,8 @@ export function apply(ctx, config) {
     getCounters: () => engine.getCounters(),
     resetCounters: () => engine.resetCounters(),
     getLedgerSummary: (sessionId) => engine.getLedgerSummary(sessionId),
+    getLatencyMetrics: () => (engine.getLatencyMetrics ? engine.getLatencyMetrics() : null),
+    resetLatencyTracker: () => (engine.resetLatencyTracker ? engine.resetLatencyTracker() : undefined),
     getSnapshot: () => ({
       active: true,
       dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
@@ -336,6 +344,7 @@ export function apply(ctx, config) {
       rulesCount: engine.declarativeRules ? engine.declarativeRules.count() : 0,
       cacheStats: engine.cache ? engine.cache.stats() : null,
       breakerState: engine.breaker ? engine.breaker.getState() : null,
+      latencyMetrics: engine.getLatencyMetrics ? engine.getLatencyMetrics() : null,
     }),
   };
   if (ctx && typeof ctx === "object") {
@@ -536,27 +545,11 @@ export {
   DEFAULT_RETAIN_LINES,
   auditRotateContent,
 } from "./audit-log.js";
-export {
-  BlockCounters,
-  categorizeReason,
-} from "./counters.js";
-export {
-  isCriticalOperation,
-} from "./engine.js";
-export {
-  parseYaml,
-  parseScalar,
-  stripComment,
-} from "./yaml-parser.js";
-export {
-  matchConditionValue,
-  evaluateWhen,
-} from "./when-matcher.js";
-export {
-  HotwordsMatcher,
-  DEFAULT_HOTWORDS,
-  extractWords,
-} from "./hotwords.js";
+export { BlockCounters, categorizeReason } from "./counters.js";
+export { isCriticalOperation } from "./engine.js";
+export { parseYaml, parseScalar, stripComment } from "./yaml-parser.js";
+export { matchConditionValue, evaluateWhen } from "./when-matcher.js";
+export { HotwordsMatcher, DEFAULT_HOTWORDS, extractWords } from "./hotwords.js";
 export {
   DeclarativeRulesEngine,
   BUILTIN_RULES_FILE,
@@ -569,9 +562,16 @@ export {
   sanitizeClassifierInput,
   truncateClassifierContext,
   isLowRiskExecution,
+  isShapeRejectError,
+  extractJsonPayload,
+  ClassifierVerdictSchema,
+  validateClassifierResponse,
   LlmClassifier,
 } from "./classifier.js";
 export { ContractGuard } from "./contract-guard.js";
 export { OverengineeringGuard, DEFAULT_MAX_FILES_PER_SESSION } from "./overengineering.js";
 export { resolveTempRoot, isGlobalTempPath, checkTempIsolation } from "./paths.js";
 export { computePayloadSize, scanPromptInjection } from "./inspect.js";
+export { RISK_BUCKETS, RISK_TAGS, categorizeRiskBucket, extractRiskTags } from "./risk.js";
+export { ClassifierLatencyTracker, DEFAULT_CLASSIFIER_SLA_MS } from "./latency.js";
+

package/lib/latency.js

@@ -0,0 +1,137 @@
+// lib/latency.js
+// Classifier latency tracking and SLA-based fallback on deterministic rules (#57).
+
+export const DEFAULT_CLASSIFIER_SLA_MS = 2000;
+export const DEFAULT_LATENCY_WINDOW_SIZE = 50;
+export const DEFAULT_DEGRADE_THRESHOLD_COUNT = 3;
+export const DEFAULT_RECOVERY_THRESHOLD_COUNT = 2;
+
+/**
+ * Tracks external semantic classifier latency with sliding window statistics and SLA health (#57).
+ */
+export class ClassifierLatencyTracker {
+  /**
+   * @param {{
+   *   slaMs?: number,
+   *   windowSize?: number,
+   *   degradeThresholdCount?: number,
+   *   recoveryThresholdCount?: number
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.slaMs = typeof options.slaMs === "number" && options.slaMs > 0
+      ? options.slaMs
+      : DEFAULT_CLASSIFIER_SLA_MS;
+    this.windowSize = typeof options.windowSize === "number" && options.windowSize > 0
+      ? options.windowSize
+      : DEFAULT_LATENCY_WINDOW_SIZE;
+    this.degradeThresholdCount = typeof options.degradeThresholdCount === "number" && options.degradeThresholdCount > 0
+      ? options.degradeThresholdCount
+      : DEFAULT_DEGRADE_THRESHOLD_COUNT;
+    this.recoveryThresholdCount = typeof options.recoveryThresholdCount === "number" && options.recoveryThresholdCount > 0
+      ? options.recoveryThresholdCount
+      : DEFAULT_RECOVERY_THRESHOLD_COUNT;
+
+    this._samples = [];
+    this._consecutiveSlow = 0;
+    this._consecutiveFast = 0;
+    this._degraded = false;
+  }
+
+  /**
+   * Records a latency observation in milliseconds.
+   *
+   * @param {number} durationMs
+   * @returns {{ degraded: boolean, p95Ms: number, avgMs: number }}
+   */
+  recordSample(durationMs) {
+    const val = Math.max(0, Number(durationMs) || 0);
+    this._samples.push(val);
+    if (this._samples.length > this.windowSize) {
+      this._samples.shift();
+    }
+
+    if (val > this.slaMs) {
+      this._consecutiveSlow += 1;
+      this._consecutiveFast = 0;
+      if (this._consecutiveSlow >= this.degradeThresholdCount) {
+        this._degraded = true;
+      }
+    } else {
+      this._consecutiveFast += 1;
+      this._consecutiveSlow = 0;
+      if (this._consecutiveFast >= this.recoveryThresholdCount) {
+        this._degraded = false;
+      }
+    }
+
+    if (!this._degraded && this._samples.length >= 5 && this.getP95() > this.slaMs && this._consecutiveSlow > 0) {
+      this._degraded = true;
+    }
+
+    return {
+      degraded: this.isDegraded(),
+      p95Ms: this.getP95(),
+      avgMs: this.getAvg(),
+    };
+  }
+
+  /**
+   * Calculates 95th percentile latency from the current sliding window.
+   * @returns {number}
+   */
+  getP95() {
+    if (this._samples.length === 0) return 0;
+    const sorted = this._samples.slice().sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * 0.95) - 1));
+    return Math.round(sorted[idx] * 10) / 10;
+  }
+
+  /**
+   * Calculates mean latency from current window.
+   * @returns {number}
+   */
+  getAvg() {
+    if (this._samples.length === 0) return 0;
+    const sum = this._samples.reduce((acc, v) => acc + v, 0);
+    return Math.round((sum / this._samples.length) * 10) / 10;
+  }
+
+  /**
+   * Checks whether the classifier is currently marked degraded due to SLA violations.
+   * @returns {boolean}
+   */
+  isDegraded() {
+    return this._degraded;
+  }
+
+  /**
+   * Resets all tracked samples and returns to healthy state.
+   */
+  reset() {
+    this._samples = [];
+    this._consecutiveSlow = 0;
+    this._consecutiveFast = 0;
+    this._degraded = false;
+  }
+
+  /**
+   * Returns a snapshot of current latency metrics.
+   * @returns {{ count: number, avgMs: number, p95Ms: number, minMs: number, maxMs: number, degraded: boolean, slaMs: number, consecutiveSlow: number }}
+   */
+  getMetrics() {
+    const count = this._samples.length;
+    const minMs = count > 0 ? Math.min(...this._samples) : 0;
+    const maxMs = count > 0 ? Math.max(...this._samples) : 0;
+    return {
+      count,
+      avgMs: this.getAvg(),
+      p95Ms: this.getP95(),
+      minMs,
+      maxMs,
+      degraded: this.isDegraded(),
+      slaMs: this.slaMs,
+      consecutiveSlow: this._consecutiveSlow,
+    };
+  }
+}

package/lib/messages.js

@@ -67,6 +67,8 @@ export const MESSAGES = Object.freeze({
     ruleClassifierTimeoutPermissive: "Semantic classifier timed out; allowed by low-risk fallback policy",
     askClassifierTimeout: "Semantic classifier request timed out; human confirmation required",
     askClassifierError: "Semantic classifier error; human confirmation required",
+    askClassifierSlaFallback: "Semantic classifier exceeded SLA latency threshold; manual review required",
+    askMalformedClassifierResponse: "Semantic classifier returned malformed or unverified decision; manual review required",
     askPayloadTooLarge: "Command arguments exceed maximum payload size limit; review before allowing",
     ruleReviewerInjectionAttempt: "Prompt instruction injection detected in tool arguments",
     askContractViolation: "Operation falls outside task contract boundaries; review before allowing",
@@ -91,6 +93,8 @@ export const MESSAGES = Object.freeze({
     hintFailClosedAudit: "Ensure the audit log directory is writable and disk space is available",
     hintLockedAskUnattended: "Switch to an interactive session or request explicit human confirmation",
     hintClassifierTimeout: "Check external LLM connectivity or review timeout policy settings",
+    hintClassifierSlaFallback: "Check external LLM classifier load or increase classifierSlaMs",
+    hintMalformedClassifierResponse: "Verify model JSON output format or check response schema compatibility",
     hintPayloadTooLarge: "Reduce input payload size or chunk data into smaller batches",
     hintReviewerInjectionAttempt: "Remove adversarial prompt override directives from input",
     hintContractViolation: "Confine operations to permitted task tools and project scope",
@@ -162,6 +166,8 @@ export const MESSAGES = Object.freeze({
     ruleClassifierTimeoutPermissive: "语义分类器超时；根据低风险容错策略放行",
     askClassifierTimeout: "语义分类器请求超时；需要人工审查",
     askClassifierError: "语义分类器发生异常；需要人工审查",
+    askClassifierSlaFallback: "语义分类器延迟超出 SLA 阈值；需要人工审查",
+    askMalformedClassifierResponse: "语义分类器返回非预期或未通过校验的判定；需要人工审查",
     askPayloadTooLarge: "命令参数超过最大负载大小限制；请在允许前进行审查",
     ruleReviewerInjectionAttempt: "在工具参数中检测到提示词指令注入尝试",
     askContractViolation: "操作超出任务契约范围；请在允许前进行审查",
@@ -186,6 +192,8 @@ export const MESSAGES = Object.freeze({
     hintFailClosedAudit: "请确保审计日志目录可写且磁盘空间充足",
     hintLockedAskUnattended: "请切换到交互式会话或请求人工显式确认",
     hintClassifierTimeout: "请检查外部 LLM 服务连通性或调整分类器超时容错策略",
+    hintClassifierSlaFallback: "请检查外部 LLM 分类器负载或调高 classifierSlaMs 阈值",
+    hintMalformedClassifierResponse: "请检查模型 JSON 输出格式或验证返回模式兼容性",
     hintPayloadTooLarge: "减小输入参数大小或分批传输数据",
     hintReviewerInjectionAttempt: "从输入中移除对抗性指令覆盖指令",
     hintContractViolation: "将操作限制在允许的任务工具和项目范围内",
@@ -256,6 +264,8 @@ const RULE_KEYS = Object.freeze({
   "classifier-timeout-strict": "ruleClassifierTimeoutStrict",
   "classifier-timeout-fallback-strict": "ruleClassifierTimeoutStrict",
   "classifier-timeout-fallback-permissive": "ruleClassifierTimeoutPermissive",
+  "classifier-sla-fallback": "askClassifierSlaFallback",
+  "malformed-classifier-response": "askMalformedClassifierResponse",
   "reviewer-injection-attempt": "ruleReviewerInjectionAttempt",
   "contract-violation": "ruleContractViolation",
   "unisolated-temp-path": "ruleUnisolatedTempPath",
@@ -280,6 +290,8 @@ const HINT_KEYS = Object.freeze({
   "locked-ask-unattended-denied": "hintLockedAskUnattended",
   "classifier-timeout-strict": "hintClassifierTimeout",
   "classifier-timeout-fallback-strict": "hintClassifierTimeout",
+  "classifier-sla-fallback": "hintClassifierSlaFallback",
+  "malformed-classifier-response": "hintMalformedClassifierResponse",
   "payload-too-large": "hintPayloadTooLarge",
   "reviewer-injection-attempt": "hintReviewerInjectionAttempt",
   "contract-violation": "hintContractViolation",
@@ -303,6 +315,8 @@ const ASK_KEYS = Object.freeze({
   "classifier-timeout-strict": "askClassifierTimeout",
   "classifier-timeout-fallback-strict": "askClassifierTimeout",
   "classifier-error": "askClassifierError",
+  "classifier-sla-fallback": "askClassifierSlaFallback",
+  "malformed-classifier-response": "askMalformedClassifierResponse",
   "payload-too-large": "askPayloadTooLarge",
   "contract-violation": "askContractViolation",
   "unisolated-temp-path": "askUnisolatedTempPath",

package/lib/risk.js

@@ -0,0 +1,224 @@
+// lib/risk.js
+// Structured risk bucket classification and operational risk tagging.
+// Resolves: #58 (Risk Buckets) and #70 (Risk Tags)
+
+import {
+  DEFAULT_BASH_TOOL,
+  DEFAULT_FILE_WRITE_TOOLS,
+  DEFAULT_READ_ONLY_TOOLS,
+  DEFAULT_NETWORK_TOOLS,
+  extractFilePath,
+} from "./dispatcher.js";
+import { isProtectedConfigPath } from "./paths.js";
+import { isLoopbackHost, isLoopbackUrl } from "./loopback.js";
+
+export const RISK_BUCKETS = Object.freeze({
+  READ_ONLY: "READ_ONLY",
+  WORKSPACE: "WORKSPACE",
+  EGRESS: "EGRESS",
+  SYSTEM: "SYSTEM",
+  SECRETS: "SECRETS",
+});
+
+export const RISK_TAGS = Object.freeze({
+  READ_ONLY: "read-only",
+  FILE_MUTATION: "file-mutation",
+  NETWORK: "network",
+  GIT: "git",
+  CREDENTIALS: "credentials",
+  PACKAGE_MANAGER: "package-manager",
+  SYSTEM_MUTATION: "system-mutation",
+  PRIVILEGE_ESCALATION: "privilege-escalation",
+  DESTRUCTIVE: "destructive",
+});
+
+const READ_ONLY_CMDS = new Set([
+  "ls", "cat", "head", "tail", "grep", "find", "pwd", "which", "whereis",
+  "file", "stat", "echo", "printf", "diff", "wc", "sort", "uniq", "date",
+  "uname", "uptime", "hostname", "whoami", "id", "node -v", "npm -v", "git status",
+  "git log", "git diff", "git show", "git rev-parse", "git branch",
+]);
+
+const SYSTEM_PKG_MANAGERS = new Set([
+  "apt", "apt-get", "dpkg", "yum", "dnf", "pacman", "zypper", "brew", "snap", "flatpak", "apk",
+]);
+
+const DEV_PKG_MANAGERS = new Set(["npm", "pnpm", "yarn", "pip", "pip3", "cargo", "gem", "go", "composer"]);
+
+const SYSTEM_SERVICES = new Set(["systemctl", "service", "init", "reboot", "shutdown", "poweroff", "journalctl"]);
+
+const NETWORK_CMDS = new Set(["curl", "wget", "fetch", "nc", "netcat", "ncat", "ssh", "scp", "rsync", "ping", "telnet"]);
+
+const SECRET_PATTERNS = [
+  /(\.env|\.env\.[a-z0-9_.-]+)$/i,
+  /id_rsa|id_ed25519|authorized_keys|known_hosts/i,
+  /\/etc\/(shadow|sudoers|master\.passwd)/i,
+  /\.git-credentials|\.netrc|\.dockercfg|\.npmrc/i,
+];
+
+/**
+ * Categorizes an execution into one of the 5 standardized risk buckets (#58).
+ * Priority waterfall: SECRETS -> SYSTEM -> EGRESS -> WORKSPACE -> READ_ONLY
+ *
+ * @param {any} execution
+ * @param {any} [context]
+ * @returns {string} Bucket name from RISK_BUCKETS
+ */
+export function categorizeRiskBucket(execution, context = {}) {
+  const toolName = execution && execution.name;
+  const args = execution && execution.arguments;
+  const command = (args && typeof args === "object" && typeof args.command === "string")
+    ? args.command.trim()
+    : (typeof args === "string" ? args.trim() : "");
+  const targetPath = extractFilePath(args);
+
+  // 1. SECRETS check
+  if (targetPath) {
+    if (isProtectedConfigPath(targetPath) || SECRET_PATTERNS.some((p) => p.test(targetPath))) {
+      return RISK_BUCKETS.SECRETS;
+    }
+  }
+  if (command) {
+    if (/\b(?:printenv|export|env)\b(?!\s*=[a-zA-Z0-9_.-]+)/i.test(command) && !/\b(?:npm|node|git|test|cargo)\b/i.test(command)) {
+      return RISK_BUCKETS.SECRETS;
+    }
+    if (SECRET_PATTERNS.some((p) => p.test(command))) {
+      return RISK_BUCKETS.SECRETS;
+    }
+  }
+
+  // 2. SYSTEM check
+  if (command) {
+    const firstWord = command.split(/\s+/)[0].replace(/^sudo\s+/, "");
+    if (/^(sudo|su|doas)\b/i.test(command)) return RISK_BUCKETS.SYSTEM;
+    if (SYSTEM_PKG_MANAGERS.has(firstWord) || SYSTEM_SERVICES.has(firstWord)) return RISK_BUCKETS.SYSTEM;
+    if (/\b(chmod|chown)\s+(-[a-zA-Z]*\s+)?[0-7]{3,4}\b/i.test(command)) return RISK_BUCKETS.SYSTEM;
+    if (/\b(mkfs|fdisk|parted|mount|umount)\b/i.test(command)) return RISK_BUCKETS.SYSTEM;
+    if (/\/(etc|usr|var|boot|sys|proc)\//i.test(command) && /[><]/.test(command)) return RISK_BUCKETS.SYSTEM;
+  }
+  if (targetPath && /(\/etc\/|\/boot\/|\/sys\/|\/proc\/)/i.test(targetPath)) {
+    return RISK_BUCKETS.SYSTEM;
+  }
+
+  // 3. EGRESS check
+  const netTools = new Set(DEFAULT_NETWORK_TOOLS);
+  if (netTools.has(toolName)) {
+    const url = (args && (args.url || args.Url || args.uri)) || "";
+    if (url && (isLoopbackHost(url) || isLoopbackUrl(url))) {
+      return RISK_BUCKETS.WORKSPACE;
+    }
+    return RISK_BUCKETS.EGRESS;
+  }
+  if (command) {
+    if (/git\s+push\b/i.test(command)) return RISK_BUCKETS.EGRESS;
+    const firstWord = command.split(/\s+/)[0];
+    if (NETWORK_CMDS.has(firstWord)) {
+      if (/\b(localhost|127\.0\.0\.1|::1|0\.0\.0\.0)\b/i.test(command)) {
+        return RISK_BUCKETS.WORKSPACE;
+      }
+      return RISK_BUCKETS.EGRESS;
+    }
+  }
+
+  // 4. READ_ONLY check
+  const readTools = new Set(DEFAULT_READ_ONLY_TOOLS);
+  if (readTools.has(toolName)) {
+    return RISK_BUCKETS.READ_ONLY;
+  }
+  if (command) {
+    const normalizedCmd = command.split(/\s+/).slice(0, 2).join(" ");
+    const singleCmd = command.split(/\s+/)[0];
+    if (READ_ONLY_CMDS.has(normalizedCmd) || READ_ONLY_CMDS.has(singleCmd)) {
+      if (!/[><|&;]/.test(command)) {
+        return RISK_BUCKETS.READ_ONLY;
+      }
+    }
+  }
+
+  // 5. WORKSPACE (default for dev tasks)
+  return RISK_BUCKETS.WORKSPACE;
+}
+
+/**
+ * Extracts multidimensional risk tags for an execution (#70).
+ *
+ * @param {any} execution
+ * @param {any} [context]
+ * @returns {string[]} Sorted array of unique tag strings
+ */
+export function extractRiskTags(execution, context = {}) {
+  const tags = new Set();
+  const toolName = String((execution && execution.name) || "").trim();
+  const args = execution && execution.arguments;
+  const command = (args && typeof args === "object" && typeof args.command === "string")
+    ? args.command.trim()
+    : (typeof args === "string" ? args.trim() : "");
+  const targetPath = extractFilePath(args);
+
+  // File mutation
+  const writeTools = new Set(DEFAULT_FILE_WRITE_TOOLS);
+  if (
+    writeTools.has(toolName) ||
+    toolName === "write_file" ||
+    toolName === "replace_file_content" ||
+    /\b(write|edit)\b/i.test(toolName) ||
+    /[><]/.test(command) ||
+    /\b(rm|mv|cp|touch|mkdir|rmdir)\b/i.test(command)
+  ) {
+    tags.add(RISK_TAGS.FILE_MUTATION);
+  }
+
+  // Network
+  const netTools = new Set(DEFAULT_NETWORK_TOOLS);
+  if (netTools.has(toolName) || /git\s+push\b/i.test(command) || /\b(curl|wget|fetch|nc|ssh|ping)\b/i.test(command)) {
+    tags.add(RISK_TAGS.NETWORK);
+  }
+
+  // Git
+  if (/^git\b/i.test(command) || toolName.includes("git")) {
+    tags.add(RISK_TAGS.GIT);
+  }
+
+  // Credentials / Secrets
+  if (
+    (targetPath && (isProtectedConfigPath(targetPath) || SECRET_PATTERNS.some((p) => p.test(targetPath)))) ||
+    /\b(printenv|export|env)\b(?!\s*=[a-zA-Z0-9_.-]+)/i.test(command) ||
+    SECRET_PATTERNS.some((p) => p.test(command)) ||
+    /\b(Bearer|token|secret|password|api[_-]?key)\b/i.test(command)
+  ) {
+    tags.add(RISK_TAGS.CREDENTIALS);
+  }
+
+  // Package manager
+  if (command) {
+    const firstWord = command.split(/\s+/)[0].replace(/^sudo\s+/, "");
+    if (SYSTEM_PKG_MANAGERS.has(firstWord) || DEV_PKG_MANAGERS.has(firstWord)) {
+      tags.add(RISK_TAGS.PACKAGE_MANAGER);
+    }
+  }
+
+  // Privilege escalation / System mutation
+  if (command) {
+    if (/^(sudo|su|doas)\b/i.test(command) || /\bchmod\s+(-[a-zA-Z]*\s+)?777\b/i.test(command)) {
+      tags.add(RISK_TAGS.PRIVILEGE_ESCALATION);
+    }
+    const firstWord = command.split(/\s+/)[0].replace(/^sudo\s+/, "");
+    if (SYSTEM_PKG_MANAGERS.has(firstWord) || SYSTEM_SERVICES.has(firstWord) || /\b(systemctl|service|reboot|shutdown)\b/i.test(command)) {
+      tags.add(RISK_TAGS.SYSTEM_MUTATION);
+    }
+    if (/\b(rm\s+-[a-zA-Z]*[rf]|mkfs|shred|wipefs|git\s+clean\s+-[a-zA-Z]*f|git\s+reset\s+--hard)\b/i.test(command)) {
+      tags.add(RISK_TAGS.DESTRUCTIVE);
+    }
+  }
+
+  // Read only
+  const readTools = new Set(DEFAULT_READ_ONLY_TOOLS);
+  if (readTools.has(toolName) || (command && !tags.has(RISK_TAGS.FILE_MUTATION) && !tags.has(RISK_TAGS.DESTRUCTIVE) && !/[><|&;]/.test(command))) {
+    const singleCmd = command ? command.split(/\s+/)[0] : "";
+    if (READ_ONLY_CMDS.has(singleCmd) || readTools.has(toolName)) {
+      tags.add(RISK_TAGS.READ_ONLY);
+    }
+  }
+
+  return Array.from(tags).sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Host-only command safety gate for DeepSeek Harness: blocks recognized dangerous operations and requests DSH approval when a command cannot be inspected.",
   "type": "module",
   "main": "lib/index.js",