openclaw-safeclaw-plugin 0.1.2 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ Neurosymbolic governance plugin for OpenClaw AI agents. Validates every tool cal
 ## Install
 
 ```bash
-npm install openclaw-safeclaw-plugin
+openclaw plugins install openclaw-safeclaw-plugin
 ```
 
 ## Quick Start
@@ -13,7 +13,7 @@ npm install openclaw-safeclaw-plugin
 Install and go — the plugin connects to SafeClaw's hosted service by default:
 
 ```bash
-npm install openclaw-safeclaw-plugin
+openclaw plugins install openclaw-safeclaw-plugin
 ```
 
 No configuration needed. The default service URL is `https://api.safeclaw.eu/api/v1`.

package/cli.tsx

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import React from 'react';
+import { render } from 'ink';
+import { execSync } from 'child_process';
+import App from './tui/App.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === 'tui') {
+  render(React.createElement(App));
+} else if (command === 'restart-openclaw') {
+  try {
+    const output = execSync('openclaw daemon restart', { encoding: 'utf-8', timeout: 15000 });
+    console.log(output.trim());
+    console.log('OpenClaw daemon restarted successfully.');
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error('Failed to restart OpenClaw daemon:', message);
+    process.exit(1);
+  }
+} else {
+  console.log('Usage: safeclaw <command>');
+  console.log('');
+  console.log('Commands:');
+  console.log('  tui                Open the interactive SafeClaw settings TUI');
+  console.log('  restart-openclaw   Restart the OpenClaw daemon');
+  process.exit(0);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import React from 'react';
+import { render } from 'ink';
+import { execSync } from 'child_process';
+import App from './tui/App.js';
+const args = process.argv.slice(2);
+const command = args[0];
+if (command === 'tui') {
+    render(React.createElement(App));
+}
+else if (command === 'restart-openclaw') {
+    try {
+        const output = execSync('openclaw daemon restart', { encoding: 'utf-8', timeout: 15000 });
+        console.log(output.trim());
+        console.log('OpenClaw daemon restarted successfully.');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error('Failed to restart OpenClaw daemon:', message);
+        process.exit(1);
+    }
+}
+else {
+    console.log('Usage: safeclaw <command>');
+    console.log('');
+    console.log('Commands:');
+    console.log('  tui                Open the interactive SafeClaw settings TUI');
+    console.log('  restart-openclaw   Restart the OpenClaw daemon');
+    process.exit(0);
+}

package/dist/index.js

@@ -6,59 +6,8 @@
  * This plugin is a thin HTTP bridge that forwards OpenClaw events
  * to the SafeClaw service and acts on the responses.
  */
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
-function loadConfig() {
-    const defaults = {
-        serviceUrl: process.env.SAFECLAW_URL ?? 'https://api.safeclaw.eu/api/v1',
-        apiKey: process.env.SAFECLAW_API_KEY ?? '',
-        timeoutMs: parseInt(process.env.SAFECLAW_TIMEOUT_MS ?? '500', 10),
-        enabled: process.env.SAFECLAW_ENABLED !== 'false',
-        enforcement: process.env.SAFECLAW_ENFORCEMENT ?? 'enforce',
-        failMode: process.env.SAFECLAW_FAIL_MODE ?? 'closed',
-        agentId: process.env.SAFECLAW_AGENT_ID ?? '',
-        agentToken: process.env.SAFECLAW_AGENT_TOKEN ?? '',
-    };
-    // Try loading from config file
-    const configPath = join(homedir(), '.safeclaw', 'config.json');
-    if (existsSync(configPath)) {
-        try {
-            const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
-            if (raw.enabled === false)
-                defaults.enabled = false;
-            if (raw.remote?.serviceUrl)
-                defaults.serviceUrl = raw.remote.serviceUrl;
-            if (raw.remote?.apiKey)
-                defaults.apiKey = raw.remote.apiKey;
-            if (raw.remote?.timeoutMs)
-                defaults.timeoutMs = raw.remote.timeoutMs;
-            if (raw.enforcement?.mode)
-                defaults.enforcement = raw.enforcement.mode;
-            if (raw.enforcement?.failMode)
-                defaults.failMode = raw.enforcement.failMode;
-            if (raw.agentId)
-                defaults.agentId = raw.agentId;
-            if (raw.agentToken)
-                defaults.agentToken = raw.agentToken;
-        }
-        catch {
-            // Config file unreadable — use defaults
-        }
-    }
-    defaults.serviceUrl = defaults.serviceUrl.replace(/\/+$/, '');
-    const validModes = ['enforce', 'warn-only', 'audit-only', 'disabled'];
-    if (!validModes.includes(defaults.enforcement)) {
-        console.warn(`[SafeClaw] Invalid enforcement mode "${defaults.enforcement}", defaulting to "enforce"`);
-        defaults.enforcement = 'enforce';
-    }
-    const validFailModes = ['open', 'closed'];
-    if (!validFailModes.includes(defaults.failMode)) {
-        console.warn(`[SafeClaw] Invalid fail mode "${defaults.failMode}", defaulting to "closed"`);
-        defaults.failMode = 'closed';
-    }
-    return defaults;
-}
+import { loadConfig, configHash } from './tui/config.js';
+// --- Configuration ---
 const config = loadConfig();
 // --- HTTP Client ---
 async function post(path, body) {
@@ -139,8 +88,43 @@ export default {
             console.log('[SafeClaw] Plugin disabled');
             return;
         }
-        // Fire-and-forget startup health check
-        checkConnection().catch(() => { });
+        // Heartbeat watchdog — send config hash to service every 30s
+        const sendHeartbeat = async () => {
+            try {
+                await fetch(`${config.serviceUrl}/heartbeat`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        agentId: config.agentId || 'default',
+                        configHash: configHash(config),
+                        status: 'alive',
+                    }),
+                    signal: AbortSignal.timeout(config.timeoutMs),
+                });
+            }
+            catch {
+                // Heartbeat failure is non-fatal
+            }
+        };
+        // Start heartbeat after connection check
+        checkConnection().then(() => sendHeartbeat()).catch(() => { });
+        const heartbeatInterval = setInterval(sendHeartbeat, 30000);
+        // Clean shutdown: send shutdown heartbeat and clear interval
+        const shutdown = () => {
+            clearInterval(heartbeatInterval);
+            fetch(`${config.serviceUrl}/heartbeat`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    agentId: config.agentId || 'default',
+                    configHash: configHash(config),
+                    status: 'shutdown',
+                }),
+            }).catch(() => { });
+        };
+        process.on('exit', shutdown);
+        process.on('SIGINT', () => { shutdown(); process.exit(0); });
+        process.on('SIGTERM', () => { shutdown(); process.exit(0); });
         // THE GATE — constraint checking on every tool call
         api.on('before_tool_call', async (event, ctx) => {
             const r = await post('/evaluate/tool-call', {
@@ -156,6 +140,9 @@ export default {
             else if (r === null && config.failMode === 'closed' && config.enforcement === 'warn-only') {
                 console.warn(`[SafeClaw] Service unavailable at ${config.serviceUrl} (fail-closed mode, warn-only)`);
             }
+            else if (r === null && config.failMode === 'closed' && config.enforcement === 'audit-only') {
+                console.warn(`[SafeClaw] Service unavailable at ${config.serviceUrl} (fail-closed mode, audit-only)`);
+            }
             if (r?.block) {
                 if (config.enforcement === 'enforce') {
                     return { block: true, blockReason: r.reason };
@@ -190,8 +177,14 @@ export default {
             else if (r === null && config.failMode === 'closed' && config.enforcement === 'warn-only') {
                 console.warn('[SafeClaw] Service unavailable (fail-closed mode, warn-only)');
             }
-            if (r?.block && config.enforcement === 'enforce') {
-                return { cancel: true };
+            if (r?.block) {
+                if (config.enforcement === 'enforce') {
+                    return { cancel: true };
+                }
+                if (config.enforcement === 'warn-only') {
+                    console.warn(`[SafeClaw] Warning: ${r.reason}`);
+                }
+                // audit-only: logged server-side, no action here
             }
         }, { priority: 100 });
         // Async logging — fire-and-forget, no return value needed
@@ -213,8 +206,8 @@ export default {
                 toolName: event.toolName ?? event.tool_name,
                 params: event.params ?? {},
                 result: event.result ?? '',
-                success: event.success ?? true,
-            }).catch(() => { });
+                success: event.success ?? false,
+            }).catch((e) => console.warn('[SafeClaw] Failed to record tool result:', e));
         });
     },
 };

