dsh-perm-gate 2.1.0 → 3.0.0

package/lib/runtime.js

@@ -11,21 +11,44 @@
 import { readFileSync } from 'node:fs';
 import { makeEntry, MemoryAuditMirror } from './audit.js';
 import { resolvePermissiveStrategies } from './config.js';
-import { appendAllowCommand, listAllowCommands, replaceAllowCommands } from './allowlist.js';
+import { appendAllowCommand, listAllowCommands, listAllowFromRulesDoc, replaceAllowCommands } from './allowlist.js';
 import { decide, CONTENT_ARG_KEYS } from './engine.js';
 import { EventLog, saveEventSnapshots } from './events.js';
 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 { compileDocument, compileRulesObject, 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';
+/** Locate a rule by its chain-wide index (deny entries first, then allow, then ask). */
+function findRuleByIndex(ruleset, index) {
+    return (ruleset.deny.find((entry) => entry.index === index) ??
+        ruleset.allow.find((entry) => entry.index === index) ??
+        ruleset.ask.find((entry) => entry.index === index));
+}
+/** Which layer of the chain produced a decision, from its stage. */
+function sourceOfStage(stage, reason) {
+    switch (stage) {
+        case 'hard-deny':
+            return 'hard-deny';
+        case 'grant':
+            return 'grant';
+        case 'rule':
+            return 'rule';
+        case 'classifier':
+            return 'classifier';
+        default:
+            return reason.startsWith('permissive') ? 'permissive' : 'default';
+    }
+}
 /**
  * One execution's session event log, or `undefined` when the host exposes none.
  *
@@ -164,6 +187,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 +212,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
@@ -186,6 +230,12 @@ export class PermGateRuntime {
      * frozen events, which would otherwise re-fold on every tool call.
      */
     presetCache;
+    /**
+     * Last stand-down announced per session (sessionId → the out-of-scope preset
+     * name, `''` when the session records none). Bounded by the session count and
+     * only read on the stand-down path — the in-scope path never touches it.
+     */
+    standDownAnnounced = new Map();
     learning;
     events;
     /** Learning candidates awaiting human approval + execution (call fingerprint → candidate). */
@@ -213,6 +263,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 +274,51 @@ 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,
         };
