dsh-perm-gate 2.1.2 → 4.0.0

package/lib/engine.js

@@ -9,7 +9,14 @@
  * Strictly fail-closed: P0 wins over every later stage.
  */
 import { isProtectedDestructiveTarget, isSensitivePath, isWithin } from './path.js';
+// SHELL_TOOLS 是**值的导入**：这份名单必须与 evaluate.ts / runtime.ts 共用同一个
+// 事实源。此处曾经自带一份 `/(?:bash|pwsh|sh|cmd)$/` 正则，漏掉了 `shell` /
+// `terminal` / `powershell`——于是 P0 的 shell 检查对 DSH 的**主 shell 工具**
+// 完全失效（实测：同一句 `echo x > /etc/passwd`，bash 被拦截，shell 放行）。
+// 同名事实的第二份副本必然腐烂，这里不再保留副本。
+import { SHELL_TOOLS } from './evaluate.js';
 import { isForceDeletion, isRecursiveDeletion, decomposeShellCommand } from './shell.js';
+import { dispatchCommand } from './command-dispatcher.js';
 const DESTRUCTIVE_TOOL = /(?:^|[_-])(?:delete|remove|rm|destroy|erase|purge|wipe|unlink|rmdir|reset)(?:$|[_-]|recursive)/i;
 /**
  * Read-only tools that can never modify the workspace or execute anything. P0
@@ -107,6 +114,42 @@ function pathArgument(args) {
     }
     return undefined;
 }
+/** 廉价前缀过滤：绝大多数 shell 调用不是 push，先过一遍正则再动用解析器。 */
+const GIT_PUSH_TEXT = /\bgit\s+push\b/;
+/**
+ * 远端历史改写：`git push` 强制覆盖或删除**保护分支**。
+ *
+ * **「只升不降」是形状约束，不是口头约定**：返回值只有 `string | undefined`，
+ * 调用方把 `string` 读作 deny、`undefined` 读作「继续走后面的阶段」。本函数
+ * 结构上**无法**产生 allow，所以挂在 P0 上永远不会放宽门的判定。
+ *
+ * 刻意**不**覆盖（仍交给关键词层 / 规则层 / LLM 层）：
+ * - 非保护分支上的 force push（如 `origin feat/x`）——P0 不可撤销，得给工作流留口子；
+ * - 没写分支名的 `git push --force`——解析不出目标就不做断言；
+ * - 普通 push。
+ *
+ * 这正是本插件补不上的那一段：`DEFAULT_DENY_KEYWORDS` 里的 `'push --force'` 是
+ * **扁平的、可被命名空间覆盖掉**的，且完全不看分支；P0 这一层则是不可协商的底。
+ */
+function gitRemoteRewriteReason(segments) {
+    for (const seg of segments) {
+        const text = [seg.command, ...seg.args].join(' ');
+        if (!GIT_PUSH_TEXT.test(text))
+            continue;
+        const result = dispatchCommand(text);
+        if (result === null)
+            continue;
+        const s = result.semantics;
+        if (s.operation !== 'force-push' && s.operation !== 'push-delete')
+            continue;
+        if (!s.targetsSharedBranch)
+            continue;
+        const what = s.operation === 'push-delete' ? 'delete' : 'force-overwrite';
+        const remote = s.remote === undefined ? '' : ` (remote ${s.remote})`;
+        return `git push would ${what} protected branch: ${s.branch}${remote}`;
+    }
+    return undefined;
+}
 /**
  * Deterministic P0 hard-deny reason, or undefined when the call may proceed to
  * later stages.
@@ -115,8 +158,7 @@ export function hardDenyReason(ctx) {
     const args = ctx.args;
     if (containsCredentialMaterial(args))
         return 'call contains credential or private-key material';
-    const shell = /^(?:bash|pwsh|sh|cmd)$/.test(ctx.tool);
-    if (shell && typeof args.command === 'string') {
+    if (SHELL_TOOLS.has(ctx.tool) && typeof args.command === 'string') {
         let commands = [];
         try {
             commands = decomposeShellCommand(args.command).commands;
@@ -133,8 +175,16 @@ export function hardDenyReason(ctx) {
             if (redir !== undefined)
                 return `shell redirect targets protected path: ${redir}`;
         }
+        const rewrite = gitRemoteRewriteReason(commands);
+        if (rewrite !== undefined)
+            return rewrite;
     }
     const path = pathArgument(args);
+    // 注意：这里**刻意不**用 SHELL_TOOLS。本判据读的是 `pathArgument`（file_path /
+    // path / cwd / **workdir**），它是"被改写的路径"而不是"要执行的命令"。shell 工具的
+    // 真目标在 command 里，由上面的命令级检查负责；若把 shell 工具也塞进来，
+    // `shell({ command: 'ls', workdir: '/etc' })` 这种纯读操作会因为 workdir 落在受保护
+    // 前缀而被 P0 永久挡住——那是过度拦截，而且 P0 撤销不了。
     if (path !== undefined && (DESTRUCTIVE_TOOL.test(ctx.tool) || ctx.tool === 'bash' || ctx.tool === 'pwsh' || ctx.tool === 'write' || ctx.tool === 'edit')) {
         if (isProtectedDestructiveTarget(path, ctx.dshHome))
             return `mutation targets protected path: ${path}`;

package/lib/evaluate.js

@@ -5,8 +5,9 @@
  */
 import { normalizeWorkspacePath } from './path.js';
 import { extractPathCandidates, extractUrlCandidates, } from './rule.js';
