dsh-perm-gate 2.1.0 → 3.0.0

package/lib/index.js

@@ -1,8 +1,16 @@
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { Config, resolveDataDir, resolveGatePresets, resolvePermissiveStrategies, resolveRulesFile } from './config.js';
-import { registerEventsRoute, registerHealthRoute, registerLearningRoute, registerReceiverRoute, registerReviewRoutes } from './events.js';
+import { parse } from 'yaml';
+import { Config, RULES_NAMESPACE, RulesSchema, isRulesConfigured, readRulesFromSettings, resolveDshHome, resolveDataDir, resolveGatePresets, resolvePermissiveStrategies, resolveRulesFile } from './config.js';
+import { appendAllowToSettings, replaceAllowInSettings } from './allowlist.js';
+import { runDryRun } from './dry-run.js';
+import { registerDryRunRoute, registerEventsRoute, registerHealthRoute, registerLearningRoute, registerNetworkRoute, registerReceiverRoute, registerReviewRoutes, registerRulesRoute } from './events.js';
 import { buildReceiverInfo } from './receiver-info.js';
+import { readRulesView, readRulesViewFromSettings } from './rules-view.js';
 import { PermGateRuntime } from './runtime.js';
+import { classifySessions, sweepSessionData } from './session-sweep.js';
+import { decideNetworkTarget } from './network.js';
+import { NetworkLifecycle } from './network-lifecycle.js';
 export const name = 'dsh-perm-gate';
 /**
  * The `tools` service drives `tools/pre-execute`/`tools/result` (dsh-tools).
@@ -13,6 +21,8 @@ export const name = 'dsh-perm-gate';
  */
 export const inject = ['tools', 'webServer', 'llm', 'agentDefaultModel'];
 export { Config };