+        // Settings-first (dual-source): a configured `dsh-perm-gate-rules`
+        // namespace overrides every file path — the gate then loads with zero
+        // filesystem dependency. Bare defaults (nothing configured) fall through
+        // to the file sources below. Compile errors propagate: the constructor
+        // fails loud, and `reload()` keeps the previous rules on a hot change.
+        const settingsDoc = options.readRulesDocument?.();
+        if (settingsDoc !== undefined) {
+            const hash = documentHash(JSON.stringify(settingsDoc));
+            const hit = this.cache.get(hash);
+            if (hit !== undefined)
+                return hit;
+            const compiled = compileRulesObject(settingsDoc, {
+                maxGlobStars: 2,
+                caseInsensitivePaths: options.caseInsensitivePaths ?? true,
+            });
+            this.cache.set(hash, compiled);
+            return compiled;
+        }
+        // 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 +397,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)
@@ -362,9 +634,38 @@ export class PermGateRuntime {
      * `danger-full-access` means "full access without approval prompts", where a
      * forwarded ask can only fail (the approval seam rejects before any answerer
      * runs) and a hard-deny would silently overrule the tier the user chose.
+     *
+     * P0 is therefore monotonic only WITHIN the gate's scope, not across every
+     * preset. {@link announceStandDown} makes that visible instead of silent.
      */
-    gateActive(exec) {
-        return presetInScope(this.presetOf(exec), this.gatePresets);
+    gateActive(preset) {
+        return presetInScope(preset, this.gatePresets);
+    }
+    /**
+     * Record one `stand-down` event the first time a session is observed with a
+     * preset outside {@link gatePresets}, and again whenever that preset changes.
+     *
+     * Per-call silence is what makes a stand-down dangerous: the tool call looks
+     * exactly like a call the gate inspected and allowed. One event per
+     * transition is enough to say otherwise, and keeps the feed (and the
+     * `events.jsonl` append) proportional to preset changes rather than to call
+     * volume.
+     *
+     * The event is a NOTICE, not a decision: it carries no allow/deny meaning,
+     * and the call it was observed on is still settled entirely by the selected
+     * tier. `verdict: 'stand-down'` labels it for the history view.
+     */
+    announceStandDown(exec, preset) {
+        const sessionId = sessionIdOf(exec);
+        const announced = preset ?? '';
+        if (this.standDownAnnounced.get(sessionId) === announced)
+            return;
+        this.standDownAnnounced.set(sessionId, announced);
+        const scope = this.gatePresets.includes('*') ? 'every preset' : this.gatePresets.join(', ');
+        const named = preset === undefined ? 'no permission/preset recorded' : `"${preset}"`;
+        this.recordEvent(exec, 'stand-down', `perm-gate is INACTIVE: the session permission preset is ${named} and the gate scope is ${scope}. `
+            + 'No P0 hard-deny, no rule, no ask and no allow is evaluated for any call in this session — '
+            + 'the selected tier\'s own policy governs. Select a preset in the gate scope to re-arm it.', { verdict: 'stand-down' });
     }
     /**
      * Whether an `ask` produced while the gate is active can actually reach a
@@ -581,10 +882,16 @@ export class PermGateRuntime {
      */
     decideExecution(exec) {
         // The gate is scoped to its own tier(s): anywhere else it stands down
-        // entirely and records nothing (the session's selected tier owns the call).
-        if (!this.gateActive(exec))
+        // entirely and decides nothing (the session's selected tier owns the call).
+        // The stand-down is announced ONCE per (session, preset) transition — the
+        // call's outcome is unchanged, but the user must be able to see that the
+        // gate — including P0 hard-deny — is inactive; a silent stand-down reads as
+        // "the gate looked at this and allowed it".
+        const preset = this.presetOf(exec);
+        if (!this.gateActive(preset)) {
+            this.announceStandDown(exec, preset);
             return undefined;
-        const ctx = this.ctxFor(exec);
+        }
         const callId = randomId();
         // Preset deny-keyword layer (deny wins over allow): a dangerous-keyword hit
         // vetoes before grants / rules / LLM. Additive deny only — P0 semantics are
@@ -596,13 +903,9 @@ export class PermGateRuntime {
             this.recordEvent(exec, 'deny', reason, { verdict: 'deny-keyword' });
             return { kind: 'deny', reason };
         }
-        const grantResolver = (tool, args) => {
-            if (exec.parentAuthorized === false)
-                return 'no-match';
-            return this.grants.decide(tool, args);
-        };
-        const raw = decide(ctx, { decide: (c) => decideRules(this.ruleset, c) }, grantResolver, this.autoAllowExtra);
-        const decision = this.applyPermissive(raw);
+        // The same chain `explainCall` reports, evaluated once here so the two views
+        // cannot drift; this caller adds the side effects and the session layers.
+        const decision = this.applyPermissive(this.rawPolicy(exec));
         // Deterministic cleanup pre-screen: if a deletion command targets a
         // regenerable/temporary artifact inside the workspace, allow it directly.
         // This runs BEFORE the ask/passthrough logic so it works even under
@@ -671,6 +974,83 @@ export class PermGateRuntime {
         this.clearCall(exec, decision.reason, source, source);
         return undefined;
     }
+    /**
+     * The **pure policy** outcome for one call: the same chain
+     * {@link decideExecution} runs, with every side effect and every session-state
+     * layer removed.
+     *
+     * Side effects removed — no audit entry, no event, no ask tracking, no call
+     * clearance, no learning. A rule-test panel must be able to run on every
+     * keystroke without writing to the live decision feed.
+     *
+     * Session-state layers removed — the preset stand-down and the
+     * `approval: never` ask degradation both describe a session a session-less
+     * caller does not have. Including them is not harmless: the degradation turns
+     * every "the rules would ask a human" into a reported **allow**, which is the
+     * opposite of the truth for exactly the rules someone opens the panel to
+     * review (measured on the live host: `shell ls -la` reported `allow` while the
+     * rule layer said `ask`).
+     *
+     * `reason` is never collapsed: "allow" has causes worth naming (a rule, a
+     * grant, cleanup-safety, the permissive default).
+     */
+    explainCall(exec) {
+        const keyword = this.denyKeywordHit(exec);
+        if (keyword !== undefined) {
+            return {
+                action: 'deny',
+                reason: `deny-keyword: matches preset blacklist entry "${keyword}"`,
+                source: 'deny-keyword',
+            };
+        }
+        const decision = this.applyPermissive(this.rawPolicy(exec));
+        if (decision.action === 'ask') {
+            const cleanupSafe = isCleanupSafe(exec);
+            if (cleanupSafe !== undefined) {
+                return { action: 'allow', reason: `cleanup-safe: ${cleanupSafe}`, source: 'cleanup-safe' };
+            }
+        }
+        return {
+            action: decision.action,
+            reason: decision.reason,
+            source: sourceOfStage(decision.stage, decision.reason),
+            ...(decision.ruleIndex !== undefined ? { ruleIndex: decision.ruleIndex } : {}),
+        };
+    }
+    /**
+     * P0 hard-deny → P1 session grant → P2 rules → P4 ask, as a value. Shared by
+     * the host-facing decision and {@link explainCall} so the two cannot drift.
+     */
+    rawPolicy(exec) {
+        const grantResolver = (tool, args) => {
+            if (exec.parentAuthorized === false)
+                return 'no-match';
+            return this.grants.decide(tool, args);
+        };
+        return decide(this.ctxFor(exec), { decide: (c) => decideRules(this.ruleset, c) }, grantResolver, this.autoAllowExtra);
+    }
+    /**
+     * Rule-layer explanation for one would-be call: what the `permissions` chain
+     * decides on its own, before P0 hard-deny, P1 session grants, the P3
+     * classifier and the P4 ask ever get a say.
+     *
+     * This is the read-only half of a dry-run. It appends nothing to the audit
+     * mirror, records no event, mints no grant and touches no learning store, so a
+     * "rule test" panel may call it on every keystroke without leaving a trace in
+     * the decision feed. It answers a narrower question than
+     * {@link decideExecution} and says so: `ruleIndex` identifies a rule in the
+     * chain, which only this layer can attribute.
+     */
+    explainRules(exec) {
+        const decision = decideRules(this.ruleset, this.ctxFor(exec));
+        return {
+            action: decision.action,
+            reason: decision.reason,
+            ruleIndex: decision.ruleIndex,
+            rule: decision.ruleIndex === undefined ? undefined : findRuleByIndex(this.ruleset, decision.ruleIndex),
+            defaultAction: this.ruleset.defaultAction,
+        };
+    }
     /**
      * Apply the Permissive tier to a raw decision. Hard-deny and minted-grant
      * outcomes are never touched (fail-closed). `alwaysConfirm` escalates a
@@ -777,13 +1157,22 @@ export class PermGateRuntime {
         if (risk.kind === 'risky') {
             if (risk.category !== 'neutral') {
                 // Hard category (deletion / credential / remote / system / bulk) or an
-                // off-protocol output graded hard: auto-deny. The operation is clearly
-                // dangerous or sensitive — no popup, no learning, just block.
-                const reason = `${decision.reason} [llm-assist risky:${risk.category} → auto-deny]`;
-                this.audit.append(makeEntry({ callId: randomId(), tool: exec.name, outcome: 'deny', source: 'classifier', reason, at: Date.now() }));
-                this.recordEvent(exec, 'deny', reason, { risk: risk.category, verdict: 'llm-deny', category: risk.category });
-                this.untrackAsk(exec);
-                return { kind: 'deny', reason };
+                // off-protocol output graded hard: KEEP THE ASK.
+                //
+                // Denying here would make a probabilistic verdict the source of an
+                // unappealable block: the gate would be "sure enough" to refuse on the
+                // model's word alone, with no popup to appeal to and no grant to retry
+                // with — measured live on a benign `git commit -F …` the grader called
+                // `remote`. Deny stays with the deterministic layers (P0 hard-deny, the
+                // deny-keyword blacklist, explicit `deny:` rules); everything the
+                // classifier merely *suspects* is negotiated with the human instead.
+                //
+                // Hard categories stay distinct from `neutral` in one way that matters:
+                // they are NEVER learnable, so repeated confirmations cannot sediment
+                // them into an auto-allow.
+                const hardReason = `${decision.reason} [llm-assist risky:${risk.category} → ask]`;
+                this.trackAsk(exec, hardReason, undefined);
+                return { kind: 'ask', reason: hardReason };
             }
             const learning = this.liveRiskLearning();
             const fp = operationFingerprint(exec.name, exec.arguments ?? {}, exec.commandText);
@@ -1022,27 +1411,44 @@ export class PermGateRuntime {
     }
     /**
      * Grant "allow every occurrence of this command" (the always-confirm panel's
-     * second extended allow button): persist the command into the rules file's
-     * `allow` whitelist and reload. Returns the reload result.
+     * second extended allow button): persist the command into the rules' `allow`
+     * whitelist and reload. Prefers the settings-backed writer (the namespace's
+     * watch triggers the reload once the write lands); falls back to the rules
+     * file when no settings scope is wired. Returns the write verdict.
      */
     approveAllowEverywhere(commandWord, reason = 'permissive allow-everywhere') {
+        const writer = this.options.allowlistWriter;
+        if (writer !== undefined && writer.append(commandWord, reason))
+            return true;
         if (!this.options.rulesFile)
             return false;
         if (!appendAllowCommand(this.options.rulesFile, commandWord, reason))
             return false;
         return this.reload();
     }
-    /** Read-only view of the current allow-list command patterns (whitelist). */
+    /**
+     * Read-only view of the current allow-list command patterns (whitelist).
+     * Reads the settings document when the namespace is configured, else the
+     * rules file.
+     */
     allowlist() {
+        const doc = this.options.readRulesDocument?.();
+        if (doc !== undefined)
+            return listAllowFromRulesDoc(doc);
         if (!this.options.rulesFile)
             return [];
         return listAllowCommands(this.options.rulesFile);
     }
     /**
      * Replace the whitelist with exactly the given command patterns and reload.
-     * Returns the reload result (false when no rulesFile or the write failed).
+     * Prefers the settings-backed writer; falls back to the rules file when no
+     * settings scope is wired. Returns the write verdict (false when neither
+     * sink is available or the write failed).
      */
     setAllowlist(patterns) {
+        const writer = this.options.allowlistWriter;
+        if (writer !== undefined && writer.replace(patterns, 'permissive allowlist'))
+            return true;
         if (!this.options.rulesFile)
             return false;
         if (!replaceAllowCommands(this.options.rulesFile, patterns))

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;