dsh-perm-gate 2.0.0 → 2.1.2

package/lib/index.js

@@ -1,8 +1,13 @@
+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 { Config, resolveDshHome, resolveDataDir, resolveGatePresets, resolvePermissiveStrategies, resolveRulesFile } from './config.js';
+import { registerEventsRoute, registerHealthRoute, registerLearningRoute, registerNetworkRoute, registerReceiverRoute, registerReviewRoutes } from './events.js';
 import { buildReceiverInfo } from './receiver-info.js';
 import { PermGateRuntime } from './runtime.js';
+import { classifySessions, sweepSessionData } from './session-sweep.js';
+import { decideNetworkTarget } from './network.js';
+import { NetworkLifecycle } from './network-lifecycle.js';
+import { RuleWatcher } from './watch.js';
 export const name = 'dsh-perm-gate';
 /**
  * The `tools` service drives `tools/pre-execute`/`tools/result` (dsh-tools).
@@ -13,6 +18,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 +144,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 +163,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 = {}) {
@@ -181,6 +200,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 +237,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: () => {
@@ -290,6 +357,57 @@ 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;
@@ -310,6 +428,17 @@ export function apply(ctx, config = {}) {
                 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;
+                }
             });
         },
     });
@@ -352,6 +481,13 @@ 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');
             // Receiver projection for the settings card (provider/model catalog is
             // potentially slow to enumerate — cached briefly).
             let receiverCache = null;
@@ -398,7 +534,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 +563,93 @@ 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());
+    // ─── Hot reload watcher (Phase 3, T3.6) ────────────────────────────
+    const watchEnabled = typeof config.watch === 'boolean' ? config.watch : true;
+    if (watchEnabled) {
+        const watchDebounceMs = typeof config.watchDebounceMs === 'number' ? config.watchDebounceMs : 300;
+        const ruleWatcher = new RuleWatcher({
+            debounceMs: watchDebounceMs,
+            logger: { warn: (msg) => console.warn(msg) },
+        });
+        // Watch the effective rules file for the current workspace.
+        const rulesFile = resolveRulesFile(typeof config.rulesFile === 'string' ? config.rulesFile : undefined, dataDir);
+        const cwd = typeof config.cwd === 'string' ? config.cwd : process.cwd();
+        ruleWatcher.watch(cwd, [rulesFile], () => {
+            runtime.reload();
+        });
+        ctx.effect(() => () => {
+            ruleWatcher.closeAll();
+        }, 'dsh-perm-gate: rule watcher');
+    }
     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;
+}

package/lib/network-lifecycle.js

@@ -0,0 +1,180 @@
+/**
+ * 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 { NetworkProxy, injectProxyEnv } from './proxy.js';
+/**
+ * Owns the proxy and the environment injection across (re)binds.
+ */
+export class NetworkLifecycle {
+    options;
+    proxy;
+    envRestore;
+    disposed = false;
+    /** Serializes mutations so rapid toggles cannot interleave. */
+    queue = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        // Registered ONCE, before any bind: a dispose that races the first bind
+        // still tears the proxy down and restores the environment. `effect`
+        // expects a factory returning the disposer, so the disposer is returned.
+        options.effect(() => () => {
+            this.disposed = true;
+            void this.run(() => this.detachLocked());
+        }, 'dsh-perm-gate: network proxy');
+    }
+    /** Mount the proxy per the current config. No-op when disabled or live. */
+    attach() {
+        return this.run(() => this.attachLocked());
+    }
+    /** Close the proxy and restore the environment. */
+    detach() {
+        return this.run(() => this.detachLocked());
+    }
+    /**
+     * 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() {
+        return this.run(async () => {
+            await this.detachLocked();
+            await this.attachLocked();
+        });
+    }
+    /** The diagnostics snapshot (safe to call at any time). */
+    snapshot() {
+        const cfg = this.options.readConfig();
+        const proxy = this.proxy;
+        const stats = proxy?.blockStats() ?? { denied: 0, askBlocked: 0 };
+        const port = proxy?.port ?? 0;
+        return {
+            enabled: cfg.enabled,
+            mode: cfg.mode,
+            bind: cfg.bind,
+            port,
+            proxyActive: proxy !== undefined && port > 0,
+            envInjected: this.envRestore !== undefined,
+            denied: stats.denied,
+            askBlocked: stats.askBlocked,
+            recent: proxy?.recentBlocks() ?? [],
+        };
+    }
+    // ─── Internals (always called through the queue) ─────────────────────
+    run(work) {
+        const next = this.queue.then(() => work());
+        // Keep the chain alive through a rejected step; the step itself is
+        // responsible for degrading rather than throwing.
+        this.queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    async attachLocked() {
+        if (this.disposed)
+            return;
+        const cfg = this.options.readConfig();
+        if (!cfg.enabled)
+            return;
+        // Already live: leave it alone (a rebind detaches first).
+        if (this.proxy !== undefined && this.proxy.port > 0)
+            return;
+        // A previous attempt may have left a proxy that failed to bind; drop it
+        // so the retry starts clean.
+        await this.closeProxyLocked();
+        this.restoreEnvLocked();
+        const proxy = new NetworkProxy({
+            bind: cfg.bind,
+            port: cfg.port,
+            maxRecent: 100,
+            decide: this.options.decide,
+            ...(this.options.escalate !== undefined ? { escalate: this.options.escalate } : {}),
+            attribution: this.options.attribution,
+            ...(this.options.onBlock !== undefined ? { onBlock: this.options.onBlock } : {}),
+            logger: this.options.logger,
+        });
+        this.proxy = proxy;
+        const port = await proxy.start();
+        // A dispose landed while binding: the effect already ran detach, but the
+        // proxy was created after it, so close it here.
+        if (this.disposed) {
+            await this.closeProxyLocked();
+            return;
+        }
+        if (port <= 0) {
+            // Bind failed (already logged by the proxy). Keep the handle so the
+            // snapshot can report `proxyActive: false`.
+            return;
+        }
+        if (cfg.injectEnv) {
+            try {
+                this.envRestore = injectProxyEnv(port, cfg.noProxy);
+            }
+            catch (error) {
+                this.safeWarn(`[dsh-perm-gate] proxy env injection failed: ${String(error)} — the proxy is live but subprocesses are not routed through it`);
+            }
+        }
+        this.safeInfo(`[dsh-perm-gate] network proxy listening on ${cfg.bind}:${port} (mode ${cfg.mode}${cfg.injectEnv ? ', env injected' : ', env not injected'})`);
+    }
+    async detachLocked() {
+        this.restoreEnvLocked();
+        await this.closeProxyLocked();
+    }
+    async closeProxyLocked() {
+        const proxy = this.proxy;
+        this.proxy = undefined;
+        if (proxy === undefined)
+            return;
+        try {
+            await proxy.close();
+        }
+        catch (error) {
+            this.safeWarn(`[dsh-perm-gate] proxy close failed: ${String(error)}`);
+        }
+    }
+    restoreEnvLocked() {
+        const restore = this.envRestore;
+        this.envRestore = undefined;
+        if (restore === undefined)
+            return;
+        try {
+            restore();
+        }
+        catch (error) {
+            this.safeWarn(`[dsh-perm-gate] proxy env restore failed: ${String(error)}`);
+        }
+    }
+    safeWarn(message) {
+        try {
+            this.options.logger.warn(message);
+        }
+        catch { /* never escalate */ }
+    }
+    safeInfo(message) {
+        const info = this.options.logger.info;
+        if (info === undefined)
+            return;
+        try {
+            info.call(this.options.logger, message);
+        }
+        catch { /* never escalate */ }
+    }
+}