package/dist/tui/About.d.ts

@@ -0,0 +1 @@
+export default function About(): import("react/jsx-runtime").JSX.Element;

package/dist/tui/About.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text, Box } from 'ink';
+export default function About() {
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, children: "About" }) }), _jsx(Text, { children: "  SafeClaw Neurosymbolic Governance" }), _jsx(Text, { dimColor: true, children: "  Validates AI agent actions against OWL" }), _jsx(Text, { dimColor: true, children: "  ontologies and SHACL constraints." }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { children: "  Web:  " }), _jsx(Text, { color: "cyan", children: "https://safeclaw.eu" })] }), _jsxs(Box, { children: [_jsx(Text, { children: "  Docs: " }), _jsx(Text, { color: "cyan", children: "https://safeclaw.eu/docs" })] }), _jsxs(Box, { children: [_jsx(Text, { children: "  Repo: " }), _jsx(Text, { color: "cyan", children: "https://github.com/tendlyeu/SafeClaw" })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "  q to quit" }) })] }));
+}

package/dist/tui/App.d.ts

@@ -0,0 +1 @@
+export default function App(): import("react/jsx-runtime").JSX.Element;

package/dist/tui/App.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Text, Box, useInput, useApp } from 'ink';
+import { loadConfig } from './config.js';
+import Status from './Status.js';
+import Settings from './Settings.js';
+import About from './About.js';
+const TABS = ['Status', 'Settings', 'About'];
+export default function App() {
+    const { exit } = useApp();
+    const [tab, setTab] = useState('Status');
+    const [config, setConfig] = useState(loadConfig());
+    useInput((input, key) => {
+        if (input === 'q' && tab !== 'Settings') {
+            exit();
+            return;
+        }
+        if (key.tab || (input === '1' || input === '2' || input === '3')) {
+            if (input === '1')
+                setTab('Status');
+            else if (input === '2')
+                setTab('Settings');
+            else if (input === '3')
+                setTab('About');
+            else {
+                const idx = TABS.indexOf(tab);
+                setTab(TABS[(idx + 1) % TABS.length]);
+            }
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { borderStyle: "single", borderColor: "green", paddingX: 1, children: [_jsx(Text, { bold: true, color: "green", children: "SafeClaw " }), _jsx(Text, { dimColor: true, children: "v0.2.0" })] }), _jsxs(Box, { paddingX: 1, gap: 2, children: [TABS.map((t, i) => (_jsx(Text, { bold: tab === t, color: tab === t ? 'cyan' : 'white', dimColor: tab !== t, children: `${i + 1}:${t}` }, t))), _jsx(Text, { dimColor: true, children: " tab/1-3 to switch" })] }), _jsxs(Box, { marginTop: 1, children: [tab === 'Status' && _jsx(Status, { config: config }), tab === 'Settings' && (_jsx(Settings, { config: config, onConfigChange: setConfig })), tab === 'About' && _jsx(About, {})] })] }));
+}

