dsh-autotier 0.1.0

package/src/config.ts

@@ -0,0 +1,358 @@
+/**
+ * The explicit-resolve judge for dsh-autotier: it re-checks every default,
+ * bound and cross-field requirement field by field, so programmatic
+ * construction that bypasses Schemastery normalization still fails loud. The
+ * schema itself lives in `schema.ts`.
+ *
+ * @module dsh-autotier/config
+ */
+
+import {
+  COST_MODES,
+  EFFORT_IDS,
+  ROUTING_MODES,
+  SCENARIOS,
+  type CostMode,
+  type EffortId,
+  type RoutingMode,
+} from './types.ts'
+import { DEFAULT_CHEAP, DEFAULT_STRONG, DEFAULT_VISION } from './schema.ts'
+import type {
+  Config,
+  EscalationConfig,
+  GuardConfig,
+  IntentConfig,
+  JudgeConfig,
+  ScenarioToggles,
+  TierConfig,
+  VisionConfig,
+} from './schema.ts'
+
+export { Config } from './schema.ts'
+export type {
+  EscalationConfig,
+  FallbackEntry,
+  GuardConfig,
+  IntentConfig,
+  IntentRule,
+  JudgeConfig,
+  ScenarioToggles,
+  TierConfig,
+  VisionConfig,
+} from './schema.ts'
+
+/** One resolved fallback landing. */
+export interface ResolvedFallbackEntry {
+  provider: string
+  model: string
+}
+
+/** One resolved tier landing. Runtime-frozen by {@link resolveConfig}. */
+export interface ResolvedTierConfig {
+  provider: string
+  model: string
+  effort: EffortId
+  followSession: boolean
+  fallback: ResolvedFallbackEntry[]
+}
+
+/** One fully-resolved declarative rule. */
+export interface ResolvedRule {
+  id: string
+  when: { patterns: string[]; tools: string[]; cwd: string }
+  tier: 'cheap' | 'strong'
+  priority: number
+}
+
+/** Fully-resolved configuration: every field present, runtime-frozen. */
+export interface ResolvedConfig {
+  tiers: {
+    strong: ResolvedTierConfig
+    cheap: ResolvedTierConfig
+    vision: Required<VisionConfig>
+  }
+  intent: {
+    ruleThreshold: number
+    attemptBand: { enabled: boolean; tauLow: number }
+    hysteresis: { toStrong: number; toCheap: number }
+    rules: ResolvedRule[]
+    judge: Required<JudgeConfig>
+    scenarios: Required<ScenarioToggles>
+    costMode: CostMode
+  }
+  guard: {
+    enabled: boolean
+    tiers: ('cheap')[]
+    whitelist: string[]
+    protectedPaths: string[]
+    interopDefend: 'auto' | 'none'
+  }
+  escalation: {
+    threshold: number
+    windowMs: number
+    ttlMs: number
+    fallbackTtlMs: number
+    signature: boolean
+  }
+  routingMode: RoutingMode
+}
+
+/** Throw the standard fail-loud config error for one invalid field. */
+function invalid(field: string, detail: string): never {
+  throw new Error(`dsh-autotier: config.${field} ${detail}`)
+}
+
+/** Read a required non-empty string field, failing loud when absent or blank. */
+function text(field: string, value: string | undefined, fallback: string): string {
+  const resolved = value ?? fallback
+  if (typeof resolved !== 'string' || resolved.trim().length === 0) invalid(field, 'must be a non-empty string')
+  return resolved
+}
+
+/** Read a bounded finite number. */
+function number(field: string, value: number | undefined, fallback: number, min: number, max: number): number {
+  const resolved = value ?? fallback
+  if (!Number.isFinite(resolved) || resolved < min || resolved > max) {
+    invalid(field, `must be a finite number in [${String(min)}, ${String(max)}]`)
+  }
+  return resolved
+}
+
+/** Read an integer in a closed range. */
+function integer(field: string, value: number | undefined, fallback: number, min: number, max: number): number {
+  const resolved = value ?? fallback
+  if (!Number.isInteger(resolved) || resolved < min || resolved > max) {
+    invalid(field, `must be an integer in [${String(min)}, ${String(max)}]`)
+  }
+  return resolved
+}
+
+/** Read a boolean switch. */
+function boolean(field: string, value: boolean | undefined, fallback: boolean): boolean {
+  const resolved = value ?? fallback
+  if (typeof resolved !== 'boolean') invalid(field, 'must be a boolean')
+  return resolved
+}
+
+/** Read one member of a closed string set. */
+function member<T extends string>(field: string, value: string | undefined, fallback: T, allowed: readonly T[]): T {
+  const resolved = value ?? fallback
+  if (!(allowed as readonly string[]).includes(resolved)) {
+    invalid(field, `must be one of ${allowed.join(', ')}`)
+  }
+  return resolved as T
+}
+
+/** Resolve one tier, judging its landing, effort vocabulary and fallback chain. */
+function resolveTier(
+  tier: 'strong' | 'cheap',
+  raw: TierConfig | undefined,
+  fallback: { provider: string; model: string; effort: EffortId; followSession: boolean },
+): ResolvedTierConfig {
+  const provider = text(`tiers.${tier}.provider`, raw?.provider, fallback.provider)
+  const model = text(`tiers.${tier}.model`, raw?.model, fallback.model)
+  const effort = member(`tiers.${tier}.effort`, raw?.effort, fallback.effort, EFFORT_IDS)
+  const followSession = boolean(`tiers.${tier}.followSession`, raw?.followSession, fallback.followSession)
+  const chain: ResolvedFallbackEntry[] = []
+  const seen = new Set<string>([`${provider}/${model}`])
+  for (const [index, entry] of (raw?.fallback ?? []).entries()) {
+    const entryProvider = text(`tiers.${tier}.fallback[${String(index)}].provider`, entry.provider, '')
+    const entryModel = text(`tiers.${tier}.fallback[${String(index)}].model`, entry.model, '')
+    const key = `${entryProvider}/${entryModel}`
+    if (seen.has(key)) {
+      invalid(`tiers.${tier}.fallback[${String(index)}]`, `duplicates the tier landing or an earlier fallback (${key})`)
+    }
+    seen.add(key)
+    chain.push({ provider: entryProvider, model: entryModel })
+  }
+  return { provider, model, effort, followSession, fallback: chain }
+}
+
+/** Resolve the intent section. */
+function resolveIntent(raw: IntentConfig | undefined): ResolvedConfig['intent'] {
+  const intent = raw ?? {}
+  const ruleThreshold = number('intent.ruleThreshold', intent.ruleThreshold, 0.7, 0.000001, 1)
+  const tauLow = number('intent.attemptBand.tauLow', intent.attemptBand?.tauLow, 0.45, 0, 1)
+  if (tauLow >= ruleThreshold) {
+    invalid('intent.attemptBand.tauLow', `must stay below intent.ruleThreshold (${String(tauLow)} >= ${String(ruleThreshold)})`)
+  }
+  const toStrong = number('intent.hysteresis.toStrong', intent.hysteresis?.toStrong, 0.8, 0, 1)
+  const toCheap = number('intent.hysteresis.toCheap', intent.hysteresis?.toCheap, 0.6, 0, 1)
+  if (toCheap >= toStrong) {
+    invalid('intent.hysteresis', `toCheap (${String(toCheap)}) must stay below toStrong (${String(toStrong)})`)
+  }
+  const rules: ResolvedRule[] = []
+  const ruleIds = new Set<string>()
+  for (const [index, rule] of (intent.rules ?? []).entries()) {
+    const id = text(`intent.rules[${String(index)}].id`, rule.id, '')
+    if (ruleIds.has(id)) invalid(`intent.rules[${String(index)}].id`, `duplicates rule id ${JSON.stringify(id)}`)
+    ruleIds.add(id)
+    const priority = rule.priority ?? 0
+    if (!Number.isFinite(priority)) invalid(`intent.rules[${String(index)}].priority`, 'must be a finite number')
+    const patterns = [...(rule.when?.patterns ?? [])]
+    const tools = [...(rule.when?.tools ?? [])]
+    if (patterns.length === 0 && tools.length === 0) {
+      invalid(`intent.rules[${String(index)}].when`, 'must declare at least one pattern or tool')
+    }
+    for (const [patternIndex, pattern] of patterns.entries()) {
+      if (typeof pattern !== 'string' || pattern.length === 0) {
+        invalid(`intent.rules[${String(index)}].when.patterns[${String(patternIndex)}]`, 'must be a non-empty regular expression')
+      }
+      try {
+        // Compile with the same flags `compileRules` uses, so a pattern the
+        // judge accepts can never throw later inside a settings watcher.
+        new RegExp(pattern, 'u')
+      } catch (error) {
+        invalid(
+          `intent.rules[${String(index)}].when.patterns[${String(patternIndex)}]`,
+          `is not a valid regular expression (${String(error)})`,
+        )
+      }
+    }
+    for (const [toolIndex, tool] of tools.entries()) {
+      if (typeof tool !== 'string' || tool.trim().length === 0) {
+        invalid(`intent.rules[${String(index)}].when.tools[${String(toolIndex)}]`, 'must be a non-empty tool name')
+      }
+    }
+    rules.push({
+      id,
+      when: { patterns, tools, cwd: rule.when?.cwd ?? '' },
+      tier: member(`intent.rules[${String(index)}].tier`, rule.tier, 'strong', ['cheap', 'strong'] as const),
+      priority,
+    })
+  }
+  const judge = intent.judge ?? {}
+  const judgeModel = judge.model ?? ''
+  if (typeof judgeModel !== 'string') invalid('intent.judge.model', 'must be a string (empty = auto)')
+  const scenarios = Object.fromEntries(SCENARIOS.map(scenario => [
+    scenario,
+    boolean(`intent.scenarios.${scenario}`, intent.scenarios?.[scenario], true),
+  ])) as Required<ScenarioToggles>
+  return {
+    ruleThreshold,
+    attemptBand: { enabled: boolean('intent.attemptBand.enabled', intent.attemptBand?.enabled, false), tauLow },
+    hysteresis: { toStrong, toCheap },
+    rules,
+    judge: {
+      enabled: boolean('intent.judge.enabled', judge.enabled, true),
+      model: judgeModel,
+      temperature: number('intent.judge.temperature', judge.temperature, 0, 0, 2),
+      maxTokens: integer('intent.judge.maxTokens', judge.maxTokens, 16, 1, 4_096),
+      cooldownMs: number('intent.judge.cooldownMs', judge.cooldownMs, 30_000, 0, 3_600_000),
+      timeoutMs: number('intent.judge.timeoutMs', judge.timeoutMs, 2_000, 1, 120_000),
+      unavailableSkip: integer('intent.judge.unavailableSkip', judge.unavailableSkip, 2, 0, 100),
+    },
+    scenarios,
+    costMode: member('intent.costMode', intent.costMode, 'balanced', COST_MODES),
+  }
+}
+
+/** Resolve the guard section. */
+function resolveGuard(raw: GuardConfig | undefined): ResolvedConfig['guard'] {
+  const guard = raw ?? {}
+  const whitelist = [...(guard.whitelist ?? [])]
+  for (const [index, entry] of whitelist.entries()) {
+    if (typeof entry !== 'string' || entry.trim().length === 0) {
+      invalid(`guard.whitelist[${String(index)}]`, 'must be a non-empty string')
+    }
+  }
+  const protectedPaths = [...(guard.protectedPaths ?? ['.dsh', 'AGENTS.md', 'package.json', '.github/workflows'])]
+  for (const [index, entry] of protectedPaths.entries()) {
+    if (typeof entry !== 'string' || entry.trim().length === 0) {
+      invalid(`guard.protectedPaths[${String(index)}]`, 'must be a non-empty path or glob')
+    }
+  }
+  const tiers: ('cheap')[] = guard.tiers === undefined ? ['cheap'] : guard.tiers.map((tier, index) => {
+    if (tier !== 'cheap') invalid(`guard.tiers[${String(index)}]`, 'must be "cheap"')
+    return tier
+  })
+  if (tiers.length === 0) {
+    invalid('guard.tiers', 'must list at least one tier; use guard.enabled=false to disable the guard')
+  }
+  return {
+    enabled: boolean('guard.enabled', guard.enabled, true),
+    tiers,
+    whitelist,
+    protectedPaths,
+    interopDefend: member('guard.interopDefend', guard.interopDefend, 'auto', ['auto', 'none'] as const),
+  }
+}
+
+/** Resolve the escalation section. */
+function resolveEscalation(raw: EscalationConfig | undefined): ResolvedConfig['escalation'] {
+  const escalation = raw ?? {}
+  return {
+    threshold: integer('escalation.threshold', escalation.threshold, 2, 1, 100),
+    windowMs: number('escalation.windowMs', escalation.windowMs, 60_000, 1, 86_400_000),
+    ttlMs: number('escalation.ttlMs', escalation.ttlMs, 180_000, 1, 86_400_000),
+    fallbackTtlMs: number('escalation.fallbackTtlMs', escalation.fallbackTtlMs, 300_000, 1, 86_400_000),
+    signature: boolean('escalation.signature', escalation.signature, true),
+  }
+}
+
+/** Deep-freeze a resolved configuration tree. */
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === 'object') {
+    for (const nested of Object.values(value as Record<string, unknown>)) deepFreeze(nested)
+    Object.freeze(value)
+  }
+  return value
+}
+
+/**
+ * The landing a tier actually resolves to. `followSession` tiers omit their
+ * effort, so two tiers that differ only by a configured-but-ignored effort are
+ * the same landing and must be rejected.
+ */
+function effectiveLanding(tier: ResolvedTierConfig): string {
+  return tier.followSession
+    ? `${tier.provider}/${tier.model}@session`
+    : `${tier.provider}/${tier.model}@${tier.effort}`
+}
+
+/**
+ * Resolve raw config to the frozen runtime policy, re-judging every default,
+ * bound and cross-field requirement.
+ *
+ * @param raw - raw loader config; `undefined` for a bare row.
+ * @returns the frozen resolved config.
+ * @throws {Error} when a value is out of bounds or a cross-field requirement fails.
+ */
+export function resolveConfig(raw: Config | undefined): ResolvedConfig {
+  const tiers = raw?.tiers ?? {}
+  const strong = resolveTier('strong', tiers.strong, DEFAULT_STRONG)
+  const cheap = resolveTier('cheap', tiers.cheap, DEFAULT_CHEAP)
+  const strongTriple = effectiveLanding(strong)
+  const cheapTriple = effectiveLanding(cheap)
+  if (strongTriple === cheapTriple) {
+    invalid('tiers', `strong and cheap resolve to the same landing (${strongTriple}); tiering would be a no-op`)
+  }
+  const resolved: ResolvedConfig = {
+    tiers: {
+      strong,
+      cheap,
+      vision: {
+        provider: text('tiers.vision.provider', tiers.vision?.provider, DEFAULT_VISION.provider),
+        model: text('tiers.vision.model', tiers.vision?.model, DEFAULT_VISION.model),
+      },
+    },
+    intent: resolveIntent(raw?.intent),
+    guard: resolveGuard(raw?.guard),
+    escalation: resolveEscalation(raw?.escalation),
+    routingMode: member('routingMode', raw?.routingMode, 'auto', ROUTING_MODES),
+  }
+  return deepFreeze(resolved)
+}
+
+/**
+ * Judge a configuration without keeping the resolved value. This is the
+ * save-time hook the `autotier` settings namespace registers, so a user write
+ * that violates a cross-field requirement is refused at the write instead of
+ * silently disabling the plugin.
+ *
+ * @param value - the configuration to judge.
+ * @throws {Error} when the configuration is invalid.
+ */
+export function validateConfig(value: Config): void {
+  resolveConfig(value)
+}

