dsh-perm-gate 2.0.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

@@ -22,6 +22,9 @@ 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';
@@ -99,6 +102,82 @@ const CLEARED_CALL_TTL_MS = 5 * 60_000;
  * unrecognized wording fails closed (the request is forwarded to the human).
  */
 const SANDBOX_ESCALATION_REASON = /^escalate sandbox to (workspace-write|danger-full-access): /;
+// --- Deterministic cleanup pre-screen ----------------------------------------
+// Pattern for shell deletion commands (rm, rmdir, Remove-Item) with flags.
+const SHELL_DELETE_RE = /^(?:rm|rmdir|Remove-Item)\b/i;
+// Temp/build artifact directory name patterns (case-insensitive match on each path segment).
+const REGENERABLE_SEGMENT = /(?:^|[\\/])(?:temp|tmp|test[-_]clone|node_modules|\.cache|dist|build|__pycache__|\.pytest_cache|\.git|\.next|\.nuxt|coverage|\.tox|\.venv|venv|env|\.mypy_cache|\.parcel-cache)(?:[\\/]|$)/i;
+// Workspace-relative path tokens that are always regenerable.
+const REGENERABLE_TOKENS = /^(?:node_modules|\.next|__pycache__|\.cache|dist|build|\.git|coverage|\.pytest_cache|\.tox|\.venv|venv|env)$/i;
+/**
+ * Deterministic pre-screen for deletion commands. Returns a reason string when
+ * the deletion is clearly safe (targeting a regenerable/temp artifact inside the
+ * workspace), or undefined when the LLM should decide.
+ *
+ * This runs BEFORE the LLM risk grader to avoid the LLM's unconditional
+ * "Remove-Item → risky:deletion" bias. The LLM is still the fallback for
+ * ambiguous cases.
+ */
+function isCleanupSafe(exec) {
+    const tool = exec.name;
+    const args = exec.arguments ?? {};
+    // Only applies to shell/pwsh tools.
+    if (!/^(?:pwsh|bash|sh|cmd|shell|terminal)$/i.test(tool))
+        return undefined;
+    const commandText = typeof args.command === 'string' ? args.command : undefined;
+    if (commandText === undefined)
+        return undefined;
+    let commands = [];
+    try {
+        commands = decomposeShellCommand(commandText).commands;
+    }
+    catch {
+        return undefined;
+    }
+    const cwd = typeof args.cwd === 'string' ? args.cwd : cwdOf(exec) ?? '';
+    const posixCwd = cwd.replace(/\\/g, '/').toLowerCase();
+    for (const cmd of commands) {
+        if (!SHELL_DELETE_RE.test(cmd.command))
+            continue;
+        // Collect all non-flag argument tokens as potential targets.
+        const targets = cmd.args.filter((a) => !a.startsWith('-'));
+        if (targets.length === 0)
+            continue;
+        let allSafe = true;
+        for (const target of targets) {
+            const posixTarget = target.replace(/\\/g, '/').toLowerCase();
+            // Resolve relative to cwd.
+            const fullPath = posixTarget.startsWith('/') || /^[a-z]:\//i.test(posixTarget)
+                ? posixTarget
+                : posixCwd !== '' ? `${posixCwd}/${posixTarget}` : posixTarget;
+            // Check if the target path contains a regenerable segment.
+            if (REGENERABLE_SEGMENT.test(fullPath))
+                continue;
+            // Check bare token (e.g. "node_modules" without path separators).
+            if (REGENERABLE_TOKENS.test(target))
+                continue;
+            // Not clearly regenerable — let the LLM decide.
+            allSafe = false;
+            break;
+        }
+        if (allSafe) {
+            return `deletion targets regenerable/temp artifacts: ${targets.join(', ')}`;
+        }
+    }
+    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;
@@ -112,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
@@ -148,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,
@@ -158,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);
@@ -242,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)
@@ -538,6 +830,19 @@ export class PermGateRuntime {
         };
         const raw = decide(ctx, { decide: (c) => decideRules(this.ruleset, c) }, grantResolver, this.autoAllowExtra);
         const decision = this.applyPermissive(raw);
+        // 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
+        // `approval: never` (where refineAsk is never called).
+        if (decision.action === 'ask') {
+            const cleanupSafe = isCleanupSafe(exec);
+            if (cleanupSafe !== undefined) {
+                const reason = `cleanup-safe: ${cleanupSafe}`;
+                this.audit.append(makeEntry({ callId, tool: exec.name, outcome: 'allow', source: 'classifier', reason, at: Date.now() }));
+                this.recordEvent(exec, 'auto', reason, { risk: 'safe', verdict: 'cleanup-safe', category: 'safe' });
+                return undefined; // passthrough (allow)
+            }
+        }
         let outcome;
         let source;
         switch (decision.stage) {
@@ -644,6 +949,19 @@ export class PermGateRuntime {
                 return undefined;
             }
         }
+        // Defensive cleanup pre-screen: normally this is handled in decideExecution
+        // before refineAsk is ever called, but refineAsk is public and may be called
+        // directly by tests or future embedders. Keep the same deterministic check
+        // here as a safety net — identical logic to decideExecution's pre-screen.
+        const cleanupSafe = isCleanupSafe(exec);
+        if (cleanupSafe !== undefined) {
+            const reason = `cleanup-safe: ${cleanupSafe}`;
+            this.audit.append(makeEntry({ callId: randomId(), tool: exec.name, outcome: 'allow', source: 'classifier', reason, at: Date.now() }));
+            this.recordEvent(exec, 'auto', reason, { risk: 'safe', verdict: 'cleanup-safe', category: 'safe' });
+            this.untrackAsk(exec);
+            this.clearCall(exec, reason, 'cleanup-safe', 'classifier');
+            return undefined;
+        }
         if (!permissive.strategies.llmAssist)
             return decision;
         // One live read of the classifier setup. Without a usable receiver (a
@@ -656,7 +974,14 @@ export class PermGateRuntime {
             && (cfg?.endpoint === undefined || cfg?.endpoint === '' || cfg?.model === undefined || cfg?.model === '')) {
             return decision;
         }
-        const req = { tool: exec.name, args: exec.arguments ?? {}, reason: decision.reason };
+        // Inject cwd into the risk request so the LLM can see the full path context
+        // (e.g. that a Remove-Item targets a temp directory, not user data).
+        const riskArgs = { ...(exec.arguments ?? {}) };
+        const cwd = cwdOf(exec);
+        if (typeof cwd === 'string' && cwd !== '' && typeof riskArgs.cwd !== 'string') {
+            riskArgs.cwd = cwd;
+        }
+        const req = { tool: exec.name, args: riskArgs, reason: decision.reason };
         let risk;
         if (this.options.riskHook !== undefined) {
             risk = await this.options.riskHook(req);

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;