package/dist/tui/Settings.d.ts

@@ -0,0 +1,7 @@
+import { type SafeClawConfig } from './config.js';
+interface SettingsProps {
+    config: SafeClawConfig;
+    onConfigChange: (config: SafeClawConfig) => void;
+}
+export default function Settings({ config, onConfigChange }: SettingsProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/tui/Settings.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Text, Box, useInput } from 'ink';
+import { saveConfig } from './config.js';
+const ENFORCEMENT_MODES = ['enforce', 'warn-only', 'audit-only', 'disabled'];
+const FAIL_MODES = ['closed', 'open'];
+const SETTINGS = [
+    { key: 'enabled', label: 'Enabled', type: 'toggle' },
+    { key: 'enforcement', label: 'Enforcement', type: 'cycle', values: ENFORCEMENT_MODES },
+    { key: 'failMode', label: 'Fail Mode', type: 'cycle', values: FAIL_MODES },
+    { key: 'serviceUrl', label: 'Service URL', type: 'text' },
+];
+export default function Settings({ config, onConfigChange }) {
+    const [selected, setSelected] = useState(0);
+    const [editing, setEditing] = useState(false);
+    const [editBuffer, setEditBuffer] = useState('');
+    const updateConfig = (patch) => {
+        const updated = { ...config, ...patch };
+        saveConfig(updated);
+        onConfigChange(updated);
+    };
+    useInput((input, key) => {
+        if (editing) {
+            if (key.return) {
+                updateConfig({ serviceUrl: editBuffer });
+                setEditing(false);
+            }
+            else if (key.escape) {
+                setEditing(false);
+            }
+            else if (key.backspace || key.delete) {
+                setEditBuffer(prev => prev.slice(0, -1));
+            }
+            else if (input && !key.ctrl && !key.meta) {
+                setEditBuffer(prev => prev + input);
+            }
+            return;
+        }
+        if (key.upArrow) {
+            setSelected(prev => Math.max(0, prev - 1));
+        }
+        else if (key.downArrow) {
+            setSelected(prev => Math.min(SETTINGS.length - 1, prev + 1));
+        }
+        else if (key.return || key.rightArrow || key.leftArrow) {
+            const setting = SETTINGS[selected];
+            if (setting.type === 'toggle') {
+                updateConfig({ enabled: !config.enabled });
+            }
+            else if (setting.type === 'cycle' && setting.values) {
+                const currentKey = setting.key;
+                const current = config[currentKey];
+                const idx = setting.values.indexOf(current);
+                const dir = key.leftArrow ? -1 : 1;
+                const next = setting.values[(idx + dir + setting.values.length) % setting.values.length];
+                updateConfig({ [currentKey]: next });
+            }
+            else if (setting.type === 'text' && key.return) {
+                setEditing(true);
+                setEditBuffer(config.serviceUrl);
+            }
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, children: "Settings" }) }), SETTINGS.map((setting, i) => {
+                const isSelected = i === selected;
+                const prefix = isSelected ? '▸ ' : '  ';
+                let value;
+                if (setting.key === 'enabled') {
+                    value = config.enabled ? 'ON' : 'OFF';
+                }
+                else if (setting.key === 'serviceUrl' && editing && isSelected) {
+                    value = editBuffer + '█';
+                }
+                else {
+                    value = String(config[setting.key]);
+                }
+                const showArrows = isSelected && setting.type === 'cycle';
+                return (_jsxs(Box, { children: [_jsxs(Text, { color: isSelected ? 'cyan' : undefined, bold: isSelected, children: [prefix, setting.label.padEnd(16)] }), showArrows && _jsx(Text, { dimColor: true, children: '◀ ' }), _jsx(Text, { color: setting.key === 'enabled'
+                                ? config.enabled ? 'green' : 'red'
+                                : undefined, children: value }), showArrows && _jsx(Text, { dimColor: true, children: ' ▶' })] }, setting.key));
+            }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: editing
+                        ? '  type to edit · enter to save · esc to cancel'
+                        : '  ↑↓ navigate · ←→ change · enter to edit URL · q quit' }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: '  Saves to ~/.safeclaw/config.json' }) })] }));
+}

