dsh-perm-gate 3.0.0 → 4.1.0-beta.1

package/lib/config.d.ts

@@ -10,6 +10,9 @@ import { DEFAULT_GATE_PRESETS, resolveGatePresets } from './preset.js';
 export declare function resolveDshHome(configured?: string): string;
 /** This plugin's data directory (`<dshHome>/perm-gate`), always defined. */
 export declare function resolveDataDir(configured?: string): string;
+export declare function ensureDataDir(dataDir: string): boolean;
+/** Check whether the data directory exists without creating it. */
+export declare function dataDirReady(dataDir: string): boolean;
 /**
  * The permissions document the gate loads. An explicit `rulesFile` wins; unset
  * falls back to `<dataDir>/rules.yml`, so a rules file the user drops in the

package/lib/config.js

@@ -3,6 +3,7 @@
  * loader validates and fills defaults before `apply`. Invalid values fail loud.
  */
 import { homedir } from 'node:os';
+import { mkdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { DEFAULT_GATE_PRESETS, resolveGatePresets } from './preset.js';
@@ -24,6 +25,41 @@ export function resolveDshHome(configured) {
 export function resolveDataDir(configured) {
     return join(resolveDshHome(configured), 'perm-gate');
 }
+/**
+ * Lazily ensure the data directory exists. Safe to call repeatedly —
+ * `mkdirSync({recursive:true})` is a no-op when the directory already
+ * exists. Returns `true` if the directory is now available, `false`
+ * if creation failed (caller should degrade to empty defaults).
+ *
+ * Used by every write path. Read paths should call `dataDirReady()`
+ * instead to avoid creating the directory as a side effect of reading.
+ */
+let _dataDirReady = false;
+export function ensureDataDir(dataDir) {
+    if (_dataDirReady)
+        return true;
+    try {
+        mkdirSync(dataDir, { recursive: true });
+        _dataDirReady = true;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check whether the data directory exists without creating it. */
+export function dataDirReady(dataDir) {
+    if (_dataDirReady)
+        return true;
+    try {
+        statSync(dataDir);
+        _dataDirReady = true;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The permissions document the gate loads. An explicit `rulesFile` wins; unset
  * falls back to `<dataDir>/rules.yml`, so a rules file the user drops in the
@@ -157,7 +193,7 @@ export const Config = z.object({
     networkAskTimeoutMs: z.number().min(1000).max(600_000).default(120_000),
     networkGrantTtlMs: z.number().min(0).max(24 * 60 * 60_000).default(30 * 60_000),
     // Hot reload (Phase 3)
-    watch: z.boolean().default(true),
+    watch: z.boolean().default(false),
     watchDebounceMs: z.number().min(50).max(5000).default(300),
 });
 export function resolveConfig(config = {}) {

package/lib/events.d.ts

@@ -100,6 +100,13 @@ export declare class EventLog {
     /** Snapshot directory; `undefined` disables diff/revert support. */
     private readonly snapshotsDir;
     private seq;
+    /**
+     * Live subscribers, notified once per successfully appended event. They exist
+     * so a browser half can be pushed to instead of re-reading the whole JSONL on
+     * a timer; a subscriber that throws is dropped from the notification only, it
+     * never costs the append its event.
+     */
+    private readonly listeners;
     constructor(
     /** JSONL path; `undefined` disables event recording entirely. */
     filePath: string | undefined, now?: () => number, 
@@ -107,6 +114,15 @@ export declare class EventLog {
     snapshotsDir?: string | undefined);
     /** Append one event; returns it, or undefined when recording is disabled/failed. */
     append(input: GateEventInput): GateEvent | undefined;
+    /**
+     * Watch events as they are appended. The listener is called once per event,
+     * after the JSONL write, from inside `append` — so it runs on the gate's own
+     * decision path and must stay cheap and non-throwing.
+     *
+     * @param listener - receives each appended event.
+     * @returns the unsubscribe.
+     */
+    subscribe(listener: (event: GateEvent) => void): () => void;
     /** Events with `id > since`, optionally filtered to one session. */
     query({ sessionId, since }?: {
         sessionId?: string;
@@ -128,6 +144,7 @@ export interface WebServerLike {
     }): () => void;
 }
 export declare const EVENTS_ROUTE = "/api/dsh-perm-gate/events";
+export declare const STREAM_ROUTE = "/api/dsh-perm-gate/stream";
 export declare const LEARNING_ROUTE = "/api/dsh-perm-gate/learning";
 export declare const HEALTH_ROUTE = "/api/dsh-perm-gate/health";
 export declare const NETWORK_ROUTE = "/api/dsh-perm-gate/network";
@@ -144,6 +161,24 @@ export declare const RULES_ROUTE = "/api/dsh-perm-gate/rules";
  * unavailable — the host keeps running, only the HTTP API is missing).
  */
 export declare function registerEventsRoute(server: unknown, log: EventLog): (() => void) | undefined;
+/**
+ * Register `GET /api/dsh-perm-gate/stream?sessionId=&since=` on the webServer
+ * service: the same events {@link registerEventsRoute} serves, but pushed.
+ *
+ * The response is `text/event-stream`. On connect the backlog after `since` is
+ * written as one `data: {"events":[…],"backlog":true}` frame, then each event
+ * appended from that moment on is written as it lands as `data: {"events":[…]}` —
+ * so the browser half is never forced to re-read the whole JSONL on a timer.
+ * `: ping` comments hold the connection open while nothing is being decided.
+ *
+ * The session filter applies to both the backlog and the live pushes. Nothing
+ * is buffered for a disconnected client: it reconnects with its own cursor and
+ * the backlog frame restores it.
+ *
+ * Returns the unregister, or `undefined` when the webServer service is
+ * unavailable — the host keeps running, only the HTTP API is missing.
+ */
+export declare function registerStreamRoute(server: unknown, log: EventLog): (() => void) | undefined;
 /** Delivers a revert instruction into the conversation (see index.ts wiring). */
 export type SessionSender = (sessionId: string, content: string) => Promise<{
     ok: boolean;

package/lib/events.js

@@ -224,6 +224,13 @@ export class EventLog {
     now;
     snapshotsDir;
     seq = -1; // lazily restored from the file on first append
+    /**
+     * Live subscribers, notified once per successfully appended event. They exist
+     * so a browser half can be pushed to instead of re-reading the whole JSONL on
+     * a timer; a subscriber that throws is dropped from the notification only, it
+     * never costs the append its event.
+     */
+    listeners = new Set();
     constructor(
     /** JSONL path; `undefined` disables event recording entirely. */
     filePath, now = Date.now, 
@@ -266,12 +273,34 @@ export class EventLog {
             if ((ev.kind === 'auto' || ev.kind === 'ask') && this.snapshotsDir !== undefined && files !== undefined) {
                 saveEventSnapshots(this.snapshotsDir, ev.id, files, input.baseDir, ev.sessionId, this.now);
             }
+            for (const listener of this.listeners) {
+                try {
+                    listener(ev);
+                }
+                catch {
+                    // A dead subscriber must not fail the append, and must not stop the others.
+                }
+            }
             return ev;
         }
         catch {
             return undefined; // best-effort only
         }
     }
+    /**
+     * Watch events as they are appended. The listener is called once per event,
+     * after the JSONL write, from inside `append` — so it runs on the gate's own
+     * decision path and must stay cheap and non-throwing.
+     *
+     * @param listener - receives each appended event.
+     * @returns the unsubscribe.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
     /** Events with `id > since`, optionally filtered to one session. */
     query({ sessionId, since } = {}) {
         if (this.filePath === undefined)
@@ -349,6 +378,7 @@ function readBody(req, limit = 1024 * 1024) {
     });
 }
 export const EVENTS_ROUTE = '/api/dsh-perm-gate/events';
+export const STREAM_ROUTE = '/api/dsh-perm-gate/stream';
 export const LEARNING_ROUTE = '/api/dsh-perm-gate/learning';
 export const HEALTH_ROUTE = '/api/dsh-perm-gate/health';
 export const NETWORK_ROUTE = '/api/dsh-perm-gate/network';
@@ -395,6 +425,104 @@ export function registerEventsRoute(server, log) {
         },
     });
 }
+/** Keep-alive cadence of {@link registerStreamRoute}: a comment line that keeps an idle stream from being reaped. */
+const STREAM_PING_MS = 15_000;
+/**
+ * Register `GET /api/dsh-perm-gate/stream?sessionId=&since=` on the webServer
+ * service: the same events {@link registerEventsRoute} serves, but pushed.
+ *
+ * The response is `text/event-stream`. On connect the backlog after `since` is
+ * written as one `data: {"events":[…],"backlog":true}` frame, then each event
+ * appended from that moment on is written as it lands as `data: {"events":[…]}` —
+ * so the browser half is never forced to re-read the whole JSONL on a timer.
+ * `: ping` comments hold the connection open while nothing is being decided.
+ *
+ * The session filter applies to both the backlog and the live pushes. Nothing
+ * is buffered for a disconnected client: it reconnects with its own cursor and
+ * the backlog frame restores it.
+ *
+ * Returns the unregister, or `undefined` when the webServer service is
+ * unavailable — the host keeps running, only the HTTP API is missing.
+ */
+export function registerStreamRoute(server, log) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: STREAM_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'GET') {
+                res.writeHead(405);
+                res.end();
+                return;
+            }
+            if (res.write === undefined) {
+                // A server that cannot stream: fail the handshake instead of hanging the browser's EventSource.
+                res.writeHead(500);
+                res.end();
+                return;
+            }
+            let sessionId;
+            let since;
+            try {
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                sessionId = url.searchParams.get('sessionId') ?? undefined;
+                const raw = url.searchParams.get('since');
+                if (raw !== null && raw !== '')
+                    since = Number.parseInt(raw, 10) || 0;
+            }
+            catch {
+                // unparseable URL: stream the unfiltered tail
+            }
+            const scoped = sessionId !== undefined && sessionId !== '';
+            res.writeHead(200, {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache, no-transform',
+                connection: 'keep-alive',
+                'x-accel-buffering': 'no',
+            });
+            const push = (events, backlog = false) => {
+                // The backlog frame is written even when it is empty: it marks where
+                // history stops, so the consumer never mistakes a live event for a replay.
+                if (events.length === 0 && !backlog)
+                    return;
+                try {
+                    res.write?.(`data: ${JSON.stringify(backlog ? { events, backlog: true } : { events })}\n\n`);
+                }
+                catch {
+                    // The socket died between the close event and this write; `close` owns the teardown.
+                }
+            };
+            push(log.query({ sessionId, since }), true);
+            const unsubscribe = log.subscribe((event) => {
+                if (scoped && event.sessionId !== sessionId)
+                    return;
+                push([event]);
+            });
+            const keepAlive = setInterval(() => {
+                try {
+                    res.write?.(': ping\n\n');
+                }
+                catch {
+                    // ignore: `close` owns the teardown
+                }
+            }, STREAM_PING_MS);
+            let closed = false;
+            const close = () => {
+                if (closed)
+                    return;
+                closed = true;
+                clearInterval(keepAlive);
+                unsubscribe();
+            };
+            res.on?.('close', close);
+            res.on?.('error', close);
+        },
+    });
+}
 /**
  * Register the review-page routes:
  * `GET  /diff?eventId=&path=`        → before/after line diff for one file

package/lib/index.js

@@ -1,16 +1,27 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { parse } from 'yaml';
-import { Config, RULES_NAMESPACE, RulesSchema, isRulesConfigured, readRulesFromSettings, resolveDshHome, resolveDataDir, resolveGatePresets, resolvePermissiveStrategies, resolveRulesFile } from './config.js';
-import { appendAllowToSettings, replaceAllowInSettings } from './allowlist.js';
+import { Config, resolveDshHome, resolveDataDir, ensureDataDir, resolveGatePresets, resolvePermissiveStrategies, resolveRulesFile } from './config.js';
 import { runDryRun } from './dry-run.js';
 import { registerDryRunRoute, registerEventsRoute, registerHealthRoute, registerLearningRoute, registerNetworkRoute, registerReceiverRoute, registerReviewRoutes, registerRulesRoute } from './events.js';
 import { buildReceiverInfo } from './receiver-info.js';
-import { readRulesView, readRulesViewFromSettings } from './rules-view.js';
+import { readRulesView } from './rules-view.js';
 import { PermGateRuntime } from './runtime.js';
 import { classifySessions, sweepSessionData } from './session-sweep.js';
 import { decideNetworkTarget } from './network.js';
 import { NetworkLifecycle } from './network-lifecycle.js';
+import { RuleWatcher } from './watch.js';
+// ─── Cold-start directory bootstrap ─────────────────────────────────────────
+// Ensure the plugin data directory exists BEFORE cordis calls apply().
+// The DSH framework (or other plugins) may scan dataDir during plugin
+// registration — before our apply() entry point runs. If the directory
+// is missing at that point, the scan throws and the plugin (or the
+// entire profile) fails to load.
+//
+// This is a belt-and-suspenders approach:
+//   1. Module-level: ensure dataDir exists at import time (earliest possible)
+//   2. Read paths: check dataDirReady() → return empty defaults if missing
+//   3. Write paths: call ensureDataDir() before first write
+ensureDataDir(resolveDataDir());
 export const name = 'dsh-perm-gate';
 /**
  * The `tools` service drives `tools/pre-execute`/`tools/result` (dsh-tools).
@@ -185,37 +196,6 @@ export function apply(ctx, config = {}) {
     // read-only). The default resolves to `$DSH_HOME` / `~/.dsh`, so a profile
     // entry that omits `config` still records events, snapshots and learning.
     const dataDir = resolveDataDir(typeof config.dshHome === 'string' ? config.dshHome : undefined);
-    // ─── Rules sources (dual-source: settings first, rulesFile fallback) ──
-    // The `dsh-perm-gate-rules` settings namespace is the primary rules store —
-    // the framework owns it, so the gate loads with no rules file on disk. A
-    // namespace still at bare defaults never shadows the file, and the first
-    // settings write seeds the file document along (implicit migration). Both
-    // references are filled in by the settings registration below; until then
-    // the file paths run exactly as before.
-    const rulesFilePath = resolveRulesFile(typeof config.rulesFile === 'string' ? config.rulesFile : undefined, dataDir);
-    let rulesFromSettings = () => ({});
-    const rulesScopeRef = { scope: undefined };
-    /** The raw file document, for seeding the namespace on its first write. */
-    const fileSeedDoc = () => {
-        try {
-            const text = readFileSync(rulesFilePath, 'utf8');
-            if (text.trim() === '')
-                return undefined;
-            return parse(text);
-        }
-        catch {
-            return undefined;
-        }
-    };
-    const settingsWrite = (write, fallback) => {
-        const scope = rulesScopeRef.scope;
-        if (scope === undefined)
-            return fallback();
-        void write(scope, fileSeedDoc()).catch((e) => {
-            console.warn('[dsh-perm-gate] settings rules write failed:', e);
-        });
-        return true;
-    };
     // Host model-group services (typed minimally; supplied by the dsh runtime
     // through the loader `inject` — dsh-approval-gate demonstrates the same
     // contract). The llm service backs the `host` receiver; agentDefaultModel
@@ -356,19 +336,8 @@ export function apply(ctx, config = {}) {
             : join(dataDir, 'learning.json'),
         // The rules document lives in the plugin's data dir by default, so a
         // `$DSH_HOME/perm-gate/rules.yml` the user writes is actually loaded without
-        // also having to declare `rulesFile` in the composition entry. It is the
-        // FALLBACK source: a configured `dsh-perm-gate-rules` namespace wins.
-        rulesFile: rulesFilePath,
-        // Settings-first rules: the live `dsh-perm-gate-rules` document when the
-        // namespace carries a real configuration, else undefined (file fallback).
-        readRulesDocument: () => readRulesFromSettings({ get: () => rulesFromSettings() }),
-        // Settings-backed allowlist writes; a falsy verdict (settings service
-        // absent) makes the runtime fall back to its own rules-file paths, and the
-        // namespace's watch triggers the reload once a write lands.
-        allowlistWriter: {
-            append: (pattern, reason) => settingsWrite((scope, seed) => appendAllowToSettings(scope, pattern, reason, seed), () => false),
-            replace: (patterns, reason) => settingsWrite((scope, seed) => replaceAllowInSettings(scope, patterns, reason, seed), () => false),
-        },
+        // also having to declare `rulesFile` in the composition entry.
+        rulesFile: resolveRulesFile(typeof config.rulesFile === 'string' ? config.rulesFile : undefined, dataDir),
         // The whole gate is scoped to the presets that opt into it (default: the
         // `permissive` tier this plugin adds); elsewhere it stands down entirely.
         gatePresets: resolveGatePresets(Array.isArray(config.gatePresets) ? config.gatePresets : undefined),
@@ -459,17 +428,15 @@ export function apply(ctx, config = {}) {
         },
         onChange: () => { },
         onScope: (scope) => {
-            // Seed the editable whitelist from the rules source only when the
-            // namespace carries no override yet, so the card shows the current allow
-            // patterns.
+            // Seed the editable whitelist from the rules file only when the namespace
+            // carries no override yet, so the card shows the current allow patterns.
             const surface = asSurface(scope.get());
             if (surface !== undefined && !Array.isArray(surface.allowlist)) {
                 const patterns = runtime.allowlist();
                 if (patterns.length > 0)
                     void scope.update({ allowlist: patterns.slice() });
             }
-            // Card edits -> namespace -> rules source (settings via the runtime's
-            // writer, else the rules file mirror) + reload.
+            // Card edits -> namespace -> rulesFile (mirror + reload).
             scope.watch(() => {
                 const next = asSurface(scope.get());
                 if (next !== undefined && Array.isArray(next.allowlist)) {
@@ -489,22 +456,6 @@ export function apply(ctx, config = {}) {
             });
         },
     });
-    // The rules namespace: the primary rules store (JSON twin of rules.yml).
-    // Every change recompiles the gate — the settings half of the hot reload
-    // that used to be a chokidar file watcher. `onScope` hands the live scope to
-    // the allowlist writers above; the seed entry is `{}`, so an untouched
-    // namespace reads as "not configured" and the file paths stay in force.
-    installSettingsSection(ctx, RULES_NAMESPACE, RulesSchema, {}, {
-        setSource: (source) => {
-            rulesFromSettings = source;
-        },
-        onChange: () => {
-            runtime.reload();
-        },
-        onScope: (scope) => {
-            rulesScopeRef.scope = scope;
-        },
-    });
     // Event feed HTTP API (best effort): the dsh webServer service exposes the
     // JSONL decision events to the browser half; without it events stay on disk.
     try {
@@ -567,18 +518,12 @@ export function apply(ctx, config = {}) {
             });
             if (offDryRun !== undefined)
                 ctx.effect(() => () => { offDryRun(); }, 'dsh-perm-gate: dry-run route');
-            // Permissions view: the document the gate is actually loading, shown so
-            // the panel is never editing rules it cannot display. Read-only, and
-            // resolved exactly as the gate resolves it — settings first, the file the
-            // fallback resolves to otherwise.
-            const offRules = registerRulesRoute(webServer, {
-                view: () => {
-                    const doc = rulesFromSettings();
-                    if (isRulesConfigured(doc))
-                        return readRulesViewFromSettings(doc);
-                    return readRulesView(rulesFilePath);
-                },
-            });
+            // Permissions YAML view: the document the gate is actually loading, shown
+            // so the panel is never editing a file it cannot display. Read-only, and
+            // resolved exactly as the gate resolves it — a view that resolved its own
+            // path could describe a different file than the one in force.
+            const rulesFilePath = resolveRulesFile(typeof config.rulesFile === 'string' ? config.rulesFile : undefined, dataDir);
+            const offRules = registerRulesRoute(webServer, { view: () => readRulesView(rulesFilePath) });
             if (offRules !== undefined)
                 ctx.effect(() => () => { offRules(); }, 'dsh-perm-gate: rules route');
             // Receiver projection for the settings card (provider/model catalog is
@@ -726,10 +671,23 @@ export function apply(ctx, config = {}) {
     networkRefs.snapshot = () => networkLifecycle.snapshot();
     if (networkRefs.appliedKey === undefined)
         networkRefs.appliedKey = networkKeyOf(current());
-    // ─── Rule hot reload ────────────────────────────────────────────────
-    // The file watcher (chokidar) is gone: the settings namespace is the primary
-    // rules store and its `scope.watch` recompiles the gate on every change
-    // (see the RULES_NAMESPACE registration above). A rules FILE edit is no
-    // longer picked up mid-session — the settings document is the source to edit.
+    // ─── 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/package.json

@@ -1,12 +1,12 @@
 {
   "name": "dsh-perm-gate",
-  "version": "3.0.0",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public",
-    "tag": "dsh-0.1.2"
+  "version": "4.1.0-beta.1",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "tag": "dsh-0.1.5"
   },
-  "description": "DSH permission-gate for the DeepSeek Harness 0.1.2+ line: a single self-sufficient, deterministic-first, fail-closed gate covering P0 hard-deny -> P1 session grant -> P2 static rule (allow/deny) chain -> P3 optional LLM semantic classifier -> P4 ask, with command whitelist/blacklist.",
+  "description": "DSH permission-gate for the DeepSeek Harness 0.1.5 line: a single self-sufficient, deterministic-first, fail-closed gate covering P0 hard-deny -> P1 session grant -> P2 static rule (allow/deny) chain -> P3 optional LLM semantic classifier -> P4 ask, with command whitelist/blacklist.",
   "type": "module",
   "files": [
     "lib",
@@ -66,8 +66,8 @@
     "dsh-perm-gate-patch-glyph": "./scripts/patch-permission-glyph.mjs"
   },
   "engines": {
-    "node": ">=20",
-    "dsh": ">=0.1.2-alpha.1 <0.2.0-0"
+    "node": ">=24",
+    "dsh": ">=0.1.5-rc.1 <0.2.0-0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1"
@@ -106,7 +106,8 @@
     "check:line": "node scripts/sync-0.1.5-line.mjs check",
     "release:latest": "npm publish --tag latest",
     "release:2x": "npm publish --tag 2.x",
-    "release:legacy": "npm publish --tag legacy"
+    "release:legacy": "npm publish --tag legacy",
+    "release:3x": "npm publish --tag dsh-0.1.5"
   },
   "license": "MIT",
   "repository": {