-import { decomposeShellCommand, isForceDeletion, isRecursiveDeletion } from './shell.js';
+import { commandArgv, decomposeShellCommand, isForceDeletion, isRecursiveDeletion } from './shell.js';
 import { compileCidr, compilePortSpec, compileDomainPattern } from './compiler.js';
+import { dispatchCommand } from './command-dispatcher.js';
 /**
  * Tool names that execute a shell command string. `shell` and `terminal` are
  * DSH's own names (the shipped tool roster uses `shell`; `terminal` is the
@@ -95,7 +96,10 @@ export function ruleMatches(rule, ctx, commands, pathCands, urlCands) {
     if (rule.argv?.pipeline !== undefined && rule.argv.pipeline.length > 0) {
         if (commands.length === 0)
             return false;
-        const pipelineText = commands.map((c) => c.command).join('|');
+        // Join the FULL argv of each simple command: `c.command` alone is just the
+        // command word, so `curl https://x | sh` would read as `curl|sh` and the
+        // documented `curl|sh` pattern could never see its own subject.
+        const pipelineText = commands.map((c) => commandArgv(c)).join('|');
         const compiled = rule.argv.pipeline.map((p) => compileGlobForMatch(p));
         if (!compiled.some((g) => g.test(pipelineText)))
             return false;
@@ -105,6 +109,13 @@ export function ruleMatches(rule, ctx, commands, pathCands, urlCands) {
         if (!matchNetwork(rule.network, ctx.network))
             return false;
     }
+    // branch dimension: git semantics only; non-git commands satisfy no branch
+    // dimension (per sub-dimension above). Never throws — a parser is pure, and
+    // the dispatcher falls back to `family: 'unknown'` rather than raising.
+    if (rule.branch !== undefined) {
+        if (!matchBranch(rule.branch, commands))
+            return false;
+    }
     return true;
 }
 const WRITE_TOOLS = new Set(['write', 'edit']);
@@ -371,3 +382,66 @@ function matchNetwork(network, ctx) {
     }
     return true;
 }
+/**
+ * Per-call memo for command classification.
+ *
+ * `ruleMatches` runs once per rule, so a rule chain with several `branch`
+ * rules would otherwise re-parse the same command each time. `dispatchCommand`
+ * is pure, so caching its result per `SimpleCommand` object is safe; the
+ * WeakMap keeps no references once the command array is dropped.
+ */
+const commandSemanticsCache = new WeakMap();
+function semanticsOf(cmd) {
+    const cached = commandSemanticsCache.get(cmd);
+    if (cached !== undefined)
+        return cached;
+    // The parser needs the WHOLE argv: `cmd.command` carries only the command
+    // word, so `git push --force origin main` would arrive as `git` and classify
+    // as `family: unknown` (no branch, no remote, no flags).
+    const result = dispatchCommand(commandArgv(cmd));
+    commandSemanticsCache.set(cmd, result);
+    return result;
+}
+/**
+ * Branch dimension matching (git semantics only).
+ *
+ * Candidates come from the shared command dispatcher, so `refspec` forms
+ * (`HEAD:main`) are already split and a remote name is never mistaken for a
+ * branch name. Sub-dimensions are AND (each present one must match); within a
+ * sub-dimension the entries are OR.
+ *
+ * **Non-git commands satisfy no branch dimension**: `dispatchCommand` reports
+ * `family: 'unknown'` for them rather than throwing, so a rule that names a
+ * branch simply does not match `rm -rf`, `npm install` and friends. That is
+ * deliberate — the write-path/blacklist layers cover non-git commands.
+ *
+ * `shared` is the parser's STATIC protected-branch rule (main / master /
+ * production / release / stable, see `src/parsers/git.ts`). No git subprocess
+ * ever runs on the decision path.
+ */
+function matchBranch(branch, commands) {
+    if (commands.length === 0)
+        return false;
+    const branches = [];
+    const remotes = [];
+    let anyShared = false;
+    for (const cmd of commands) {
+        const result = semanticsOf(cmd);
+        if (result === null || result.semantics.family !== 'git')
+            continue;
+        const { branch: name, remote, targetsSharedBranch } = result.semantics;
+        if (targetsSharedBranch)
+            anyShared = true;
+        if (typeof name === 'string' && name.length > 0)
+            branches.push(name);
+        if (typeof remote === 'string' && remote.length > 0)
+            remotes.push(remote);
+    }
+    if (branch.shared && !anyShared)
+        return false;
+    if (branch.target.length > 0 && !branches.some((b) => branch.target.some((g) => g.re.test(b))))
+        return false;
+    if (branch.remote.length > 0 && !remotes.some((r) => branch.remote.some((g) => g.re.test(r))))
+        return false;
+    return true;
+}