package/dist/tui/Status.d.ts

@@ -0,0 +1,6 @@
+import { type SafeClawConfig } from './config.js';
+interface StatusProps {
+    config: SafeClawConfig;
+}
+export default function Status({ config }: StatusProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/tui/Status.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from 'react';
+import { Text, Box, useInput } from 'ink';
+import { exec } from 'child_process';
+export default function Status({ config }) {
+    const [health, setHealth] = useState(null);
+    const [error, setError] = useState(null);
+    const [lastCheck, setLastCheck] = useState(null);
+    const [openclawStatus, setOpenclawStatus] = useState('checking');
+    const [restartMsg, setRestartMsg] = useState(null);
+    const checkHealth = async () => {
+        try {
+            const res = await fetch(`${config.serviceUrl}/health`, {
+                signal: AbortSignal.timeout(config.timeoutMs * 2),
+            });
+            if (res.ok) {
+                const data = await res.json();
+                setHealth(data);
+                setError(null);
+            }
+            else {
+                setHealth(null);
+                setError(`HTTP ${res.status}`);
+            }
+        }
+        catch {
+            setHealth(null);
+            setError('Cannot connect');
+        }
+        setLastCheck(new Date());
+    };
+    const checkOpenClaw = () => {
+        exec('openclaw daemon status', { timeout: 10000 }, (err, stdout) => {
+            if (err) {
+                setOpenclawStatus('not running');
+            }
+            else {
+                const output = stdout.toLowerCase();
+                setOpenclawStatus(output.includes('running') ? 'running' : 'not running');
+            }
+        });
+    };
+    const restartOpenClaw = () => {
+        setRestartMsg('Restarting...');
+        exec('openclaw daemon restart', { timeout: 15000 }, (err) => {
+            if (err) {
+                setRestartMsg('Restart failed');
+            }
+            else {
+                setRestartMsg('Restarted');
+                checkOpenClaw();
+            }
+            setTimeout(() => setRestartMsg(null), 3000);
+        });
+    };
+    useEffect(() => {
+        checkHealth();
+        checkOpenClaw();
+        const interval = setInterval(() => {
+            checkHealth();
+            checkOpenClaw();
+        }, 10000);
+        return () => clearInterval(interval);
+    }, []);
+    useInput((input) => {
+        if (input === 'r') {
+            restartOpenClaw();
+        }
+    });
+    const connected = health !== null;
+    const dot = '●';
+    const serviceDotColor = connected ? 'green' : 'red';
+    const serviceText = connected
+        ? `Connected (${config.serviceUrl.replace(/^https?:\/\//, '').replace(/\/api\/v1$/, '')})`
+        : error ?? 'Disconnected';
+    const openclawDotColor = openclawStatus === 'running' ? 'green' : openclawStatus === 'checking' ? 'yellow' : 'red';
+    const openclawText = openclawStatus === 'checking' ? 'Checking...'
+        : openclawStatus === 'running' ? 'Running'
+            : 'Not running';
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, children: "Status" }) }), _jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: '  Service     ' }), _jsxs(Text, { color: serviceDotColor, children: [dot, " "] }), _jsx(Text, { children: serviceText })] }), _jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: '  OpenClaw    ' }), _jsxs(Text, { color: openclawDotColor, children: [dot, " "] }), _jsx(Text, { children: openclawText }), restartMsg && _jsx(Text, { dimColor: true, children: `  (${restartMsg})` })] }), _jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: '  Enforcement  ' }), _jsx(Text, { children: config.enforcement })] }), _jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: '  Fail Mode    ' }), _jsx(Text, { children: config.failMode })] }), _jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: '  Enabled      ' }), _jsx(Text, { color: config.enabled ? 'green' : 'red', children: config.enabled ? 'ON' : 'OFF' })] }), health?.version && (_jsxs(Box, { marginTop: 1, children: [_jsx(Text, { dimColor: true, children: '  Service v' }), _jsx(Text, { children: health.version })] })), lastCheck && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { dimColor: true, children: ['  Last check: ', lastCheck.toLocaleTimeString()] }) })), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { dimColor: true, children: '  Press ' }), _jsx(Text, { bold: true, children: "r" }), _jsx(Text, { dimColor: true, children: ' to restart OpenClaw daemon' })] })] }));
+}