package/src/guard-rules.ts

@@ -0,0 +1,303 @@
+/**
+ * High-impact command and path rules for the autotier guard.
+ *
+ * A TypeScript port of the dependency-free rule logic in `lib/pure.js` of
+ * `dsh-tier-router` (v0.5.0, MIT — see `THIRD_PARTY_NOTICES.md`): the
+ * `ARG_RUNNERS`/`DIRECT_RUNNERS` command-position detection, the 16
+ * `HIGH_IMPACT_COMMAND` patterns, and the 5 `HIGH_IMPACT_PATH` patterns. The
+ * upstream matching order, case-insensitivity, anchored command position, and
+ * 80/120-character truncation are preserved exactly; the port only adds stable
+ * rule ids and the `GuardMatch` shape the guard layer consumes.
+ *
+ * INTENTIONAL DELTA OVER UPSTREAM (the plugin's own Apache-2.0 addition, not
+ * upstream code): upstream never looks inside a `sh -c "..."` payload, so
+ * `sh -c "rm -rf /"` is a documented false negative. {@link SHELL_WRAPPERS} and
+ * {@link SHELL_WRAPPER_MAX_DEPTH} add a second pass that runs only after the
+ * upstream rules return no match: it strips a leading command runner, extracts
+ * the `-c` payload (single-dash flag clusters such as `-lc`, case-insensitive
+ * wrapper names, and the optional backslash escape included), unescapes it, and
+ * re-runs the same matcher on it (bounded by depth) under a
+ * `shell-wrapper:<inner rule>` id. No upstream verdict changes.
+ *
+ * Matching is deliberately conservative: it is a review/escalation signal, never
+ * a substitute for `dsh-defend`, approvals, or the sandbox policy.
+ * @module dsh-autotier/guard-rules
+ */
+
+/**
+ * Command runners that may prefix `rm` and still execute it, split by whether
+ * they legitimately carry their own arguments before the command.
+ *
+ * `ARG_RUNNERS` allow any arguments before `rm` (`env -i rm -rf`,
+ * `timeout 5 rm -rf`, `xargs -0 rm -rf`); `DIRECT_RUNNERS` take the command
+ * immediately (`nohup rm -rf`), because allowing arguments there would
+ * false-positive on harmless forms like `nohup echo rm -rf`.
+ */
+const ARG_RUNNERS = 'sudo|env|timeout|nice|xargs|doas|setarch|stdbuf|ionice'
+const DIRECT_RUNNERS = 'command|exec|busybox|nohup|pkexec'
+
+/**
+ * `rm` at command position: start of string, after a command separator
+ * (`;`, `&`, `|`), or after one of the runners above. `\\?` makes the leading
+ * backslash escape (`\rm -rf`) optional rather than required.
+ */
+const RECURSIVE_FORCE_RM = new RegExp(
+  '(^|[;&|]\\s*' +
+    '|\\b(' + ARG_RUNNERS + ')\\s+(?:\\S+\\s+)*' +
+    '|\\b(' + DIRECT_RUNNERS + ')\\s+' +
+    ')\\\\?rm(\\s+)',
+  'i',
+)
+
+/** Command matches are trimmed and truncated to this many characters. */
+const COMMAND_MATCH_LIMIT = 80
+
+/** Path matches are truncated to this many characters (upstream: whole path). */
+const PATH_MATCH_LIMIT = 120
+
+/**
+ * Shell wrappers whose `-c` payload must be re-scanned (upstream misses these).
+ * This table and {@link SHELL_WRAPPER_MAX_DEPTH} are the plugin's own extension,
+ * not part of the upstream rule port.
+ */
+export const SHELL_WRAPPERS: readonly string[] = ['sh', 'bash', 'zsh', 'dash', 'ksh']
+
+/** Recursion depth bound for nested `sh -c "sh -c ..."` payloads. */
+export const SHELL_WRAPPER_MAX_DEPTH = 3
+
+/**
+ * The wrapper-name alternation in every letter case (`SH`, `Bash`, `sh`, ...)
+ * WITHOUT making the flag cluster case-insensitive: `-C` must not count as a
+ * `-c` cluster.
+ */
+const WRAPPER_NAMES = SHELL_WRAPPERS
+  .map((word) => word.split('').map((letter) => `[${letter}${letter.toUpperCase()}]`).join(''))
+  .join('|')
+
+/**
+ * A wrapper invocation at command position: separator/start, an optional
+ * backslash escape, wrapper name (any letter case), a single-dash flag cluster
+ * containing `c` (`-c`, `-lc`, `-ec`, ... but never a long option such as
+ * `--command`, which has no single-dash cluster before the payload), then a
+ * double-quoted, single-quoted, or bare payload. The quoted forms accept
+ * backslash escapes so nested quoting survives; the captured content is
+ * unescaped before it is re-scanned.
+ */
+const SHELL_WRAPPER_C = new RegExp(
+  `(^|[;&|]\\s*)\\\\?(${WRAPPER_NAMES})\\s+-(?=[a-z]*c[a-z]*\\b)[a-z]+\\s+("((?:[^"\\\\]|\\\\.)*)"|'((?:[^'\\\\]|\\\\.)*)'|(\\S+))`,
+)
+
+/** A command runner at the very start, with optional backslash escape. */
+const RUNNER_AT_START = new RegExp(`^\\s*\\\\?(${ARG_RUNNERS}|${DIRECT_RUNNERS})\\s+`)
+
+/** An argument-carrying runner at the very start. */
+const ARG_RUNNER_AT_START = new RegExp(`^\\s*\\\\?(${ARG_RUNNERS})\\s+`)
+
+/** One leading whitespace-delimited token. */
+const LEADING_TOKEN = /^(\S+)\s+/
+
+/** One named high-impact rule. */
+export interface GuardRule {
+  /** Stable kebab-case identifier, also reported in {@link GuardMatch.rule}. */
+  readonly id: string
+  /** Human-readable description of the destruction the rule protects against. */
+  readonly description: string
+  /** The upstream pattern, unchanged (no `g` flag, so matching is stateless). */
+  readonly pattern: RegExp
+}
+
+/** A matched rule plus the exact text that matched. */
+export interface GuardMatch {
+  /** The {@link GuardRule.id} that matched, or `shell-wrapper:<inner rule>`. */
+  readonly rule: string
+  /** The matched rule's description. */
+  readonly description: string
+  /**
+   * The matched text: for commands the matched substring trimmed and truncated
+   * to 80 characters; for paths the whole target path truncated to 120
+   * characters (upstream reports the path, not the regex substring).
+   */
+  readonly matched: string
+}
+
+/**
+ * The 16 upstream `HIGH_IMPACT_COMMAND` patterns, in upstream array order.
+ * `matchCommand` returns the first hit, so order is part of the contract:
+ * `sudo` precedes `wget-pipe-shell`, and the separate `rm` rule precedes all
+ * of these.
+ */
+export const HIGH_IMPACT_COMMAND_RULES: readonly GuardRule[] = [
+  { id: 'mkfs', description: 'mkfs: filesystem creation on a device', pattern: /\bmkfs\.?[a-z]*\b/ },
+  { id: 'dd-write', description: 'dd with if=/of=: raw device read/write', pattern: /\bdd\s+(if|of)=/ },
+  { id: 'sudo', description: 'sudo: privilege escalation at command position', pattern: /(^|[;&|]\s*)sudo\b/ },
+  { id: 'shutdown', description: 'shutdown/reboot/halt: system power control', pattern: /(^|[;&|]\s*)(shutdown|reboot|halt)\b/ },
+  { id: 'git-push-force', description: 'git push --force/-f: remote history rewrite', pattern: /git\s+push\s+[^\n]*(-f\b|--force)/ },
+  { id: 'git-clean-force', description: 'git clean -f: untracked file deletion', pattern: /git\s+clean\s+(-[a-z]*f[a-z]*\b)/ },
+  { id: 'find-delete', description: 'find -delete: recursive file deletion', pattern: /find\s+[^\n]*\s+-delete\b/ },
+  { id: 'find-exec-rm', description: 'find -exec rm: deletion through find', pattern: /find\s+[^\n]*-exec\s+[^\n]*\brm\b/ },
+  { id: 'shutil-rmtree', description: 'shutil.rmtree(...): recursive Python deletion', pattern: /\b(shutil\.rmtree|rmtree)\s*\(/ },
+  { id: 'os-remove', description: 'os.remove(...): Python file deletion', pattern: /\bos\.remove\s*\(/ },
+  { id: 'python-inline-delete', description: 'python -c with inline deletion', pattern: /python[0-9.]*\s+-c\s+[^|;&\n]*(rmtree|os\.remove|shutil\.rmtree|rm\s+-rf)/ },
+  { id: 'curl-pipe-shell', description: 'curl | sh: remote script execution', pattern: /curl\s+[^\n]*\|\s*(sudo\s+)?(ba)?sh\b/ },
+  { id: 'wget-pipe-shell', description: 'wget | sh: remote script execution', pattern: /wget\s+[^\n]*\|\s*(sudo\s+)?(ba)?sh\b/ },
+  { id: 'chmod-ssh', description: 'chmod on a .ssh/ path: SSH key permission change', pattern: /\bchmod\s+[0-7]{3,4}\s+[^\n]*\.ssh\// },
+  { id: 'chown', description: 'chown: ownership change', pattern: /\bchown\s/ },
+  { id: 'diskutil-erase', description: 'diskutil erase/unmount: macOS disk destruction', pattern: /\bdiskutil\s+(eraseDisk|eraseVolume|zeroDisk|secureErase|unmountDisk)\b/ },
+]
+
+/**
+ * The 5 upstream `HIGH_IMPACT_PATH` patterns (credentials, keys, secrets), in
+ * upstream array order. `.env` matches unless the suffix is an
+ * example/sample/template name.
+ */
+export const HIGH_IMPACT_PATH_RULES: readonly GuardRule[] = [
+  { id: 'dotenv', description: '.env secrets file (example/sample/template names excluded)', pattern: /(^|\/)\.env(\.(?!example|sample|template)[^/]*)?$/i },
+  { id: 'credentials', description: 'credentials/secrets file or directory', pattern: /(^|\/)(credentials?|secrets?)(\.(json|ya?ml|toml|ini|env|key|pem|txt))?($|\/)/i },
+  { id: 'ssh-dir', description: '.ssh/ directory', pattern: /(^|\/)\.ssh\// },
+  { id: 'private-key', description: 'id_rsa/id_ed25519/id_ecdsa/id_dsa key or .netrc', pattern: /(^|\/)(id_(rsa|ed25519|ecdsa|dsa)|\.netrc)(\b|\/)/i },
+  { id: 'key-file', description: '.pem/.key/.p12/.pfx/.jks key material', pattern: /\.(pem|key|p12|pfx|jks)$/i },
+]
+
+/** Description reported for the separate recursive-force `rm` rule. */
+const RM_RECURSIVE_FORCE_DESCRIPTION = 'command pattern rm -r/-f matched (recursive force delete)'
+
+/**
+ * Match `rm` at command position with BOTH recursive (`-r`/`-R`/`--recursive`)
+ * and force (`-f`/`--force`) flags, including split flags (`rm -r -f`) that a
+ * single-token check misses.
+ * @param command - one shell command string.
+ * @returns the matched command-position text (trimmed, truncated), or null.
+ */
+function matchRecursiveForceRm(command: string): string | null {
+  const separator = command.match(RECURSIVE_FORCE_RM)
+  if (separator === null) return null
+  const head = separator[0] ?? ''
+  const rest = command.slice((separator.index ?? 0) + head.length)
+  let flags = ''
+  for (const token of rest.split(/\s+/)) {
+    if (/^--?[a-zA-Z]/.test(token)) flags += token.replace(/^-+/, '')
+    else break
+  }
+  const lowered = flags.toLowerCase()
+  if (!lowered.includes('r') || !lowered.includes('f')) return null
+  return head.trim().slice(0, COMMAND_MATCH_LIMIT)
+}
+
+/**
+ * Match the upstream command rules only: the recursive-force `rm` rule first
+ * (upstream order), then {@link HIGH_IMPACT_COMMAND_RULES} in array order.
+ */
+function matchUpstreamCommand(command: string): GuardMatch | null {
+  const rm = matchRecursiveForceRm(command)
+  if (rm !== null) {
+    return { rule: 'rm-recursive-force', description: RM_RECURSIVE_FORCE_DESCRIPTION, matched: rm }
+  }
+  for (const rule of HIGH_IMPACT_COMMAND_RULES) {
+    const match = command.match(rule.pattern)
+    if (match !== null) {
+      return {
+        rule: rule.id,
+        description: rule.description,
+        matched: (match[0] ?? '').trim().slice(0, COMMAND_MATCH_LIMIT),
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Strip leading command runners (and the arguments an argument-carrying runner
+ * may carry) so a `sh -c ...` behind `env -i`, `timeout 5`, or `nohup` is still
+ * seen at command position. Argument consumption stops at a shell wrapper,
+ * matched case-insensitively and with the optional backslash escape removed.
+ */
+function stripRunnerPrefix(command: string): string {
+  let rest = command
+  for (;;) {
+    const carriesArgs = ARG_RUNNER_AT_START.test(rest)
+    const runner = RUNNER_AT_START.exec(rest)
+    if (runner === null) return rest
+    rest = rest.slice((runner[0] ?? '').length)
+    if (!carriesArgs) continue
+    for (;;) {
+      const token = LEADING_TOKEN.exec(rest)
+      const word = (token?.[1] ?? '').replace(/^\\/, '').toLowerCase()
+      if (token === null || SHELL_WRAPPERS.includes(word)) break
+      rest = rest.slice((token[0] ?? '').length)
+    }
+  }
+}
+
+/** The `-c` payload of the first shell-wrapper invocation, or null. */
+function matchShellWrapperPayload(command: string): string | null {
+  const wrapper = SHELL_WRAPPER_C.exec(stripRunnerPrefix(command))
+  if (wrapper === null) return null
+  const payload = wrapper[4] ?? wrapper[5] ?? wrapper[6] ?? ''
+  return payload.replace(/\\(["'\\])/g, '$1')
+}
+
+/**
+ * The full matcher: upstream rules first, then the bounded shell-wrapper
+ * extension. `depth` counts wrapper unwrappings, so a payload nested deeper
+ * than {@link SHELL_WRAPPER_MAX_DEPTH} is left unmatched.
+ */
+function matchCommandAtDepth(command: string, depth: number): GuardMatch | null {
+  const upstream = matchUpstreamCommand(command)
+  if (upstream !== null) return upstream
+  if (depth >= SHELL_WRAPPER_MAX_DEPTH) return null
+  const payload = matchShellWrapperPayload(command)
+  if (payload === null) return null
+  const inner = matchCommandAtDepth(payload, depth + 1)
+  if (inner === null) return null
+  return {
+    rule: `shell-wrapper:${inner.rule}`,
+    description: `shell wrapper -c payload: ${inner.description}`,
+    matched: inner.matched.slice(0, COMMAND_MATCH_LIMIT),
+  }
+}
+
+/**
+ * True for `rm` with BOTH recursive and force flags at command position (split
+ * flags included). Prose (`echo rm -rf`) and runner-argument false positives
+ * (`nohup echo rm -rf`) stay unmatched. Upstream-exact: this never unwraps a
+ * shell wrapper.
+ */
+export function hasRecursiveForceRm(command: string): boolean {
+  return matchRecursiveForceRm(command) !== null
+}
+
+/**
+ * Match one shell command string against the recursive-force `rm` rule first
+ * (upstream order) and then the command rules in array order; only when those
+ * find nothing, re-scan a `sh -c`-style payload (see the module header delta).
+ * @param command - one shell command string.
+ * @returns the first match, or null when the command is not high impact.
+ */
+export function matchCommand(command: string): GuardMatch | null {
+  return matchCommandAtDepth(command, 0)
+}
+
+/**
+ * Match one file path (a write/edit target) against the path rules in array
+ * order.
+ * @param filePath - one target path.
+ * @returns the first match, or null when the path is not high impact.
+ */
+export function matchPath(filePath: string): GuardMatch | null {
+  const rule = HIGH_IMPACT_PATH_RULES.find((candidate) => candidate.pattern.test(filePath))
+  if (rule === undefined) return null
+  return {
+    rule: rule.id,
+    description: rule.description,
+    matched: filePath.slice(0, PATH_MATCH_LIMIT),
+  }
+}
+
+/**
+ * Credential/secret path classification for protected-path review: true when
+ * any of the {@link HIGH_IMPACT_PATH_RULES} matches, i.e. exactly the paths
+ * {@link matchPath} reports.
+ */
+export function isCredentialPath(filePath: string): boolean {
+  return HIGH_IMPACT_PATH_RULES.some((rule) => rule.pattern.test(filePath))
+}