package/lib/events.d.ts

@@ -1,3 +1,4 @@
+import type { RulesView } from './rules-view.js';
 /** One gate decision event. `kind` drives the client notice strip styling. */
 export interface GateEvent {
     /** Monotonic id (resumed from the file across restarts). */
@@ -8,9 +9,11 @@ export interface GateEvent {
     /**
      * auto = allowed (rule/grant/llm), ask = routed to the human, deny = vetoed,
      * learned = confirmation settled, manual-* = the human's terminal answer to an
-     * ask (approved / rejected / cancelled).
+     * ask (approved / rejected / cancelled), stand-down = the gate itself is
+     * inactive in this session's permission preset and therefore decided nothing
+     * (see {@link GateEvent.verdict} `stand-down`).
      */
-    readonly kind: 'auto' | 'ask' | 'deny' | 'learned' | 'manual-approved' | 'manual-rejected' | 'manual-cancelled';
+    readonly kind: 'auto' | 'ask' | 'deny' | 'learned' | 'manual-approved' | 'manual-rejected' | 'manual-cancelled' | 'stand-down';
     /** Risk category when an LLM verdict contributed to the decision. */
     readonly risk?: string;
     /** Truncated decision reason. */
@@ -97,6 +100,13 @@ export declare class EventLog {
     /** Snapshot directory; `undefined` disables diff/revert support. */
     private readonly snapshotsDir;
     private seq;
+    /**
+     * Live subscribers, notified once per successfully appended event. They exist
+     * so a browser half can be pushed to instead of re-reading the whole JSONL on
+     * a timer; a subscriber that throws is dropped from the notification only, it
+     * never costs the append its event.
+     */
+    private readonly listeners;
     constructor(
     /** JSONL path; `undefined` disables event recording entirely. */
     filePath: string | undefined, now?: () => number, 
@@ -104,6 +114,15 @@ export declare class EventLog {
     snapshotsDir?: string | undefined);
     /** Append one event; returns it, or undefined when recording is disabled/failed. */
     append(input: GateEventInput): GateEvent | undefined;
+    /**
+     * Watch events as they are appended. The listener is called once per event,
+     * after the JSONL write, from inside `append` — so it runs on the gate's own
+     * decision path and must stay cheap and non-throwing.
+     *
+     * @param listener - receives each appended event.
+     * @returns the unsubscribe.
+     */
+    subscribe(listener: (event: GateEvent) => void): () => void;
     /** Events with `id > since`, optionally filtered to one session. */
     query({ sessionId, since }?: {
         sessionId?: string;
@@ -125,6 +144,7 @@ export interface WebServerLike {
     }): () => void;
 }
 export declare const EVENTS_ROUTE = "/api/dsh-perm-gate/events";
+export declare const STREAM_ROUTE = "/api/dsh-perm-gate/stream";
 export declare const LEARNING_ROUTE = "/api/dsh-perm-gate/learning";
 export declare const HEALTH_ROUTE = "/api/dsh-perm-gate/health";
 export declare const NETWORK_ROUTE = "/api/dsh-perm-gate/network";
@@ -133,12 +153,32 @@ export declare const DIFF_ROUTE = "/api/dsh-perm-gate/diff";
 export declare const REVERT_ROUTE = "/api/dsh-perm-gate/revert";
 export declare const SNAPSHOTS_STATS_ROUTE = "/api/dsh-perm-gate/snapshots-stats";
 export declare const SNAPSHOTS_CLEAR_ROUTE = "/api/dsh-perm-gate/snapshots-clear";
+export declare const DRY_RUN_ROUTE = "/api/dsh-perm-gate/dry-run";
+export declare const RULES_ROUTE = "/api/dsh-perm-gate/rules";
 /**
  * Register `GET /api/dsh-perm-gate/events?sessionId=&since=` on the webServer
  * service. Returns whether the route was registered (false when the service is
  * unavailable — the host keeps running, only the HTTP API is missing).
  */
 export declare function registerEventsRoute(server: unknown, log: EventLog): (() => void) | undefined;
+/**
+ * Register `GET /api/dsh-perm-gate/stream?sessionId=&since=` on the webServer
+ * service: the same events {@link registerEventsRoute} serves, but pushed.
+ *
+ * The response is `text/event-stream`. On connect the backlog after `since` is
+ * written as one `data: {"events":[…],"backlog":true}` frame, then each event
+ * appended from that moment on is written as it lands as `data: {"events":[…]}` —
+ * so the browser half is never forced to re-read the whole JSONL on a timer.
+ * `: ping` comments hold the connection open while nothing is being decided.
+ *
+ * The session filter applies to both the backlog and the live pushes. Nothing
+ * is buffered for a disconnected client: it reconnects with its own cursor and
+ * the backlog frame restores it.
+ *
+ * Returns the unregister, or `undefined` when the webServer service is
+ * unavailable — the host keeps running, only the HTTP API is missing.
+ */
+export declare function registerStreamRoute(server: unknown, log: EventLog): (() => void) | undefined;
 /** Delivers a revert instruction into the conversation (see index.ts wiring). */
 export type SessionSender = (sessionId: string, content: string) => Promise<{
     ok: boolean;
@@ -196,6 +236,55 @@ export interface LearningRouteProvider {
     threshold(): number;
     reset(key: string, fp?: string): void;
 }
+/** One rule-test request: the call to evaluate, nothing else. */
+export interface DryRunRequest {
+    readonly tool: string;
+    readonly args: Record<string, unknown>;
+    readonly permissive?: boolean;
+}
+/**
+ * The rule-test face the settings card calls. `run` evaluates one call against
+ * the ruleset the gate currently has loaded and returns the report from
+ * `dryRunResult`. It must not change any state — see {@link registerDryRunRoute}.
+ */
+export interface DryRunRouteProvider {
+    run(request: DryRunRequest): unknown;
+}
+/**
+ * Register `POST /api/dsh-perm-gate/dry-run` — the rule-test panel's endpoint.
+ * Body `{ tool, args?, permissive? }`; the response carries the effective
+ * verdict plus the rule layer's own answer.
+ *
+ * **Read-only by construction.** Unlike `/learning` (GET reads, POST resets), this
+ * route has no write form: it never edits rules, grants, learning state or the
+ * settings namespace, and the provider it delegates to evaluates against a
+ * throwaway or live read path only. Testing a rule must not be able to change
+ * the ruleset — otherwise "test it first" would itself be the risky action.
+ *
+ * Returns whether the route was registered.
+ */
+export declare function registerDryRunRoute(server: unknown, provider: DryRunRouteProvider): (() => void) | undefined;
+/**
+ * The permissions-file face the settings card calls. `view` reads the rules file
+ * the gate is loading; it must never write it.
+ */
+export interface RulesRouteProvider {
+    view(): RulesView;
+}
+/**
+ * Register `GET /api/dsh-perm-gate/rules` — the panel's view of the permissions
+ * YAML the gate actually loads.
+ *
+ * **Read-only by construction**, like {@link registerDryRunRoute}: there is no
+ * write form. The card could already *edit* this file — the allowlist section
+ * appends and replaces patterns — but had no way to display it, so an operator
+ * changing rules through the panel could not see the document being changed.
+ * Reading must not be the risky act, and a viewer that could write would make
+ * "let me just look at the rules" a mutation.
+ *
+ * Returns whether the route was registered.
+ */
+export declare function registerRulesRoute(server: unknown, provider: RulesRouteProvider): (() => void) | undefined;
 /**
  * Register the learning-store routes on the webServer service:
  * `GET  /api/dsh-perm-gate/learning` → the store snapshot + live threshold,

package/lib/events.js

@@ -224,6 +224,13 @@ export class EventLog {
     now;
     snapshotsDir;
     seq = -1; // lazily restored from the file on first append
+    /**
+     * Live subscribers, notified once per successfully appended event. They exist
+     * so a browser half can be pushed to instead of re-reading the whole JSONL on
+     * a timer; a subscriber that throws is dropped from the notification only, it
+     * never costs the append its event.
+     */
+    listeners = new Set();
     constructor(
     /** JSONL path; `undefined` disables event recording entirely. */
     filePath, now = Date.now, 
@@ -266,12 +273,34 @@ export class EventLog {
             if ((ev.kind === 'auto' || ev.kind === 'ask') && this.snapshotsDir !== undefined && files !== undefined) {
                 saveEventSnapshots(this.snapshotsDir, ev.id, files, input.baseDir, ev.sessionId, this.now);
             }
+            for (const listener of this.listeners) {
+                try {
+                    listener(ev);
+                }
+                catch {
+                    // A dead subscriber must not fail the append, and must not stop the others.
+                }
+            }
             return ev;
         }
         catch {
             return undefined; // best-effort only
         }
     }
+    /**
+     * Watch events as they are appended. The listener is called once per event,
+     * after the JSONL write, from inside `append` — so it runs on the gate's own
+     * decision path and must stay cheap and non-throwing.
+     *
+     * @param listener - receives each appended event.
+     * @returns the unsubscribe.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
     /** Events with `id > since`, optionally filtered to one session. */
     query({ sessionId, since } = {}) {
         if (this.filePath === undefined)
@@ -349,6 +378,7 @@ function readBody(req, limit = 1024 * 1024) {
     });
 }
 export const EVENTS_ROUTE = '/api/dsh-perm-gate/events';
+export const STREAM_ROUTE = '/api/dsh-perm-gate/stream';
 export const LEARNING_ROUTE = '/api/dsh-perm-gate/learning';
 export const HEALTH_ROUTE = '/api/dsh-perm-gate/health';
 export const NETWORK_ROUTE = '/api/dsh-perm-gate/network';
@@ -357,6 +387,8 @@ export const DIFF_ROUTE = '/api/dsh-perm-gate/diff';
 export const REVERT_ROUTE = '/api/dsh-perm-gate/revert';
 export const SNAPSHOTS_STATS_ROUTE = '/api/dsh-perm-gate/snapshots-stats';
 export const SNAPSHOTS_CLEAR_ROUTE = '/api/dsh-perm-gate/snapshots-clear';
+export const DRY_RUN_ROUTE = '/api/dsh-perm-gate/dry-run';
+export const RULES_ROUTE = '/api/dsh-perm-gate/rules';
 /**
  * Register `GET /api/dsh-perm-gate/events?sessionId=&since=` on the webServer
  * service. Returns whether the route was registered (false when the service is
@@ -393,6 +425,104 @@ export function registerEventsRoute(server, log) {
         },
     });
 }
+/** Keep-alive cadence of {@link registerStreamRoute}: a comment line that keeps an idle stream from being reaped. */
+const STREAM_PING_MS = 15_000;
+/**
+ * Register `GET /api/dsh-perm-gate/stream?sessionId=&since=` on the webServer
+ * service: the same events {@link registerEventsRoute} serves, but pushed.
+ *
+ * The response is `text/event-stream`. On connect the backlog after `since` is
+ * written as one `data: {"events":[…],"backlog":true}` frame, then each event
+ * appended from that moment on is written as it lands as `data: {"events":[…]}` —
+ * so the browser half is never forced to re-read the whole JSONL on a timer.
+ * `: ping` comments hold the connection open while nothing is being decided.
+ *
+ * The session filter applies to both the backlog and the live pushes. Nothing
+ * is buffered for a disconnected client: it reconnects with its own cursor and
+ * the backlog frame restores it.
+ *
+ * Returns the unregister, or `undefined` when the webServer service is
+ * unavailable — the host keeps running, only the HTTP API is missing.
+ */
+export function registerStreamRoute(server, log) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: STREAM_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'GET') {
+                res.writeHead(405);
+                res.end();
+                return;
+            }
+            if (res.write === undefined) {
+                // A server that cannot stream: fail the handshake instead of hanging the browser's EventSource.
+                res.writeHead(500);
+                res.end();
+                return;
+            }
+            let sessionId;
+            let since;
+            try {
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                sessionId = url.searchParams.get('sessionId') ?? undefined;
+                const raw = url.searchParams.get('since');
+                if (raw !== null && raw !== '')
+                    since = Number.parseInt(raw, 10) || 0;
+            }
+            catch {
+                // unparseable URL: stream the unfiltered tail
+            }
+            const scoped = sessionId !== undefined && sessionId !== '';
+            res.writeHead(200, {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache, no-transform',
+                connection: 'keep-alive',
+                'x-accel-buffering': 'no',
+            });
+            const push = (events, backlog = false) => {
+                // The backlog frame is written even when it is empty: it marks where
+                // history stops, so the consumer never mistakes a live event for a replay.
+                if (events.length === 0 && !backlog)
+                    return;
+                try {
+                    res.write?.(`data: ${JSON.stringify(backlog ? { events, backlog: true } : { events })}\n\n`);
+                }
+                catch {
+                    // The socket died between the close event and this write; `close` owns the teardown.
+                }
+            };
+            push(log.query({ sessionId, since }), true);
+            const unsubscribe = log.subscribe((event) => {
+                if (scoped && event.sessionId !== sessionId)
+                    return;
+                push([event]);
+            });
+            const keepAlive = setInterval(() => {
+                try {
+                    res.write?.(': ping\n\n');
+                }
+                catch {
+                    // ignore: `close` owns the teardown
+                }
+            }, STREAM_PING_MS);
+            let closed = false;
+            const close = () => {
+                if (closed)
+                    return;
+                closed = true;
+                clearInterval(keepAlive);
+                unsubscribe();
+            };
+            res.on?.('close', close);
+            res.on?.('error', close);
+        },
+    });
+}
 /**
  * Register the review-page routes:
  * `GET  /diff?eventId=&path=`        → before/after line diff for one file
@@ -682,6 +812,96 @@ export function registerNetworkRoute(server, provider) {
         },
     });
 }
+/**
+ * Register `POST /api/dsh-perm-gate/dry-run` — the rule-test panel's endpoint.
+ * Body `{ tool, args?, permissive? }`; the response carries the effective
+ * verdict plus the rule layer's own answer.
+ *
+ * **Read-only by construction.** Unlike `/learning` (GET reads, POST resets), this
+ * route has no write form: it never edits rules, grants, learning state or the
+ * settings namespace, and the provider it delegates to evaluates against a
+ * throwaway or live read path only. Testing a rule must not be able to change
+ * the ruleset — otherwise "test it first" would itself be the risky action.
+ *
+ * Returns whether the route was registered.
+ */
+export function registerDryRunRoute(server, provider) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: DRY_RUN_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'POST') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            void (async () => {
+                try {
+                    const parsed = await readBody(req);
+                    const tool = parsed.tool;
+                    if (typeof tool !== 'string' || tool === '') {
+                        json(res, 400, { ok: false, error: 'missing tool' });
+                        return;
+                    }
+                    const args = parsed.args;
+                    if (args !== undefined && (typeof args !== 'object' || args === null || Array.isArray(args))) {
+                        json(res, 400, { ok: false, error: 'args must be an object' });
+                        return;
+                    }
+                    const result = provider.run({
+                        tool,
+                        args: (args ?? {}),
+                        ...(typeof parsed.permissive === 'boolean' ? { permissive: parsed.permissive } : {}),
+                    });
+                    json(res, 200, { ok: true, result });
+                }
+                catch (e) {
+                    json(res, 500, { ok: false, error: String(e?.message ?? e) });
+                }
+            })();
+        },
+    });
+}
+/**
+ * Register `GET /api/dsh-perm-gate/rules` — the panel's view of the permissions
+ * YAML the gate actually loads.
+ *
+ * **Read-only by construction**, like {@link registerDryRunRoute}: there is no
+ * write form. The card could already *edit* this file — the allowlist section
+ * appends and replaces patterns — but had no way to display it, so an operator
+ * changing rules through the panel could not see the document being changed.
+ * Reading must not be the risky act, and a viewer that could write would make
+ * "let me just look at the rules" a mutation.
+ *
+ * Returns whether the route was registered.
+ */
+export function registerRulesRoute(server, provider) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: RULES_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'GET') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            try {
+                json(res, 200, { ok: true, result: provider.view() });
+            }
+            catch (e) {
+                json(res, 500, { ok: false, error: String(e?.message ?? e) });
+            }
+        },
+    });
+}
 /**
  * Register the learning-store routes on the webServer service:
  * `GET  /api/dsh-perm-gate/learning` → the store snapshot + live threshold,