package/dist/tui/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SafeClaw shared configuration module.
+ *
+ * Used by both the OpenClaw plugin (index.ts) and the TUI.
+ * Reads ~/.safeclaw/config.json, applies env-var overrides,
+ * and exposes helpers for saving and hashing config state.
+ */
+export interface SafeClawConfig {
+    serviceUrl: string;
+    apiKey: string;
+    timeoutMs: number;
+    enabled: boolean;
+    enforcement: 'enforce' | 'warn-only' | 'audit-only' | 'disabled';
+    failMode: 'open' | 'closed';
+    agentId: string;
+    agentToken: string;
+}
+export declare const CONFIG_PATH: string;
+export declare function loadConfig(): SafeClawConfig;
+/**
+ * Persist managed config fields back to ~/.safeclaw/config.json.
+ * Reads the existing file (if any), merges the fields SafeClaw manages,
+ * and writes the result. Fields not managed by SafeClaw are preserved.
+ */
+export declare function saveConfig(config: SafeClawConfig): void;
+/**
+ * SHA-256 hash of the four TUI-managed config fields.
+ * Used to detect whether the on-disk config has drifted from the in-memory state.
+ */
+export declare function configHash(config: SafeClawConfig): string;

package/dist/tui/config.js

@@ -0,0 +1,123 @@
+/**
+ * SafeClaw shared configuration module.
+ *
+ * Used by both the OpenClaw plugin (index.ts) and the TUI.
+ * Reads ~/.safeclaw/config.json, applies env-var overrides,
+ * and exposes helpers for saving and hashing config state.
+ */
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import crypto from 'crypto';
+// --- Constants ---
+export const CONFIG_PATH = join(homedir(), '.safeclaw', 'config.json');
+// --- Functions ---
+export function loadConfig() {
+    const defaults = {
+        serviceUrl: 'https://api.safeclaw.eu/api/v1',
+        apiKey: '',
+        timeoutMs: 500,
+        enabled: true,
+        enforcement: 'enforce',
+        failMode: 'closed',
+        agentId: '',
+        agentToken: '',
+    };
+    // Load from config file first
+    if (existsSync(CONFIG_PATH)) {
+        try {
+            const raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+            if (raw.enabled === false)
+                defaults.enabled = false;
+            if (raw.remote?.serviceUrl)
+                defaults.serviceUrl = raw.remote.serviceUrl;
+            if (raw.remote?.apiKey)
+                defaults.apiKey = raw.remote.apiKey;
+            if (raw.remote?.timeoutMs)
+                defaults.timeoutMs = raw.remote.timeoutMs;
+            if (raw.enforcement?.mode)
+                defaults.enforcement = raw.enforcement.mode;
+            if (raw.enforcement?.failMode)
+                defaults.failMode = raw.enforcement.failMode;
+            if (raw.agentId)
+                defaults.agentId = raw.agentId;
+            if (raw.agentToken)
+                defaults.agentToken = raw.agentToken;
+        }
+        catch {
+            // Config file unreadable — use defaults
+        }
+    }
+    // Env vars override config file
+    if (process.env.SAFECLAW_URL)
+        defaults.serviceUrl = process.env.SAFECLAW_URL;
+    if (process.env.SAFECLAW_API_KEY)
+        defaults.apiKey = process.env.SAFECLAW_API_KEY;
+    if (process.env.SAFECLAW_TIMEOUT_MS)
+        defaults.timeoutMs = parseInt(process.env.SAFECLAW_TIMEOUT_MS, 10);
+    if (process.env.SAFECLAW_ENABLED === 'false')
+        defaults.enabled = false;
+    if (process.env.SAFECLAW_ENFORCEMENT)
+        defaults.enforcement = process.env.SAFECLAW_ENFORCEMENT;
+    if (process.env.SAFECLAW_FAIL_MODE)
+        defaults.failMode = process.env.SAFECLAW_FAIL_MODE;
+    if (process.env.SAFECLAW_AGENT_ID)
+        defaults.agentId = process.env.SAFECLAW_AGENT_ID;
+    if (process.env.SAFECLAW_AGENT_TOKEN)
+        defaults.agentToken = process.env.SAFECLAW_AGENT_TOKEN;
+    defaults.serviceUrl = defaults.serviceUrl.replace(/\/+$/, '');
+    const validModes = ['enforce', 'warn-only', 'audit-only', 'disabled'];
+    if (!validModes.includes(defaults.enforcement)) {
+        console.warn(`[SafeClaw] Invalid enforcement mode "${defaults.enforcement}", defaulting to "enforce"`);
+        defaults.enforcement = 'enforce';
+    }
+    const validFailModes = ['open', 'closed'];
+    if (!validFailModes.includes(defaults.failMode)) {
+        console.warn(`[SafeClaw] Invalid fail mode "${defaults.failMode}", defaulting to "closed"`);
+        defaults.failMode = 'closed';
+    }
+    return defaults;
+}
+/**
+ * Persist managed config fields back to ~/.safeclaw/config.json.
+ * Reads the existing file (if any), merges the fields SafeClaw manages,
+ * and writes the result. Fields not managed by SafeClaw are preserved.
+ */
+export function saveConfig(config) {
+    let existing = {};
+    if (existsSync(CONFIG_PATH)) {
+        try {
+            existing = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+        }
+        catch {
+            // Unreadable — start fresh
+        }
+    }
+    // Merge managed fields into existing structure
+    existing.enabled = config.enabled;
+    if (!existing.remote || typeof existing.remote !== 'object') {
+        existing.remote = {};
+    }
+    existing.remote.serviceUrl = config.serviceUrl;
+    if (!existing.enforcement || typeof existing.enforcement !== 'object') {
+        existing.enforcement = {};
+    }
+    existing.enforcement.mode = config.enforcement;
+    existing.enforcement.failMode = config.failMode;
+    // Ensure parent directory exists
+    mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
+}
+/**
+ * SHA-256 hash of the four TUI-managed config fields.
+ * Used to detect whether the on-disk config has drifted from the in-memory state.
+ */
+export function configHash(config) {
+    const payload = JSON.stringify({
+        enabled: config.enabled,
+        enforcement: config.enforcement,
+        failMode: config.failMode,
+        serviceUrl: config.serviceUrl,
+    });
+    return crypto.createHash('sha256').update(payload).digest('hex');
+}