dsh-perm-gate 2.1.0 → 2.1.2

package/lib/runtime.d.ts

@@ -6,6 +6,7 @@ import { RiskLearning } from './learning.js';
 import { type RiskRequest, type RiskVerdict } from './risk.js';
 import { type HostLlmLike, type HostModelSelection } from './host-llm.js';
 import { type CompiledRuleset } from './rule.js';
+import type { NetworkTarget } from './network.js';
 import { type SessionEventLike } from './preset.js';
 export interface PreToolDecisionLike {
     kind: 'deny' | 'ask';
@@ -73,6 +74,8 @@ interface PendingAsk {
     readonly learningKey?: string;
 }
 export interface PermGateRuntimeOptions extends PermGateConfig {
+    /** Workspace root for chain resolution. Defaults to process.cwd(). */
+    readonly cwd?: string;
     readonly onRulesChanged?: (ruleset: CompiledRuleset) => void;
     readonly now?: () => number;
     /**
@@ -132,6 +135,24 @@ export interface PermGateRuntimeOptions extends PermGateConfig {
      * review page's diff/revert data plane (events are still recorded).
      */
     readonly snapshotsDir?: string;
+    /**
+     * Raise one interactive approval request on behalf of a subprocess network
+     * connection. Wired by `apply` to the DSH `approval` service
+     * (`approval.request`), which routes the prompt to the agent, appends the
+     * `approval/asked` + `approval/decided` audit pair, and applies the session
+     * policy before any answerer runs.
+     *
+     * Absent (or throwing) means the connection cannot ride the seam and the
+     * gate fails closed to `deny`. Only `'allowed-once'` is treated as an allow.
+     */
+    readonly requestApproval?: (req: NetworkApprovalRequest) => Promise<ApprovalOutcomeLike>;
+    /**
+     * How long one approved network target stays approved for the session (ms).
+     * A single shell command routinely opens many connections to the same host;
+     * without this the human would be prompted once per connection.
+     * Default 30 minutes.
+     */
+    readonly networkGrantTtlMs?: number;
 }
 export type CallDecision = 'allow' | 'deny' | 'ask';
 /** The effective Permissive tier state read per tool call. */
@@ -152,6 +173,30 @@ export interface ApprovalRequestLike {
 }
 /** A closed approval outcome, structurally the DSH seam's `ApprovalOutcome`. */
 export type ApprovalOutcomeLike = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+/**
+ * One approval ask the gate raises on behalf of a subprocess network
+ * connection. Structurally the subset of the DSH `ApprovalRequest` the gate
+ * supplies — the host service adds the borrowed session/log handling.
+ */
+export interface NetworkApprovalRequest {
+    /** The host agent the question is asked on behalf of (routes the prompt). */
+    readonly agent: unknown;
+    /** The tool whose subprocess opened the connection. */
+    readonly toolName: string;
+    /** The exact tool call, when the host gave one — lets the UI attach the prompt. */
+    readonly callId?: string;
+    readonly reason: string;
+    readonly signal?: AbortSignal;
+}
+/** The attribution the proxy layer receives for one connection. */
+export interface ShellAttribution {
+    readonly tool: string;
+    readonly callId?: string;
+    /** The host agent, needed to route an approval request. */
+    readonly agent?: unknown;
+    readonly sessionId: string;
+    readonly signal?: AbortSignal;
+}
 export declare class PermGateRuntime {
     private readonly options;
     private ruleset;
@@ -165,6 +210,14 @@ export declare class PermGateRuntime {
     private readonly gatePresets;
     /** Extra tool names the user classified as safe (config `autoAllowTools`). */
     private readonly autoAllowExtra;
+    /** In-flight shell executions, for proxy-layer network attribution. */
+    private readonly inFlightShells;
+    /** Stable key per execution object (the host call id is not always present). */
+    private readonly shellKeys;
+    private shellSeq;
+    /** Session-scoped network grants: grantKey -> expiry epoch ms. */
+    private readonly networkGrants;
+    private readonly networkGrantTtlMs;
     /**
      * Cache of the permission-preset fold. The key is the log's length plus the
      * identity of its LAST event: a session's log only appends, so "same length
@@ -213,6 +266,40 @@ export declare class PermGateRuntime {
     /** Deep read-only view of the learning state (diagnostics/tests). */
     learningSnapshot(): ReturnType<RiskLearning['snapshot']>;
     private ctxFor;
+    /**
+     * Register a shell execution as in-flight so a proxy-layer block made by its
+     * child process can be attributed back to the session — and therefore ride
+     * the interactive approval seam. Called when the gate lets a shell call run;
+     * {@link endShellExecution} removes it.
+     */
+    beginShellExecution(exec: ToolExecutionLike): void;
+    /** Remove a shell execution from the in-flight table (its tool call settled). */
+    endShellExecution(exec: ToolExecutionLike): void;
+    /** Drop every in-flight entry (dispose / session teardown). */
+    clearShellExecutions(): void;
+    /**
+     * The newest live in-flight shell execution, for proxy-layer attribution.
+     * Stale entries (a shell that never reported a result) are expired here so a
+     * long-dead call can never authorize a later connection.
+     */
+    currentAttribution(): ShellAttribution | undefined;
+    /** A stable per-execution key: the host call id, else an object-keyed fallback. */
+    private shellKeyOf;
+    /**
+     * Ask the human to allow one network target, on behalf of the attributed
+     * shell execution. Returns `'allow'` only for an explicit `allowed-once`;
+     * every other outcome (rejection, cancellation, timeout, no answerer)
+     * fails closed to `'deny'`.
+     *
+     * The approval seam requires an open turn — the durable audit pair must be
+     * enclosed by the log's commit boundary — which holds here because the ask
+     * happens *while* the shell tool call is executing.
+     */
+    askNetwork(target: NetworkTarget, reason: string, timeoutMs: number): Promise<'allow' | 'deny'>;
+    /** Record one network escalation outcome in the audit mirror + event feed. */
+    private auditNetworkAsk;
+    /** The compiled ruleset (read-only view for network module). */
+    get compiledRuleset(): CompiledRuleset;
     private liveRiskLearning;
     private liveRiskSediment;
     private liveClassifySource;

package/lib/runtime.js

@@ -18,11 +18,13 @@ import { decideRules } from './evaluate.js';
 import { canonicalizeCall, GrantRegistry } from './grant.js';
 import { learnKey, operationFingerprint, RiskLearning } from './learning.js';
 import { ArtifactRegistry } from './path.js';
-import { decomposeShellCommand } from './shell.js';
 import { classifyRisk, classifyRiskWith } from './risk.js';
 import { completeViaHost, DEFAULT_HOST_MODEL } from './host-llm.js';
 import { chatCompletion } from './classifier.js';
 import { compileDocument, documentHash, extractPathCandidates, parsePermissionsDocument } from './rule.js';
+import { decomposeShellCommand } from './shell.js';
+import { extractAgentCandidates } from './agent-identity.js';
+import { resolveRuleChain } from './rule-chain.js';
 import { DEFAULT_DENY_KEYWORDS } from './deny-defaults.js';
 import { permissionPresetOf, presetInScope } from './preset.js';
 import { resolveGatePresets } from './config.js';
@@ -164,6 +166,18 @@ function isCleanupSafe(exec) {
     }
     return undefined;
 }
+/** A shell whose result never arrived is dropped after this long (ms). */
+const IN_FLIGHT_SHELL_TTL_MS = 30 * 60_000;
+/** Tool names that execute a command string (mirrors evaluate's shell roster). */
+const SHELL_TOOL_NAMES = new Set(['shell', 'terminal', 'bash', 'pwsh', 'sh', 'cmd', 'powershell']);
+/** Whether a tool name runs a shell command. */
+function isShellToolName(name) {
+    return SHELL_TOOL_NAMES.has(name);
+}
+/** The session-grant key for one network target (scheme/host/port). */
+function networkGrantKey(sessionId, target) {
+    return `${sessionId}|${target.scheme ?? ''}|${target.host}|${target.port ?? ''}`;
+}
 export class PermGateRuntime {
     options;
     ruleset;
@@ -177,6 +191,15 @@ export class PermGateRuntime {
     gatePresets;
     /** Extra tool names the user classified as safe (config `autoAllowTools`). */
     autoAllowExtra;
+    // ─── Network seam (T2.11) ───────────────────────────────────────────
+    /** In-flight shell executions, for proxy-layer network attribution. */
+    inFlightShells = new Map();
+    /** Stable key per execution object (the host call id is not always present). */
+    shellKeys = new WeakMap();
+    shellSeq = 0;
+    /** Session-scoped network grants: grantKey -> expiry epoch ms. */
+    networkGrants = new Map();
+    networkGrantTtlMs;
     /**
      * Cache of the permission-preset fold. The key is the log's length plus the
      * identity of its LAST event: a session's log only appends, so "same length
@@ -213,6 +236,7 @@ export class PermGateRuntime {
         this.gatePresets = options.gatePresets === undefined ? ['*'] : resolveGatePresets(options.gatePresets);
         this.autoAllowExtra = new Set((options.autoAllowTools ?? []).filter((name) => typeof name === 'string' && name !== ''));
         this.strategies = resolvePermissiveStrategies(options.permissiveStrategies);
+        this.networkGrantTtlMs = options.networkGrantTtlMs ?? 30 * 60_000;
         this.learning = new RiskLearning(options.learningFile, {
             threshold: () => this.liveRiskLearning().threshold,
             now: options.now,
@@ -223,12 +247,33 @@ export class PermGateRuntime {
         this.ruleset = this.compileInline(options);
     }
     compileInline(options) {
-        const text = options.rulesFile !== undefined ? readFileSafe(options.rulesFile) : '';
         const empty = {
             defaultAction: options.defaultAction ?? 'ask',
             deny: [], allow: [], ask: [],
             caseInsensitivePaths: options.caseInsensitivePaths ?? true,
         };
+        // Chain mode: when searchUp is enabled, use the multi-file chain resolver.
+        if (options.searchUp === true) {
+            const cwd = options.cwd ?? process.cwd();
+            const rulesFile = options.rulesFile !== undefined ? options.rulesFile : 'rules.yml';
+            try {
+                return resolveRuleChain(cwd, {
+                    rulesFile,
+                    searchUp: true,
+                    fallbackPath: options.fallbackPath,
+                    badFilePolicy: options.badFilePolicy ?? 'fail',
+                    maxChainLength: options.maxChainLength ?? 10,
+                }, {
+                    maxGlobStars: 2,
+                    caseInsensitivePaths: options.caseInsensitivePaths ?? true,
+                });
+            }
+            catch {
+                return empty;
+            }
+        }
+        // Single-file mode (legacy): read and compile one rules file.
+        const text = options.rulesFile !== undefined ? readFileSafe(options.rulesFile) : '';
         if (text === '')
             return empty;
         const hash = documentHash(text);
@@ -307,8 +352,190 @@ export class PermGateRuntime {
             home: cwdOf(exec),
             caseInsensitive: this.options.caseInsensitivePaths ?? true,
             dshHome: this.options.dshHome,
+            agentCandidates: extractAgentCandidates(exec),
+        };
+    }
+    // ─── Network seam (T2.11) ───────────────────────────────────────────
+    /**
+     * Register a shell execution as in-flight so a proxy-layer block made by its
+     * child process can be attributed back to the session — and therefore ride
+     * the interactive approval seam. Called when the gate lets a shell call run;
+     * {@link endShellExecution} removes it.
+     */
+    beginShellExecution(exec) {
+        if (!isShellToolName(exec.name))
+            return;
+        const key = this.shellKeyOf(exec);
+        this.inFlightShells.set(key, {
+            key,
+            tool: exec.name,
+            callId: exec.callId,
+            agent: exec.agent,
+            sessionId: sessionIdOf(exec),
+            signal: exec.signal,
+            at: Date.now(),
+        });
+    }
+    /** Remove a shell execution from the in-flight table (its tool call settled). */
+    endShellExecution(exec) {
+        if (!isShellToolName(exec.name))
+            return;
+        this.inFlightShells.delete(this.shellKeyOf(exec));
+    }
+    /** Drop every in-flight entry (dispose / session teardown). */
+    clearShellExecutions() {
+        this.inFlightShells.clear();
+    }
+    /**
+     * The newest live in-flight shell execution, for proxy-layer attribution.
+     * Stale entries (a shell that never reported a result) are expired here so a
+     * long-dead call can never authorize a later connection.
+     */
+    currentAttribution() {
+        const now = Date.now();
+        let newest;
+        for (const entry of this.inFlightShells.values()) {
+            if (now - entry.at > IN_FLIGHT_SHELL_TTL_MS) {
+                this.inFlightShells.delete(entry.key);
+                continue;
+            }
+            // An aborted call was cancelled or rejected: it will never run, so it
+            // must not authorize a connection made by some later command.
+            if (entry.signal?.aborted === true) {
+                this.inFlightShells.delete(entry.key);
+                continue;
+            }
+            if (newest === undefined || entry.at >= newest.at)
+                newest = entry;
+        }
+        if (newest === undefined)
+            return undefined;
+        return {
+            tool: newest.tool,
+            ...(newest.callId !== undefined ? { callId: newest.callId } : {}),
+            ...(newest.agent !== undefined ? { agent: newest.agent } : {}),
+            sessionId: newest.sessionId,
+            ...(newest.signal !== undefined ? { signal: newest.signal } : {}),
         };
     }
+    /** A stable per-execution key: the host call id, else an object-keyed fallback. */
+    shellKeyOf(exec) {
+        const cached = this.shellKeys.get(exec);
+        if (cached !== undefined)
+            return cached;
+        const key = typeof exec.callId === 'string' && exec.callId !== ''
+            ? `call:${exec.callId}`
+            : `exec:${sessionIdOf(exec)}:${exec.name}:${++this.shellSeq}`;
+        this.shellKeys.set(exec, key);
+        return key;
+    }
+    /**
+     * Ask the human to allow one network target, on behalf of the attributed
+     * shell execution. Returns `'allow'` only for an explicit `allowed-once`;
+     * every other outcome (rejection, cancellation, timeout, no answerer)
+     * fails closed to `'deny'`.
+     *
+     * The approval seam requires an open turn — the durable audit pair must be
+     * enclosed by the log's commit boundary — which holds here because the ask
+     * happens *while* the shell tool call is executing.
+     */
+    async askNetwork(target, reason, timeoutMs) {
+        const attribution = this.currentAttribution();
+        if (attribution === undefined || attribution.agent === undefined) {
+            // Unattributable traffic cannot ride the approval seam — fail closed.
+            this.auditNetworkAsk(target, 'deny', 'no in-flight shell to attribute the connection to', undefined);
+            return 'deny';
+        }
+        // A session already allowed this exact target: honour it without asking.
+        const grantKey = networkGrantKey(attribution.sessionId, target);
+        if (this.networkGrants.has(grantKey)) {
+            return 'allow';
+        }
+        const requester = this.options.requestApproval;
+        if (requester === undefined) {
+            this.auditNetworkAsk(target, 'deny', 'no approval service available', attribution);
+            return 'deny';
+        }
+        const controller = new AbortController();
+        let timer;
+        // The timeout is raced, not merely signalled. `abort()` only *asks* the
+        // callee to withdraw the question; a callee that ignores the signal would
+        // otherwise leave this await pending forever and hang the CONNECT. The
+        // race guarantees the wait settles no matter what the seam does.
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                resolve('unavailable');
+            }, Math.max(1, timeoutMs));
+        });
+        let outcome = 'unavailable';
+        try {
+            outcome = await Promise.race([
+                requester({
+                    agent: attribution.agent,
+                    toolName: attribution.tool,
+                    ...(attribution.callId !== undefined ? { callId: attribution.callId } : {}),
+                    reason,
+                    signal: controller.signal,
+                }),
+                timedOut,
+            ]);
+        }
+        catch {
+            // A seam failure (e.g. no open turn) is never an allow.
+            outcome = 'unavailable';
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        if (outcome === 'allowed-once') {
+            // Remember it for this session so one command making many connections
+            // does not prompt once per connection.
+            this.networkGrants.set(grantKey, Date.now() + this.networkGrantTtlMs);
+            this.auditNetworkAsk(target, 'allow', 'approved by the human (session grant)', attribution);
+            return 'allow';
+        }
+        this.auditNetworkAsk(target, 'deny', `approval seam returned ${outcome}`, attribution);
+        return 'deny';
+    }
+    /** Record one network escalation outcome in the audit mirror + event feed. */
+    auditNetworkAsk(target, verdict, reason, attribution) {
+        const now = Date.now();
+        const tool = attribution?.tool ?? 'subprocess';
+        const detail = `network ${verdict === 'allow' ? 'allowed' : 'denied'} ${target.scheme ?? '?'}://${target.host}${target.port !== undefined ? `:${target.port}` : ''} — ${reason}`;
+        try {
+            this.audit.append(makeEntry({
+                callId: randomId(),
+                tool,
+                outcome: verdict === 'allow' ? 'allow' : 'deny',
+                source: 'rule',
+                reason: detail,
+                at: now,
+            }));
+        }
+        catch {
+            // Auditing must never influence the verdict.
+        }
+        if (this.events !== undefined && attribution?.sessionId !== undefined) {
+            try {
+                this.events.append({
+                    sessionId: attribution.sessionId,
+                    tool,
+                    kind: verdict === 'allow' ? 'auto' : 'deny',
+                    reason: detail,
+                    verdict: 'network-ask',
+                });
+            }
+            catch {
+                // Same: the feed is best-effort.
+            }
+        }
+    }
+    /** The compiled ruleset (read-only view for network module). */
+    get compiledRuleset() {
+        return this.ruleset;
+    }
     liveRiskLearning() {
         const read = this.options.readRiskLearning;
         if (read !== undefined)

package/lib/session-sweep.d.ts

@@ -0,0 +1,45 @@
+/** Session ids grouped by their lifecycle class, all prefix-stripped (see {@link normalizeSessionId}). */
+export interface SessionClassification {
+    /** Sessions referenced by some workspace's `sessionIds`. */
+    readonly live: ReadonlySet<string>;
+    /** Sessions listed in the store's `global.archivedSessionIds`. */
+    readonly archived: ReadonlySet<string>;
+}
+/** A session id whose gate data is stale and can be swept. */
+export interface SweepReport {
+    /** Decision-event lines removed from events.jsonl. */
+    readonly eventsRemoved: number;
+    /** Snapshot files deleted from the snapshots directory. */
+    readonly snapshotsRemoved: number;
+}
+/** Strip the `session-` prefix so ids from different sources compare equal. */
+export declare function normalizeSessionId(id: unknown): string;
+/**
+ * Classify sessions from the raw text of the workspace store. Returns `null`
+ * on unparsable or structurally unexpected content (torn write, format bump) —
+ * the caller skips the round. Missing `global`/`tables` sections degrade to
+ * empty sets rather than failing: a fresh install has neither.
+ */
+export declare function classifySessions(raw: string): SessionClassification | null;
+/**
+ * Whether a gate-side session id belongs to an archived or deleted session.
+ * An empty id (unattributable legacy row) never matches — the same semantics
+ * `snapshotMatchesSession` uses for snapshots, so unattributable data is kept.
+ */
+export declare function isStaleSession(id: string, cls: SessionClassification): boolean;
+/** Options for {@link sweepSessionData}; all paths are plugin-owned except the store. */
+export interface SweepOptions {
+    readonly classification: SessionClassification;
+    /** The decision-event JSONL feed (plugin data dir). */
+    readonly eventsFile: string;
+    /** The per-event pre-change snapshot directory (plugin data dir). */
+    readonly snapshotsDir: string;
+}
+/**
+ * Drop archived/dead sessions' rows from `events.jsonl` (atomic tmp+rename
+ * rewrite, only when something is actually removed) and delete their snapshot
+ * files. Both halves are independent: a failure in one still lets the other
+ * run. I/O errors are swallowed with a warn — best-effort cleanup, never a
+ * gating concern.
+ */
+export declare function sweepSessionData(opts: SweepOptions): SweepReport;

package/lib/session-sweep.js

@@ -0,0 +1,153 @@
+/**
+ * Session-lifecycle sweep for dsh-perm-gate: DSH's workspace store
+ * (`<dshHome>/storages/workspace.json`) is the authority on which sessions are
+ * live and which were archived. On plugin start and hourly, the gate classifies
+ * every session id it holds gate data for — live (in a workspace), archived
+ * (in `global.archivedSessionIds`), or gone (neither) — and drops the
+ * authorization-chain data of archived/gone sessions: their decision events in
+ * `events.jsonl` and their pre-change snapshots in `snapshots/`.
+ *
+ * Fail-open like every other side effect in this plugin: any I/O or parse
+ * error is swallowed with a single warn and the round is skipped — the sweep
+ * must never influence gating. The workspace store is read-only here (DSH owns
+ * it and rewrites it continuously); a torn read simply defers to the next round.
+ */
+import { readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Strip the `session-` prefix so ids from different sources compare equal. */
+export function normalizeSessionId(id) {
+    const s = String(id ?? '');
+    return s.startsWith('session-') ? s.slice('session-'.length) : s;
+}
+/**
+ * Classify sessions from the raw text of the workspace store. Returns `null`
+ * on unparsable or structurally unexpected content (torn write, format bump) —
+ * the caller skips the round. Missing `global`/`tables` sections degrade to
+ * empty sets rather than failing: a fresh install has neither.
+ */
+export function classifySessions(raw) {
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc))
+        return null;
+    const root = doc;
+    const live = new Set();
+    const workspaces = root.tables?.workspaces;
+    if (typeof workspaces === 'object' && workspaces !== null) {
+        for (const record of Object.values(workspaces)) {
+            const ids = record?.sessionIds;
+            if (!Array.isArray(ids))
+                continue;
+            for (const id of ids)
+                live.add(normalizeSessionId(id));
+        }
+    }
+    const archived = new Set();
+    if (Array.isArray(root.global?.archivedSessionIds)) {
+        for (const id of root.global.archivedSessionIds)
+            archived.add(normalizeSessionId(id));
+    }
+    return { live, archived };
+}
+/**
+ * Whether a gate-side session id belongs to an archived or deleted session.
+ * An empty id (unattributable legacy row) never matches — the same semantics
+ * `snapshotMatchesSession` uses for snapshots, so unattributable data is kept.
+ */
+export function isStaleSession(id, cls) {
+    const norm = normalizeSessionId(id);
+    return norm !== '' && !cls.live.has(norm);
+}
+/**
+ * Drop archived/dead sessions' rows from `events.jsonl` (atomic tmp+rename
+ * rewrite, only when something is actually removed) and delete their snapshot
+ * files. Both halves are independent: a failure in one still lets the other
+ * run. I/O errors are swallowed with a warn — best-effort cleanup, never a
+ * gating concern.
+ */
+export function sweepSessionData(opts) {
+    const eventsRemoved = sweepEvents(opts);
+    const snapshotsRemoved = sweepSnapshots(opts);
+    return { eventsRemoved, snapshotsRemoved };
+}
+function sweepEvents({ classification, eventsFile }) {
+    let raw;
+    try {
+        raw = readFileSync(eventsFile, 'utf8');
+    }
+    catch {
+        return 0; // no feed yet (or unreadable) — nothing to sweep
+    }
+    const lines = raw.split('\n');
+    const kept = [];
+    let removed = 0;
+    for (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        let stale = false;
+        try {
+            const ev = JSON.parse(line);
+            stale = isStaleSession(String(ev.sessionId ?? ''), classification);
+        }
+        catch {
+            // An unparsable line is unattributable — keep it (never destroy evidence).
+        }
+        if (stale)
+            removed += 1;
+        else
+            kept.push(line);
+    }
+    if (removed === 0)
+        return 0;
+    try {
+        const tmp = `${eventsFile}.sweep-tmp`;
+        writeFileSync(tmp, kept.length > 0 ? kept.join('\n') + '\n' : '', 'utf8');
+        renameSync(tmp, eventsFile);
+        return removed;
+    }
+    catch (e) {
+        warn('events rewrite failed', e);
+        return 0;
+    }
+}
+function sweepSnapshots({ classification, snapshotsDir }) {
+    let entries;
+    try {
+        entries = readdirSync(snapshotsDir);
+    }
+    catch {
+        return 0; // no snapshot dir yet
+    }
+    let removed = 0;
+    for (const name of entries) {
+        if (!/^\d+\.json$/.test(name))
+            continue;
+        const abs = join(snapshotsDir, name);
+        let stale = false;
+        try {
+            const doc = JSON.parse(readFileSync(abs, 'utf8'));
+            stale = isStaleSession(String(doc.sessionId ?? ''), classification);
+        }
+        catch {
+            // Unparsable snapshot (torn write) has no attributable session — keep it.
+        }
+        if (!stale)
+            continue;
+        try {
+            rmSync(abs);
+            removed += 1;
+        }
+        catch (e) {
+            warn(`snapshot ${name} delete failed`, e);
+        }
+    }
+    return removed;
+}
+function warn(what, e) {
+    console.warn(`[dsh-perm-gate] session sweep: ${what}:`, e instanceof Error ? e.message : e);
+}

package/lib/shadow.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shadow detection for dsh-perm-gate rule chains.
+ *
+ * A rule is "shadowed" when an earlier rule in the same action partition
+ * always matches the same (or a superset of) tool calls, making the later
+ * rule unreachable. Shadowed rules are dead weight — they can never fire
+ * and may confuse users who think they are effective.
+ *
+ * This module performs a structural (conservative) shadow check. It does NOT
+ * do full semantic analysis — it flags potential shadows based on pattern
+ * structure, not on actual runtime argument values.
+ */
+import type { CompiledRuleset } from './rule.js';
+export interface ShadowReport {
+    /** Rule indices that are shadowed (unreachable). */
+    readonly shadowed: readonly number[];
+    /** Human-readable reasons per shadowed rule. */
+    readonly reasons: ReadonlyMap<number, string>;
+}
+/**
+ * Detect shadowed rules within a compiled ruleset.
+ *
+ * For each action partition (deny, allow, ask), check if any rule is
+ * dominated by an earlier rule in the same partition. A rule is dominated
+ * when:
+ *   1. Its tools pattern is a subset (or equal) of an earlier rule's tools
+ *   2. Its command pattern is a subset (or equal)
+ *   3. Its args/paths dimensions are subsets
+ *   4. Its new dimensions (params/absent/agents/when/network) are subsets
+ *
+ * This is conservative: it only flags rules that are DEFINITELY unreachable,
+ * not rules that MIGHT be unreachable under certain argument combinations.
+ */
+export declare function detectShadows(ruleset: CompiledRuleset): ShadowReport;