+/** The closed approval-outcome vocabulary (anything else is normalized to `unavailable`). */
+const APPROVAL_OUTCOMES = new Set(['allowed-once', 'rejected', 'cancelled', 'unavailable']);
 /** Runtime settings namespace: `permissive` + `permissiveStrategies` (editable in the UI). */
 export const PERMISSIVE_NAMESPACE = 'dsh-perm-gate';
 /**
@@ -137,10 +147,14 @@ export function makePreExecuteListener(runtime) {
     return async (exec, next) => {
         const decision = runtime.decideExecution(exec);
         // Passthrough (allow / stand-down) and a hard-deny need no grading.
-        if (decision === undefined)
+        if (decision === undefined) {
+            // The call proceeds: register it so a network connection made by its
+            // child process can be attributed back to this session.
+            runtime.beginShellExecution(exec);
             return next();
+        }
         if (decision.kind !== 'ask')
-            return decision;
+            return decision; // deny: it never runs
         // A cancelled call is never worth a model round-trip; the registry rechecks
         // cancellation after this gate settles.
         if (exec.signal?.aborted === true)
@@ -152,7 +166,15 @@ export function makePreExecuteListener(runtime) {
         catch {
             return decision; // fail-closed: keep the human ask
         }
-        return refined ?? next();
+        if (refined === undefined) {
+            runtime.beginShellExecution(exec);
+            return next();
+        }
+        // Still an ask: the human decides. Register optimistically so a call they
+        // approve is attributable; a rejection is dropped by the abort/settle path.
+        if (refined.kind === 'ask')
+            runtime.beginShellExecution(exec);
+        return refined;
     };
 }
 export function apply(ctx, config = {}) {
@@ -163,6 +185,37 @@ export function apply(ctx, config = {}) {
     // read-only). The default resolves to `$DSH_HOME` / `~/.dsh`, so a profile
     // entry that omits `config` still records events, snapshots and learning.
     const dataDir = resolveDataDir(typeof config.dshHome === 'string' ? config.dshHome : undefined);
+    // ─── Rules sources (dual-source: settings first, rulesFile fallback) ──
+    // The `dsh-perm-gate-rules` settings namespace is the primary rules store —
+    // the framework owns it, so the gate loads with no rules file on disk. A
+    // namespace still at bare defaults never shadows the file, and the first
+    // settings write seeds the file document along (implicit migration). Both
+    // references are filled in by the settings registration below; until then
+    // the file paths run exactly as before.
+    const rulesFilePath = resolveRulesFile(typeof config.rulesFile === 'string' ? config.rulesFile : undefined, dataDir);
+    let rulesFromSettings = () => ({});
+    const rulesScopeRef = { scope: undefined };
+    /** The raw file document, for seeding the namespace on its first write. */
+    const fileSeedDoc = () => {
+        try {
+            const text = readFileSync(rulesFilePath, 'utf8');
+            if (text.trim() === '')
+                return undefined;
+            return parse(text);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const settingsWrite = (write, fallback) => {
+        const scope = rulesScopeRef.scope;
+        if (scope === undefined)
+            return fallback();
+        void write(scope, fileSeedDoc()).catch((e) => {
+            console.warn('[dsh-perm-gate] settings rules write failed:', e);
+        });
+        return true;
+    };
     // Host model-group services (typed minimally; supplied by the dsh runtime
     // through the loader `inject` — dsh-approval-gate demonstrates the same
     // contract). The llm service backs the `host` receiver; agentDefaultModel
@@ -181,6 +234,28 @@ export function apply(ctx, config = {}) {
         ? llmService
         : undefined;
     const hostModelService = injected.agentDefaultModel ?? fallbackGet('agentDefaultModel');
+    // Host log channel, probed rather than assumed: cordis exposes `ctx.logger`,
+    // but the shape moved between DSH lines. Falls back to console so a warning
+    // is never silently dropped — and never throws, because these calls happen
+    // inside error handlers where a throw would escalate into a host crash.
+    const ctxLogger = (() => {
+        const candidate = ctx.logger;
+        if (candidate !== null && typeof candidate === 'object' && typeof candidate.warn === 'function') {
+            return candidate;
+        }
+        return undefined;
+    })();
+    const loggerWarn = (message) => {
+        try {
+            if (ctxLogger !== undefined)
+                ctxLogger.warn(message);
+            else
+                console.warn(message);
+        }
+        catch {
+            // A throwing logger must never become an unhandled error.
+        }
+    };
     // The live approval service, captured by the optional inject below. Its
     // `effectivePolicy` tells the gate whether an ask can reach a human at all.
     //
@@ -196,6 +271,32 @@ export function apply(ctx, config = {}) {
     const runtime = new PermGateRuntime({
         ...config,
         hostLlm,
+        // Raise a network approval through the DSH approval seam. The service
+        // applies the session policy, routes the prompt to the agent, and appends
+        // the `approval/asked`/`approval/decided` audit pair. Everything that is
+        // not an explicit `allowed-once` fails closed to `unavailable`, and the
+        // gate turns that into a block.
+        requestApproval: async (req) => {
+            const svc = approvalService;
+            if (svc === undefined || typeof svc.request !== 'function')
+                return 'unavailable';
+            try {
+                const outcome = await svc.request({
+                    agent: req.agent,
+                    toolName: req.toolName,
+                    ...(req.callId !== undefined ? { callId: req.callId } : {}),
+                    reason: req.reason,
+                    ...(req.signal !== undefined ? { signal: req.signal } : {}),
+                });
+                return APPROVAL_OUTCOMES.has(String(outcome))
+                    ? outcome
+                    : 'unavailable';
+            }
+            catch {
+                // No open turn, a missing answerer, or a seam failure: never an allow.
+                return 'unavailable';
+            }
+        },
         // Read the Permissive tier live so the UI card's switches take effect on
         // the next tool call (no reload). Falls back to the composition entry.
         readPermissive: () => {
@@ -255,8 +356,19 @@ export function apply(ctx, config = {}) {
             : join(dataDir, 'learning.json'),
         // The rules document lives in the plugin's data dir by default, so a
         // `$DSH_HOME/perm-gate/rules.yml` the user writes is actually loaded without
-        // also having to declare `rulesFile` in the composition entry.
-        rulesFile: resolveRulesFile(typeof config.rulesFile === 'string' ? config.rulesFile : undefined, dataDir),
+        // also having to declare `rulesFile` in the composition entry. It is the
+        // FALLBACK source: a configured `dsh-perm-gate-rules` namespace wins.
+        rulesFile: rulesFilePath,
+        // Settings-first rules: the live `dsh-perm-gate-rules` document when the
+        // namespace carries a real configuration, else undefined (file fallback).
+        readRulesDocument: () => readRulesFromSettings({ get: () => rulesFromSettings() }),
+        // Settings-backed allowlist writes; a falsy verdict (settings service
+        // absent) makes the runtime fall back to its own rules-file paths, and the
+        // namespace's watch triggers the reload once a write lands.
+        allowlistWriter: {
+            append: (pattern, reason) => settingsWrite((scope, seed) => appendAllowToSettings(scope, pattern, reason, seed), () => false),
+            replace: (patterns, reason) => settingsWrite((scope, seed) => replaceAllowInSettings(scope, patterns, reason, seed), () => false),
+        },
         // The whole gate is scoped to the presets that opt into it (default: the
         // `permissive` tier this plugin adds); elsewhere it stands down entirely.
         gatePresets: resolveGatePresets(Array.isArray(config.gatePresets) ? config.gatePresets : undefined),
@@ -290,29 +402,109 @@ export function apply(ctx, config = {}) {
             ? config.snapshotsDir
             : join(dataDir, 'snapshots'),
     });
+    // Session-lifecycle sweep: on startup and hourly, classify every session the
+    // gate holds data for against DSH's workspace store, and drop the
+    // authorization-chain data (decision events + pre-change snapshots) of
+    // sessions that were archived or no longer exist. The store is read-only
+    // here and every failure is fail-open (a skipped round retries in an hour);
+    // the timers are unref'd so cleanup never holds the process open.
+    if (config.sessionSweep !== false) {
+        const storeFile = typeof config.workspaceStoreFile === 'string' && config.workspaceStoreFile !== ''
+            ? config.workspaceStoreFile
+            : join(resolveDshHome(typeof config.dshHome === 'string' ? config.dshHome : undefined), 'storages', 'workspace.json');
+        const sweepEventsFile = typeof config.eventsFile === 'string' && config.eventsFile !== ''
+            ? config.eventsFile
+            : join(dataDir, 'events.jsonl');
+        const sweepSnapshotsDir = typeof config.snapshotsDir === 'string' && config.snapshotsDir !== ''
+            ? config.snapshotsDir
+            : join(dataDir, 'snapshots');
+        const sweepOnce = () => {
+            try {
+                const cls = classifySessions(readFileSync(storeFile, 'utf8'));
+                if (cls === null)
+                    return; // torn read / format change — retry next round
+                sweepSessionData({ classification: cls, eventsFile: sweepEventsFile, snapshotsDir: sweepSnapshotsDir });
+            }
+            catch (e) {
+                console.warn('[dsh-perm-gate] session sweep skipped:', e instanceof Error ? e.message : e);
+            }
+        };
+        const first = setTimeout(sweepOnce, 0);
+        const hourly = setInterval(sweepOnce, 60 * 60 * 1000);
+        hourly.unref?.();
+        ctx.effect(() => () => {
+            clearTimeout(first);
+            clearInterval(hourly);
+        }, 'dsh-perm-gate: session sweep');
+    }
+    /**
+     * The network-relevant slice of a settings surface, as a comparison key.
+     * Used to decide whether a settings edit needs a proxy rebind at all — an
+     * unrelated edit (say, the allowlist) must not close and reopen the proxy.
+     */
+    const networkKeyOf = (source) => {
+        const s = (source ?? {});
+        return JSON.stringify([
+            s.networkEnabled, s.networkMode, s.networkUnlisted, s.networkLoopback,
+            s.networkBind, s.networkPort, s.networkNoProxy, s.networkInjectEnv,
+        ]);
+    };
+    // Forward references, resolved during apply before any UI edit can fire:
+    // the settings watch only ever runs on a later user action. Held in an
+    // object so the mutable slots stay lint-clean and the intent is explicit.
+    const networkRefs = {};
     installSettingsSection(ctx, PERMISSIVE_NAMESPACE, Config, config, {
         setSource: (source) => {
             current = source;
         },
         onChange: () => { },
         onScope: (scope) => {
-            // Seed the editable whitelist from the rules file only when the namespace
-            // carries no override yet, so the card shows the current allow patterns.
+            // Seed the editable whitelist from the rules source only when the
+            // namespace carries no override yet, so the card shows the current allow
+            // patterns.
             const surface = asSurface(scope.get());
             if (surface !== undefined && !Array.isArray(surface.allowlist)) {
                 const patterns = runtime.allowlist();
                 if (patterns.length > 0)
                     void scope.update({ allowlist: patterns.slice() });
             }
-            // Card edits -> namespace -> rulesFile (mirror + reload).
+            // Card edits -> namespace -> rules source (settings via the runtime's
+            // writer, else the rules file mirror) + reload.
             scope.watch(() => {
                 const next = asSurface(scope.get());
                 if (next !== undefined && Array.isArray(next.allowlist)) {
                     runtime.setAllowlist(next.allowlist.filter((x) => typeof x === 'string'));
                 }
+                // A network knob changed: re-mount the proxy so the card's switches
+                // take effect without a plugin reload. Only a rebind-relevant edit
+                // triggers it.
+                const key = networkKeyOf(next);
+                if (networkRefs.appliedKey !== undefined && networkRefs.appliedKey !== key) {
+                    networkRefs.appliedKey = key;
+                    networkRefs.rebind?.();
+                }
+                else if (networkRefs.appliedKey === undefined) {
+                    networkRefs.appliedKey = key;
+                }
             });
         },
     });
+    // The rules namespace: the primary rules store (JSON twin of rules.yml).
+    // Every change recompiles the gate — the settings half of the hot reload
+    // that used to be a chokidar file watcher. `onScope` hands the live scope to
+    // the allowlist writers above; the seed entry is `{}`, so an untouched
+    // namespace reads as "not configured" and the file paths stay in force.
+    installSettingsSection(ctx, RULES_NAMESPACE, RulesSchema, {}, {
+        setSource: (source) => {
+            rulesFromSettings = source;
+        },
+        onChange: () => {
+            runtime.reload();
+        },
+        onScope: (scope) => {
+            rulesScopeRef.scope = scope;
+        },
+    });
     // Event feed HTTP API (best effort): the dsh webServer service exposes the
     // JSONL decision events to the browser half; without it events stay on disk.
     try {
@@ -352,6 +544,43 @@ export function apply(ctx, config = {}) {
             const offHealth = registerHealthRoute(webServer, { check: () => runtime.healthCheck() });
             if (offHealth !== undefined)
                 ctx.effect(() => () => { offHealth(); }, 'dsh-perm-gate: health route');
+            // Network diagnostics: mode, bind, port, proxy liveness, env injection,
+            // block counters and recent blocks. Read-only.
+            const offNetwork = registerNetworkRoute(webServer, {
+                snapshot: () => networkRefs.snapshot?.() ?? { enabled: false, proxyActive: false },
+            });
+            if (offNetwork !== undefined)
+                ctx.effect(() => () => { offNetwork(); }, 'dsh-perm-gate: network route');
+            // Rule test (dry-run): evaluate one would-be call against the ruleset the
+            // gate currently has loaded, and report both the effective verdict and the
+            // rule layer's own answer. Read-only — the route has no write form, so
+            // testing a rule can never change it. It runs against the LIVE runtime
+            // rather than a fresh one so the panel tests the rules in force, not a
+            // re-derivation of them (a fresh runtime would also re-resolve the chain
+            // from a different root and could silently answer about a different file).
+            const offDryRun = registerDryRunRoute(webServer, {
+                run: (request) => runDryRun({
+                    tool: request.tool,
+                    args: request.args,
+                    ...(request.permissive !== undefined ? { permissive: request.permissive } : {}),
+                }, runtime),
+            });
+            if (offDryRun !== undefined)
+                ctx.effect(() => () => { offDryRun(); }, 'dsh-perm-gate: dry-run route');
+            // Permissions view: the document the gate is actually loading, shown so
+            // the panel is never editing rules it cannot display. Read-only, and
+            // resolved exactly as the gate resolves it — settings first, the file the
+            // fallback resolves to otherwise.
+            const offRules = registerRulesRoute(webServer, {
+                view: () => {
+                    const doc = rulesFromSettings();
+                    if (isRulesConfigured(doc))
+                        return readRulesViewFromSettings(doc);
+                    return readRulesView(rulesFilePath);
+                },
+            });
+            if (offRules !== undefined)
+                ctx.effect(() => () => { offRules(); }, 'dsh-perm-gate: rules route');
             // Receiver projection for the settings card (provider/model catalog is
             // potentially slow to enumerate — cached briefly).
             let receiverCache = null;
@@ -398,7 +627,12 @@ export function apply(ctx, config = {}) {
     // Fallback terminal-answer channel: settle the ask from the call's result,
     // and settle a pending learning candidate (a result for one means the human
     // approved it and it executed — one confirmation).
-    host.on('tools/result', ((exec, result) => { runtime.settleExecution(exec, result); }));
+    host.on('tools/result', ((exec, result) => {
+        // The call settled: it is no longer in flight, so a later connection must
+        // not be attributed to it.
+        runtime.endShellExecution(exec);
+        runtime.settleExecution(exec, result);
+    }));
     // Approval channel: answer an escalation the gate already cleared, and settle
     // the outcome of an ask the gate did raise. Registered `prepend` so it sits at
     // the head of the `approval/request` waterfall, ahead of the remote bridge that
@@ -422,5 +656,80 @@ export function apply(ctx, config = {}) {
             approvalService = undefined;
         }, 'dsh-perm-gate: approval answerer');
     });
+    // ─── Network proxy (Phase 2, T2.12 + rebind) ────────────────────────
+    // T2.10 escape hatch: default OFF. The network proxy is opt-in — enabling
+    // it binds a loopback port and rewrites proxy env vars, so it must never
+    // be turned on implicitly.
+    //
+    // The lifecycle lives in NetworkLifecycle: one persistent teardown effect,
+    // serialized (re)binds, and a diagnostics snapshot. A settings change calls
+    // rebind(), so the card's switches take effect without a plugin reload.
+    const readNetworkConfig = () => {
+        const live = current();
+        const str = (key, fallback) => typeof live[key] === 'string' && live[key] !== '' ? live[key] : fallback;
+        const num = (key, fallback) => typeof live[key] === 'number' ? live[key] : fallback;
+        const bool = (key, fallback) => typeof live[key] === 'boolean' ? live[key] : fallback;
+        return {
+            enabled: bool('networkEnabled', false),
+            mode: str('networkMode', 'whitelist'),
+            unlisted: str('networkUnlisted', 'ask'),
+            unattributed: str('networkUnattributed', 'allow'),
+            loopback: str('networkLoopback', 'allow'),
+            bind: str('networkBind', '127.0.0.1'),
+            port: num('networkPort', 0),
+            noProxy: str('networkNoProxy', 'clear'),
+            injectEnv: bool('networkInjectEnv', true),
+            askTimeoutMs: num('networkAskTimeoutMs', 120_000),
+        };
+    };
+    const networkLogger = ctxLogger !== undefined ? ctxLogger : { warn: (msg) => console.warn(msg) };
+    const networkLifecycle = new NetworkLifecycle({
+        effect: (disposeFactory, label) => { ctx.effect(disposeFactory, label); },
+        readConfig: readNetworkConfig,
+        decide: (target) => {
+            const cfg = readNetworkConfig();
+            return decideNetworkTarget(runtime.compiledRuleset, target, {
+                mode: cfg.mode,
+                unlisted: cfg.unlisted,
+                loopback: cfg.loopback,
+                // Attribution decides whether this connection is a shell subprocess
+                // (the gate's business) or DSH's own client (left alone by default).
+                attributed: runtime.currentAttribution() !== undefined,
+                unattributed: cfg.unattributed,
+            });
+        },
+        attribution: () => runtime.currentAttribution(),
+        // An `ask` verdict escalates to the interactive approval seam, raised on
+        // behalf of the shell command that opened the connection. A `deny` verdict
+        // never reaches here — approval widens reach but cannot override a rule.
+        escalate: async (target, decision) => {
+            const where = `${target.scheme ?? 'https'}://${target.host}${target.port !== undefined ? `:${target.port}` : ''}`;
+            const why = decision.matched && decision.ruleIndex !== undefined
+                ? `rule #${decision.ruleIndex + 1} asks about it`
+                : `${decision.mode} mode has no allow rule for it`;
+            return runtime.askNetwork(target, `a shell subprocess wants to reach ${where} — ${why}. Approve to let this command use the network for this target.`, readNetworkConfig().askTimeoutMs);
+        },
+        logger: networkLogger,
+    });
+    // Never awaited at apply(): a slow or failing bind must not block plugin
+    // load. attach() degrades to "no proxy" internally.
+    void networkLifecycle.attach().catch((error) => {
+        loggerWarn(`[dsh-perm-gate] network proxy attach failed: ${String(error)}`);
+    });
+    // Resolve the forward reference and seed the change-detection key from the
+    // config actually applied, so the first UI edit is compared against it.
+    networkRefs.rebind = () => {
+        void networkLifecycle.rebind().catch((error) => {
+            loggerWarn(`[dsh-perm-gate] network proxy rebind failed: ${String(error)}`);
+        });
+    };
+    networkRefs.snapshot = () => networkLifecycle.snapshot();
+    if (networkRefs.appliedKey === undefined)
+        networkRefs.appliedKey = networkKeyOf(current());
+    // ─── Rule hot reload ────────────────────────────────────────────────
+    // The file watcher (chokidar) is gone: the settings namespace is the primary
+    // rules store and its `scope.watch` recompiles the gate on every change
+    // (see the RULES_NAMESPACE registration above). A rules FILE edit is no
+    // longer picked up mid-session — the settings document is the source to edit.
     return runtime;
 }

package/lib/network-lifecycle.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Network proxy lifecycle for dsh-perm-gate.
+ *
+ * Owns the proxy + the subprocess environment injection and exposes the
+ * three operations the host needs:
+ *
+ *   attach()   — mount per the current config (called once at apply)
+ *   rebind()   — re-read the config and re-mount (called on a settings change)
+ *   detach()   — close the proxy and restore the environment
+ *
+ * Keeping this out of `index.ts` matters: the proxy has a real lifecycle
+ * (bind, env rewrite, teardown) and every step must be owned by exactly one
+ * disposer. `index.ts` only wires it.
+ *
+ * Robustness contract:
+ * - One persistent teardown effect is registered at construction, so a
+ *   dispose that races an in-flight bind still closes the proxy and restores
+ *   the environment.
+ * - Mutating operations are serialized: rapid settings toggles cannot
+ *   interleave attach/detach and leave an orphaned listener or a rewritten
+ *   `process.env`.
+ * - Nothing here throws into the host: failures degrade to "no proxy" and
+ *   surface through the optional logger.
+ */
+import { type NetworkBlockRecord, type ProxyAttribution } from './proxy.js';
+import type { NetworkDecision, NetworkMode, NetworkTarget, UnattributedAction, UnlistedAction } from './network.js';
+/** The live network configuration (read fresh on every operation). */
+export interface NetworkConfigSnapshot {
+    readonly enabled: boolean;
+    readonly mode: NetworkMode;
+    readonly unlisted: UnlistedAction;
+    /** Handling for traffic with no shell attribution. Default `'allow'`. */
+    readonly unattributed: UnattributedAction;
+    readonly loopback: 'allow' | 'policy';
+    readonly bind: string;
+    readonly port: number;
+    readonly noProxy: 'clear' | 'preserve';
+    /** Rewrite `HTTP(S)_PROXY`/`ALL_PROXY` for subprocesses. Default true. */
+    readonly injectEnv: boolean;
+    /** How long an unlisted-target approval may wait for a human (ms). */
+    readonly askTimeoutMs: number;
+}
+/** The network state the settings page and HTTP route render. */
+export interface NetworkSnapshot {
+    readonly enabled: boolean;
+    readonly mode: NetworkMode;
+    readonly bind: string;
+    readonly port: number;
+    readonly proxyActive: boolean;
+    readonly envInjected: boolean;
+    readonly denied: number;
+    readonly askBlocked: number;
+    readonly recent: readonly NetworkBlockRecord[];
+}
+export interface NetworkLifecycleOptions {
+    /** Register one disposer factory with the host plugin context. The factory
+     *  is invoked at dispose time; it must RETURN the teardown function. */
+    readonly effect: (disposeFactory: () => () => void, label: string) => void;
+    /** Read the live network config (settings-aware). */
+    readonly readConfig: () => NetworkConfigSnapshot;
+    /** The decision function (reads the live ruleset). */
+    readonly decide: (target: NetworkTarget) => NetworkDecision | Promise<NetworkDecision>;
+    /**
+     * Escalate an `ask` verdict to the interactive approval seam. Never called
+     * for a `deny` — the rule review stays authoritative.
+     */
+    readonly escalate?: (target: NetworkTarget, decision: NetworkDecision) => Promise<'allow' | 'deny'>;
+    /** Attribution for block records. */
+    readonly attribution: () => ProxyAttribution | undefined;
+    /** Extra block observer (audit/event feed). */
+    readonly onBlock?: (record: NetworkBlockRecord, attribution: ProxyAttribution | undefined) => void;
+    readonly logger: {
+        warn(message: string): void;
+        info?(message: string): void;
+    };
+}
+/**
+ * Owns the proxy and the environment injection across (re)binds.
+ */
+export declare class NetworkLifecycle {
+    private readonly options;
+    private proxy;
+    private envRestore;
+    private disposed;
+    /** Serializes mutations so rapid toggles cannot interleave. */
+    private queue;
+    constructor(options: NetworkLifecycleOptions);
+    /** Mount the proxy per the current config. No-op when disabled or live. */
+    attach(): Promise<void>;
+    /** Close the proxy and restore the environment. */
+    detach(): Promise<void>;
+    /**
+     * Re-read the config and re-mount: the old proxy is closed and the old
+     * environment restored before the new one is installed. This is what makes
+     * the settings-card switches take effect without a plugin reload.
+     */
+    rebind(): Promise<void>;
+    /** The diagnostics snapshot (safe to call at any time). */
+    snapshot(): NetworkSnapshot;
+    private run;
+    private attachLocked;
+    private detachLocked;
+    private closeProxyLocked;
+    private restoreEnvLocked;
+    private safeWarn;
+    private safeInfo;
+}