dsh-perm-gate 2.1.0 → 2.1.2

package/lib/compiler.d.ts

@@ -28,3 +28,42 @@ export declare function compileGlob(pattern: string, options?: {
 export declare function compileLiteral(pattern: string): CompiledPattern;
 /** Stable SHA-256 content hash (used for rule-file compile caching). */
 export declare function hashText(text: string): string;
+/**
+ * Compile a CIDR notation string (e.g. `10.0.0.0/8`) into a matcher that
+ * tests whether an IPv4 address falls within the range.
+ *
+ * Returns a pure function `(ip: string) => boolean`. Non-IPv4 inputs always
+ * return false. Invalid CIDR throws at compile time (fail-loud).
+ */
+export declare function compileCidr(cidr: string): (ip: string) => boolean;
+/**
+ * Compile a port specification into a matcher function.
+ *
+ * Accepts:
+ *   - A single port: `"443"` → matches exactly 443
+ *   - A port range: `"8000-9000"` → matches 8000–9000 inclusive
+ *
+ * Returns `(port: number) => boolean`. Invalid specs throw at compile time.
+ */
+export declare function compilePortSpec(spec: string): (port: number) => boolean;
+/**
+ * Compile a domain pattern into a matcher that supports subdomain inclusion.
+ *
+ * - `"github.com"` matches `github.com` AND any subdomain (`api.github.com`)
+ * - `"*.example.com"` matches only subdomains, not `example.com` itself
+ * - Glob characters (`*`, `?`, `[...]`) are handled by {@link compileGlob}.
+ *
+ * Returns a {@link CompiledPattern} whose `.re` is the anchored RegExp.
+ */
+export declare function compileDomainPattern(pattern: string): CompiledPattern;
+/**
+ * Compile a list of patterns (possibly `!`-prefixed) into param matchers.
+ * Returns `{ pattern, negated, compiled }` entries for the params dimension.
+ */
+export declare function compileParamPatterns(patterns: readonly string[], opts?: {
+    maxStars?: number;
+}): Array<{
+    readonly pattern: string;
+    readonly negated: boolean;
+    readonly compiled: CompiledPattern;
+}>;

package/lib/compiler.js

@@ -124,3 +124,109 @@ function escapeRegexChar(ch) {
 export function hashText(text) {
     return createHash('sha256').update(text, 'utf8').digest('hex');
 }
+// ─── Extended matchers for new dimensions ──────────────────────────────────
+/**
+ * Compile a CIDR notation string (e.g. `10.0.0.0/8`) into a matcher that
+ * tests whether an IPv4 address falls within the range.
+ *
+ * Returns a pure function `(ip: string) => boolean`. Non-IPv4 inputs always
+ * return false. Invalid CIDR throws at compile time (fail-loud).
+ */
+export function compileCidr(cidr) {
+    const slash = cidr.indexOf('/');
+    if (slash <= 0 || slash >= cidr.length - 1) {
+        throw new PatternError(`CIDR "${cidr}" must be in address/prefix format`);
+    }
+    const addrStr = cidr.slice(0, slash);
+    const prefixStr = cidr.slice(slash + 1);
+    const prefix = Number.parseInt(prefixStr, 10);
+    if (!Number.isFinite(prefix) || prefix < 0 || prefix > 32) {
+        throw new PatternError(`CIDR "${cidr}" prefix must be 0–32`);
+    }
+    const addr = ipv4ToNumber(addrStr);
+    if (addr === undefined) {
+        throw new PatternError(`CIDR "${cidr}" has invalid IPv4 address`);
+    }
+    const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+    const network = (addr & mask) >>> 0;
+    return (ip) => {
+        const n = ipv4ToNumber(ip);
+        if (n === undefined)
+            return false;
+        return ((n & mask) >>> 0) === network;
+    };
+}
+/** Parse an IPv4 dotted-decimal string to a 32-bit unsigned integer, or undefined. */
+function ipv4ToNumber(addr) {
+    const parts = addr.split('.');
+    if (parts.length !== 4)
+        return undefined;
+    let result = 0;
+    for (const part of parts) {
+        const n = Number.parseInt(part, 10);
+        if (!Number.isFinite(n) || n < 0 || n > 255)
+            return undefined;
+        if (part.length > 1 && part.startsWith('0'))
+            return undefined; // no leading zeros
+        result = (result * 256 + n) >>> 0;
+    }
+    return result;
+}
+/**
+ * Compile a port specification into a matcher function.
+ *
+ * Accepts:
+ *   - A single port: `"443"` → matches exactly 443
+ *   - A port range: `"8000-9000"` → matches 8000–9000 inclusive
+ *
+ * Returns `(port: number) => boolean`. Invalid specs throw at compile time.
+ */
+export function compilePortSpec(spec) {
+    const dash = spec.indexOf('-');
+    if (dash === -1) {
+        const n = Number.parseInt(spec, 10);
+        if (!Number.isFinite(n) || n < 0 || n > 65535) {
+            throw new PatternError(`port "${spec}" must be 0–65535`);
+        }
+        return (port) => port === n;
+    }
+    const lo = Number.parseInt(spec.slice(0, dash), 10);
+    const hi = Number.parseInt(spec.slice(dash + 1), 10);
+    if (!Number.isFinite(lo) || !Number.isFinite(hi) || lo < 0 || hi > 65535 || lo > hi) {
+        throw new PatternError(`port range "${spec}" must be low–high within 0–65535`);
+    }
+    return (port) => port >= lo && port <= hi;
+}
+/**
+ * Compile a domain pattern into a matcher that supports subdomain inclusion.
+ *
+ * - `"github.com"` matches `github.com` AND any subdomain (`api.github.com`)
+ * - `"*.example.com"` matches only subdomains, not `example.com` itself
+ * - Glob characters (`*`, `?`, `[...]`) are handled by {@link compileGlob}.
+ *
+ * Returns a {@link CompiledPattern} whose `.re` is the anchored RegExp.
+ */
+export function compileDomainPattern(pattern) {
+    // If the pattern already contains glob chars, use glob compilation.
+    if (/[*?[\]]/.test(pattern)) {
+        return compileGlob(pattern, { segments: false, maxStars: DEFAULT_MAX_STARS });
+    }
+    // Literal domain: match exactly OR as a parent of a subdomain.
+    // e.g. "github.com" matches "github.com" and "api.github.com"
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`^(?:.*\\.)?${escaped}$`, 'u');
+    return { source: pattern, re };
+}
+/**
+ * Compile a list of patterns (possibly `!`-prefixed) into param matchers.
+ * Returns `{ pattern, negated, compiled }` entries for the params dimension.
+ */
+export function compileParamPatterns(patterns, opts = {}) {
+    const maxStars = opts.maxStars ?? DEFAULT_MAX_STARS;
+    return patterns.map((p) => {
+        if (p.startsWith('!') && p.length > 1) {
+            return { pattern: p, negated: true, compiled: compileGlob(p.slice(1), { segments: false, maxStars }) };
+        }
+        return { pattern: p, negated: false, compiled: compileGlob(p, { segments: false, maxStars }) };
+    });
+}

package/lib/config.d.ts

@@ -100,6 +100,96 @@ export interface PermGateConfig {
      * never widen authority for a destructive or credential-bearing call.
      */
     readonly autoAllowTools?: string[];
+    /**
+     * Session-lifecycle sweep: on startup and hourly, drop the authorization
+     * chain's decision events and pre-change snapshots of sessions DSH has
+     * archived or no longer tracks. Fail-open, best-effort. Default true.
+     */
+    readonly sessionSweep?: boolean;
+    /** Path to DSH's workspace store; defaults to `<dshHome>/storages/workspace.json`. Read-only to the gate. */
+    readonly workspaceStoreFile?: string;
+    /**
+     * Whether to enable multi-file rule chain resolution. When true, the gate
+     * searches up directory ancestors for the rules file. Default false.
+     */
+    readonly searchUp?: boolean;
+    /** Fallback rules file path when no file is found in the chain search. */
+    readonly fallbackPath?: string;
+    /** Error policy for malformed files in the chain: `fail` (throw) or `warn` (skip). Default fail. */
+    readonly badFilePolicy?: 'fail' | 'warn';
+    /** Maximum number of files in the rule chain. Default 10. */
+    readonly maxChainLength?: number;
+    /**
+     * Master network switch. **Default false** — the network proxy is an
+     * opt-in capability, not part of the baseline gate.
+     *
+     * When false: no proxy is started, no environment variables are injected,
+     * and no network interception occurs — zero behavior change from the
+     * pre-network baseline.
+     *
+     * Enable it from the settings card only after verifying it in your
+     * environment. The proxy binds a loopback port and rewrites proxy env
+     * vars for subprocesses, so it must never be enabled implicitly.
+     */
+    readonly networkEnabled?: boolean;
+    /** Network policy mode when auto-mapping from sandbox is not used. Default 'whitelist'. */
+    readonly networkMode?: import('./network.js').NetworkMode;
+    /** How unlisted targets are handled in whitelist mode.
+     *
+     * - `'deny'` — block outright, never prompt.
+     * - `'ask'`  — raise an interactive approval for the attributed shell command;
+     *              approve to let THIS target through for this session.
+     *
+     * A `deny` rule always wins: approval can widen reach for a target no rule
+     * allows, but it can never override a rule that says no.
+     */
+    readonly networkUnlisted?: import('./network.js').UnlistedAction;
+    /**
+     * How traffic with **no shell attribution** is handled. Default `'allow'`.
+     *
+     * A connection that cannot be tied to an in-flight shell execution did not
+     * come from a subprocess this gate manages — it is DSH's own client (a
+     * built-in network tool, the LLM transport). The proxy is a *subprocess*
+     * policy surface, so reviewing the host's own traffic risks the host
+     * blocking itself, which is far worse than a missed block. `'deny'` reviews
+     * it anyway, and would break DSH if a built-in client ever honors the proxy
+     * environment (e.g. Node 24+ with `NODE_USE_ENV_PROXY=1`).
+     */
+    readonly networkUnattributed?: import('./network.js').UnattributedAction;
+    /** Loopback handling: 'allow' short-circuits before rules; 'policy' evaluates normally. Default 'allow'. */
+    readonly networkLoopback?: 'allow' | 'policy';
+    /** Proxy bind address. Default '127.0.0.1'. */
+    readonly networkBind?: string;
+    /** Proxy bind port. Default 0 (ephemeral). */
+    readonly networkPort?: number;
+    /** NO_PROXY handling: 'clear' empties it so policy cannot be bypassed; 'preserve' keeps ambient values. Default 'clear'. */
+    readonly networkNoProxy?: 'clear' | 'preserve';
+    /**
+     * Rewrite `HTTP(S)_PROXY` / `ALL_PROXY` for subprocesses so their traffic
+     * reaches the proxy. Default true.
+     *
+     * Turn it off to run the proxy WITHOUT touching `process.env` — the
+     * listener still adjudicates whatever is explicitly pointed at it, but no
+     * ambient state is rewritten. Useful when the environment is managed
+     * elsewhere or when verifying the proxy in isolation.
+     */
+    readonly networkInjectEnv?: boolean;
+    /**
+     * How long an unlisted-target approval waits for a human before failing
+     * closed to a block (ms). Default 120000 (2 min).
+     */
+    readonly networkAskTimeoutMs?: number;
+    /**
+     * How long one approved network target stays approved for the session (ms).
+     * One shell command routinely opens many connections to the same host, so
+     * without this the human would be prompted once per connection.
+     * Default 1800000 (30 min).
+     */
+    readonly networkGrantTtlMs?: number;
+    /** Enable file watching for rule hot-reload. Default true. */
+    readonly watch?: boolean;
+    /** Debounce interval for rule file changes in ms. Default 300. */
+    readonly watchDebounceMs?: number;
 }
 /** Backend combinable approval strategies for the Permissive tier (all opt-in). */
 export interface PermissiveStrategies {
@@ -128,8 +218,11 @@ export interface PermissiveStrategies {
 }
 export declare const DEFAULT_PERMISSIVE_STRATEGIES: Readonly<PermissiveStrategies>;
 /**
- * Presets in which the gate is active. It owns the `permissive` tier; `'*'`
- * makes it global (every preset, including the hard-deny layer).
+ * Presets in which the gate is active. It owns both 自动审查 tiers — the plain
+ * one (file sandbox kept) and the full-access one (sandbox restriction lifted,
+ * same approval behaviour) — so a user can have the gate without inheriting a
+ * sandbox that breaks `git` / Cygwin tools. `'*'` makes it global (every
+ * preset, including the hard-deny layer).
  */
 export declare const DEFAULT_GATE_PRESETS: readonly string[];
 /** Normalize the gate scope: an unset/empty list means the default. */

package/lib/config.js

@@ -43,10 +43,13 @@ export const DEFAULT_PERMISSIVE_STRATEGIES = {
     trustEscalation: true,
 };
 /**
- * Presets in which the gate is active. It owns the `permissive` tier; `'*'`
- * makes it global (every preset, including the hard-deny layer).
+ * Presets in which the gate is active. It owns both 自动审查 tiers — the plain
+ * one (file sandbox kept) and the full-access one (sandbox restriction lifted,
+ * same approval behaviour) — so a user can have the gate without inheriting a
+ * sandbox that breaks `git` / Cygwin tools. `'*'` makes it global (every
+ * preset, including the hard-deny layer).
  */
-export const DEFAULT_GATE_PRESETS = ['permissive'];
+export const DEFAULT_GATE_PRESETS = ['permissive', 'permissive-full'];
 /** Normalize the gate scope: an unset/empty list means the default. */
 export function resolveGatePresets(configured) {
     if (configured === undefined || configured.length === 0)
@@ -92,6 +95,28 @@ export const Config = z.object({
     allowlist: z.array(z.string()),
     denyKeywords: z.array(z.string()),
     autoAllowTools: z.array(z.string()),
+    sessionSweep: z.boolean().default(true),
+    workspaceStoreFile: z.string(),
+    // Rule chain (T1.9)
+    searchUp: z.boolean().default(false),
+    fallbackPath: z.string(),
+    badFilePolicy: z.union(['fail', 'warn']).default('fail'),
+    maxChainLength: z.number().min(1).max(50).default(10),
+    // Network (Phase 2)
+    networkEnabled: z.boolean().default(false),
+    networkMode: z.union(['deny-all', 'whitelist', 'allow-all']).default('whitelist'),
+    networkUnlisted: z.union(['ask', 'deny']).default('ask'),
+    networkUnattributed: z.union(['allow', 'deny']).default('allow'),
+    networkLoopback: z.union(['allow', 'policy']).default('allow'),
+    networkBind: z.string().default('127.0.0.1'),
+    networkPort: z.number().min(0).max(65535).default(0),
+    networkNoProxy: z.union(['clear', 'preserve']).default('clear'),
+    networkInjectEnv: z.boolean().default(true),
+    networkAskTimeoutMs: z.number().min(1000).max(600_000).default(120_000),
+    networkGrantTtlMs: z.number().min(0).max(24 * 60 * 60_000).default(30 * 60_000),
+    // Hot reload (Phase 3)
+    watch: z.boolean().default(true),
+    watchDebounceMs: z.number().min(50).max(5000).default(300),
 });
 export function resolveConfig(config = {}) {
     const parsed = Config(config);

package/lib/engine.js

@@ -19,8 +19,13 @@ const DESTRUCTIVE_TOOL = /(?:^|[_-])(?:delete|remove|rm|destroy|erase|purge|wipe
  */
 const READ_TOOLS = new Set([
     'read', 'read_image', 'grep', 'glob', 'ls', 'lsp',
-    // Read-only network / media queries: no write, no exec.
+    // Search / lookup: every one of these only READS. `web_search` and
+    // `modlens_read_image` also reach the network, but through DSH's own client
+    // rather than a subprocess — see the network note below.
     'web_search', 'modlens_read_image',
+    'advanced_search', 'platform_search', 'free_search_test',
+    // Session-scoped reads: they disclose already-recorded state, never mutate.
+    'context_compression_retrieve', 'memory_search_graph', 'memory_expand_graph_node',
 ]);
 /** DSH internal coordination / management tools — not workspace-modifying. */
 const INTERNAL_TOOLS = new Set([
@@ -31,9 +36,11 @@ const INTERNAL_TOOLS = new Set([
     'agent_teams_approve', 'agent_teams_resume',
     // AgentTeams status reads
     'agent_teams_status', 'agent_teams_update_task',
-    // DSH session/memory/goal/taskboard management
+    // DSH session/memory/goal/taskboard management. The memory store is the
+    // agent's own state, not the workspace: writing it is not a workspace write.
     'conversation_search',
     'memory_add', 'memory_delete', 'memory_read_scene', 'memory_search',
+    'memory_import', 'memory_ruminate', 'memory_ruminate_cancel', 'memory_ruminate_status',
     'get_goal', 'update_goal', 'create_goal',
     'taskboard_get', 'taskboard_list', 'taskboard_claim', 'taskboard_block',
     'taskboard_comment', 'taskboard_release_claim', 'taskboard_submit_review',

package/lib/evaluate.d.ts

@@ -9,6 +9,15 @@ export interface ToolCallContext {
     readonly home?: string;
     readonly dshHome?: string;
     readonly caseInsensitive?: boolean;
+    /** Agent identity candidates from session context. */
+    readonly agentCandidates?: readonly string[];
+    /** Network request info (for network dimension matching). */
+    readonly network?: {
+        readonly domain?: string;
+        readonly ip?: string;
+        readonly port?: number;
+        readonly scheme?: string;
+    };
 }
 export interface Decision {
     readonly action: RuleAction;

package/lib/evaluate.js

@@ -6,6 +6,7 @@
 import { normalizeWorkspacePath } from './path.js';
 import { extractPathCandidates, extractUrlCandidates, } from './rule.js';
 import { decomposeShellCommand, isForceDeletion, isRecursiveDeletion } from './shell.js';
+import { compileCidr, compilePortSpec, compileDomainPattern } from './compiler.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
@@ -64,6 +65,46 @@ export function ruleMatches(rule, ctx, commands, pathCands, urlCands) {
         if (!rel.some((p) => rule.paths.some((g) => g.re.test(p))))
             return false;
     }
+    // ─── New dimensions ────────────────────────────────────────────────────
+    // params dimension: AND over keys; each key's value must match at least one pattern (OR).
+    if (rule.params.length > 0) {
+        if (!matchParams(rule.params, ctx.args))
+            return false;
+    }
+    // absent dimension: all listed keys must be absent from args.
+    if (rule.absent.length > 0) {
+        for (const key of rule.absent) {
+            if (key in ctx.args)
+                return false;
+        }
+    }
+    // agents dimension: at least one candidate must match an entry.
+    if (rule.agents.length > 0) {
+        const candidates = ctx.agentCandidates ?? [];
+        if (candidates.length === 0)
+            return false; // fail-closed
+        if (!candidates.some((c) => rule.agents.some((a) => a === c || matchAgentPattern(a, c))))
+            return false;
+    }
+    // when dimension: all conditions must be satisfied.
+    if (rule.when !== undefined) {
+        if (!matchWhen(rule.when))
+            return false;
+    }
+    // argv dimension: pipeline patterns.
+    if (rule.argv?.pipeline !== undefined && rule.argv.pipeline.length > 0) {
+        if (commands.length === 0)
+            return false;
+        const pipelineText = commands.map((c) => c.command).join('|');
+        const compiled = rule.argv.pipeline.map((p) => compileGlobForMatch(p));
+        if (!compiled.some((g) => g.test(pipelineText)))
+            return false;
+    }
+    // network dimension: all present sub-dimensions must match.
+    if (rule.network !== undefined) {
+        if (!matchNetwork(rule.network, ctx.network))
+            return false;
+    }
     return true;
 }
 const WRITE_TOOLS = new Set(['write', 'edit']);
@@ -182,3 +223,151 @@ function decomposeSafe(text) {
         return [];
     }
 }
+// ─── New dimension matchers ────────────────────────────────────────────────
+/** Import compileGlob locally to avoid circular dependency with compiler.ts. */
+import { compileGlob } from './compiler.js';
+/** Compile a glob pattern to a RegExp for ad-hoc matching. */
+function compileGlobForMatch(pattern) {
+    return compileGlob(pattern, { segments: false }).re;
+}
+/**
+ * Match the params dimension: AND over keys, OR within each key's patterns.
+ * A negated pattern means the value must NOT match.
+ */
+function matchParams(params, args) {
+    for (const cond of params) {
+        const value = resolveNestedKey(args, cond.key);
+        if (cond.patterns.length === 0) {
+            // No patterns → key must exist (any value).
+            if (value === undefined)
+                return false;
+            continue;
+        }
+        if (value === undefined)
+            return false;
+        const strValue = typeof value === 'string' ? value : JSON.stringify(value);
+        const compiled = cond.patterns.map((p) => {
+            if (p.startsWith('!') && p.length > 1) {
+                return { negated: true, re: compileGlobForMatch(p.slice(1)) };
+            }
+            return { negated: false, re: compileGlobForMatch(p) };
+        });
+        if (cond.negated) {
+            // Negated: value must NOT match the sole pattern.
+            if (compiled[0].re.test(strValue))
+                return false;
+        }
+        else {
+            // Normal: value must match at least one pattern (OR).
+            if (!compiled.some((c) => !c.negated && c.re.test(strValue)))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Resolve a dotted key path from a nested object.
+ * e.g. `resolveNestedKey({flags: {mode: 'prod'}}, 'flags.mode')` → `'prod'`
+ */
+function resolveNestedKey(obj, key) {
+    const parts = key.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Match an agent pattern against an identity candidate.
+ * Supports exact match and glob patterns.
+ */
+function matchAgentPattern(pattern, candidate) {
+    if (pattern === candidate)
+        return true;
+    // Glob patterns: compile and test.
+    if (/[*?[\]]/.test(pattern)) {
+        return compileGlobForMatch(pattern).test(candidate);
+    }
+    return false;
+}
+/**
+ * Match the when dimension: all conditions must be satisfied.
+ */
+function matchWhen(when) {
+    // Platform check.
+    if (when.platform !== undefined && when.platform.length > 0) {
+        if (!when.platform.includes(process.platform))
+            return false;
+    }
+    // Env var checks.
+    if (when.env !== undefined) {
+        for (const [varName, allowed] of Object.entries(when.env)) {
+            const actual = process.env[varName];
+            if (actual === undefined)
+                return false;
+            if (!allowed.includes(actual))
+                return false;
+        }
+    }
+    // Node version (reserved — skip for now).
+    return true;
+}
+/**
+ * Match the network dimension: all present sub-dimensions must match.
+ * Within a sub-dimension, entries are OR.
+ */
+function matchNetwork(network, ctx) {
+    if (ctx === undefined)
+        return false;
+    // domains
+    if (network.domains !== undefined && network.domains.length > 0) {
+        if (ctx.domain === undefined)
+            return false;
+        const matchers = network.domains.map((d) => compileDomainPattern(d));
+        if (!matchers.some((m) => m.re.test(ctx.domain)))
+            return false;
+    }
+    // ips
+    if (network.ips !== undefined && network.ips.length > 0) {
+        if (ctx.ip === undefined)
+            return false;
+        const isCidr = (s) => s.includes('/');
+        const cidrs = network.ips.filter(isCidr);
+        const literals = network.ips.filter((s) => !isCidr(s));
+        const ipMatch = literals.includes(ctx.ip) || cidrs.some((c) => {
+            try {
+                return compileCidr(c)(ctx.ip);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!ipMatch)
+            return false;
+    }
+    // ports
+    if (network.ports !== undefined && network.ports.length > 0) {
+        if (ctx.port === undefined)
+            return false;
+        const matchers = network.ports.map((p) => {
+            try {
+                return compilePortSpec(p);
+            }
+            catch {
+                return (_) => false;
+            }
+        });
+        if (!matchers.some((m) => m(ctx.port)))
+            return false;
+    }
+    // schemes
+    if (network.schemes !== undefined && network.schemes.length > 0) {
+        if (ctx.scheme === undefined)
+            return false;
+        if (!network.schemes.includes(ctx.scheme))
+            return false;
+    }
+    return true;
+}

package/lib/events.d.ts

@@ -127,6 +127,7 @@ export interface WebServerLike {
 export declare const EVENTS_ROUTE = "/api/dsh-perm-gate/events";
 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";
 export declare const RECEIVER_ROUTE = "/api/dsh-perm-gate/receiver";
 export declare const DIFF_ROUTE = "/api/dsh-perm-gate/diff";
 export declare const REVERT_ROUTE = "/api/dsh-perm-gate/revert";
@@ -177,6 +178,18 @@ export declare function registerHealthRoute(server: unknown, provider: {
         detail: string;
     }>;
 }): (() => void) | undefined;
+/** The network-state face the settings UI's network section needs. */
+export interface NetworkRouteProvider {
+    snapshot(): unknown;
+}
+/**
+ * Register the network diagnostics route: `GET /api/dsh-perm-gate/network`
+ * returns the live network state (mode, bind, port, proxy liveness, env
+ * injection, block counters, recent blocks). Read-only — a policy change goes
+ * through the settings namespace, never through HTTP.
+ * Returns whether the route was registered.
+ */
+export declare function registerNetworkRoute(server: unknown, provider: NetworkRouteProvider): (() => void) | undefined;
 /** The learning-store face the settings UI's sediment view needs. */
 export interface LearningRouteProvider {
     snapshot(): unknown;

package/lib/events.js

@@ -351,6 +351,7 @@ function readBody(req, limit = 1024 * 1024) {
 export const EVENTS_ROUTE = '/api/dsh-perm-gate/events';
 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';
 export const RECEIVER_ROUTE = '/api/dsh-perm-gate/receiver';
 export const DIFF_ROUTE = '/api/dsh-perm-gate/diff';
 export const REVERT_ROUTE = '/api/dsh-perm-gate/revert';
@@ -651,6 +652,36 @@ export function registerHealthRoute(server, provider) {
         },
     });
 }
+/**
+ * Register the network diagnostics route: `GET /api/dsh-perm-gate/network`
+ * returns the live network state (mode, bind, port, proxy liveness, env
+ * injection, block counters, recent blocks). Read-only — a policy change goes
+ * through the settings namespace, never through HTTP.
+ * Returns whether the route was registered.
+ */
+export function registerNetworkRoute(server, provider) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: NETWORK_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'GET' && req.method !== 'HEAD') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            try {
+                json(res, 200, { ok: true, ...provider.snapshot() });
+            }
+            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,

package/lib/index.d.ts

@@ -53,5 +53,5 @@ export declare function makeApprovalAnswerer(runtime: Pick<PermGateRuntime, 'set
  * `riskTimeoutMs` (default 20 s), and a grader failure keeps the original ask
  * (fail-closed).
  */
-export declare function makePreExecuteListener(runtime: Pick<PermGateRuntime, 'decideExecution' | 'refineAsk'>): (exec: ToolExecutionLike, next: () => Promise<unknown>) => Promise<unknown>;
+export declare function makePreExecuteListener(runtime: Pick<PermGateRuntime, 'decideExecution' | 'refineAsk' | 'beginShellExecution'>): (exec: ToolExecutionLike, next: () => Promise<unknown>) => Promise<unknown>;
 export declare function apply(ctx: Context, config?: Record<string, unknown>): PermGateRuntime;