openclaw-safeclaw-plugin 0.1.2 → 0.2.0

package/cli.tsx

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import React from 'react';
+import { render } from 'ink';
+import App from './tui/App.js';
+
+const args = process.argv.slice(2);
+
+if (args[0] !== 'tui') {
+  console.log('Usage: safeclaw tui');
+  console.log('');
+  console.log('Opens the interactive SafeClaw settings TUI.');
+  process.exit(0);
+}
+
+render(React.createElement(App));

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import React from 'react';
+import { render } from 'ink';
+import App from './tui/App.js';
+const args = process.argv.slice(2);
+if (args[0] !== 'tui') {
+    console.log('Usage: safeclaw tui');
+    console.log('');
+    console.log('Opens the interactive SafeClaw settings TUI.');
+    process.exit(0);
+}
+render(React.createElement(App));

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,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from 'react';
+import { Text, Box } from 'ink';
+export default function Status({ config }) {
+    const [health, setHealth] = useState(null);
+    const [error, setError] = useState(null);
+    const [lastCheck, setLastCheck] = 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());
+    };
+    useEffect(() => {
+        checkHealth();
+        const interval = setInterval(checkHealth, 10000);
+        return () => clearInterval(interval);
+    }, []);
+    const connected = health !== null;
+    const dot = '●';
+    const dotColor = connected ? 'green' : 'red';
+    const statusText = connected
+        ? `Connected (${config.serviceUrl.replace(/^https?:\/\//, '').replace(/\/api\/v1$/, '')})`
+        : error ?? 'Disconnected';
+    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: dotColor, children: [dot, " "] }), _jsx(Text, { children: statusText })] }), _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()] }) }))] }));
+}

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');
+}

package/index.ts

@@ -7,70 +7,10 @@
  * to the SafeClaw service and acts on the responses.
  */
 
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
+import { loadConfig, configHash } from './tui/config.js';
 
 // --- Configuration ---
 
-interface SafeClawPluginConfig {
-  serviceUrl: string;
-  apiKey: string;
-  timeoutMs: number;
-  enabled: boolean;
-  enforcement: 'enforce' | 'warn-only' | 'audit-only' | 'disabled';
-  failMode: 'open' | 'closed';
-  agentId: string;
-  agentToken: string;
-}
-
-function loadConfig(): SafeClawPluginConfig {
-  const defaults: SafeClawPluginConfig = {
-    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 as SafeClawPluginConfig['enforcement']) ?? 'enforce',
-    failMode: (process.env.SAFECLAW_FAIL_MODE as SafeClawPluginConfig['failMode']) ?? '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'] as const;
-  if (!validModes.includes(defaults.enforcement as any)) {
-    console.warn(`[SafeClaw] Invalid enforcement mode "${defaults.enforcement}", defaulting to "enforce"`);
-    defaults.enforcement = 'enforce';
-  }
-
-  const validFailModes = ['open', 'closed'] as const;
-  if (!validFailModes.includes(defaults.failMode as any)) {
-    console.warn(`[SafeClaw] Invalid fail mode "${defaults.failMode}", defaulting to "closed"`);
-    defaults.failMode = 'closed';
-  }
-
-  return defaults;
-}
-
 const config = loadConfig();
 
 // --- HTTP Client ---
@@ -175,8 +115,44 @@ export default {
       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: PluginEvent, ctx: PluginContext) => {
@@ -192,6 +168,8 @@ export default {
         return { block: true, blockReason: `SafeClaw service unavailable at ${config.serviceUrl} (fail-closed)` };
       } 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') {
@@ -230,8 +208,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 });
 
@@ -256,8 +240,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/package.json

@@ -1,10 +1,13 @@
 {
   "name": "openclaw-safeclaw-plugin",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "SafeClaw Neurosymbolic Governance plugin for OpenClaw — validates AI agent actions against OWL ontologies and SHACL constraints",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "bin": {
+    "safeclaw": "dist/cli.js"
+  },
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
@@ -13,6 +16,8 @@
   "files": [
     "dist/",
     "index.ts",
+    "cli.tsx",
+    "tui/",
     "SKILL.md",
     "README.md"
   ],
@@ -40,10 +45,17 @@
   },
   "author": "Tendly EU",
   "devDependencies": {
-    "typescript": "^5.4.0",
-    "@types/node": "^20.0.0"
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.2.14",
+    "typescript": "^5.4.0"
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "ink": "^6.8.0",
+    "ink-select-input": "^6.2.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^19.2.4"
   }
 }

package/tui/About.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import { Text, Box } from 'ink';
+
+export default function About() {
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Box marginBottom={1}>
+        <Text bold>About</Text>
+      </Box>
+      <Text>  SafeClaw Neurosymbolic Governance</Text>
+      <Text dimColor>  Validates AI agent actions against OWL</Text>
+      <Text dimColor>  ontologies and SHACL constraints.</Text>
+      <Box marginTop={1}>
+        <Text>  Web:  </Text>
+        <Text color="cyan">https://safeclaw.eu</Text>
+      </Box>
+      <Box>
+        <Text>  Docs: </Text>
+        <Text color="cyan">https://safeclaw.eu/docs</Text>
+      </Box>
+      <Box>
+        <Text>  Repo: </Text>
+        <Text color="cyan">https://github.com/tendlyeu/SafeClaw</Text>
+      </Box>
+      <Box marginTop={1}>
+        <Text dimColor>  q to quit</Text>
+      </Box>
+    </Box>
+  );
+}

package/tui/App.tsx

@@ -0,0 +1,65 @@
+import React, { useState } from 'react';
+import { Text, Box, useInput, useApp } from 'ink';
+import { loadConfig, type SafeClawConfig } from './config.js';
+import Status from './Status.js';
+import Settings from './Settings.js';
+import About from './About.js';
+
+const TABS = ['Status', 'Settings', 'About'] as const;
+type Tab = typeof TABS[number];
+
+export default function App() {
+  const { exit } = useApp();
+  const [tab, setTab] = useState<Tab>('Status');
+  const [config, setConfig] = useState<SafeClawConfig>(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 (
+    <Box flexDirection="column">
+      {/* Header */}
+      <Box borderStyle="single" borderColor="green" paddingX={1}>
+        <Text bold color="green">SafeClaw </Text>
+        <Text dimColor>v0.2.0</Text>
+      </Box>
+
+      {/* Tab bar */}
+      <Box paddingX={1} gap={2}>
+        {TABS.map((t, i) => (
+          <Text
+            key={t}
+            bold={tab === t}
+            color={tab === t ? 'cyan' : 'white'}
+            dimColor={tab !== t}
+          >
+            {`${i + 1}:${t}`}
+          </Text>
+        ))}
+        <Text dimColor> tab/1-3 to switch</Text>
+      </Box>
+
+      {/* Content */}
+      <Box marginTop={1}>
+        {tab === 'Status' && <Status config={config} />}
+        {tab === 'Settings' && (
+          <Settings config={config} onConfigChange={setConfig} />
+        )}
+        {tab === 'About' && <About />}
+      </Box>
+    </Box>
+  );
+}

package/tui/Settings.tsx

@@ -0,0 +1,130 @@
+import React, { useState } from 'react';
+import { Text, Box, useInput } from 'ink';
+import { type SafeClawConfig, saveConfig } from './config.js';
+
+interface SettingsProps {
+  config: SafeClawConfig;
+  onConfigChange: (config: SafeClawConfig) => void;
+}
+
+const ENFORCEMENT_MODES = ['enforce', 'warn-only', 'audit-only', 'disabled'] as const;
+const FAIL_MODES = ['closed', 'open'] as const;
+
+interface SettingItem {
+  key: string;
+  label: string;
+  type: 'toggle' | 'cycle' | 'text';
+  values?: readonly string[];
+}
+
+const SETTINGS: SettingItem[] = [
+  { 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 }: SettingsProps) {
+  const [selected, setSelected] = useState(0);
+  const [editing, setEditing] = useState(false);
+  const [editBuffer, setEditBuffer] = useState('');
+
+  const updateConfig = (patch: Partial<SafeClawConfig>) => {
+    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 as 'enforcement' | 'failMode';
+        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 (
+    <Box flexDirection="column" paddingX={1}>
+      <Box marginBottom={1}>
+        <Text bold>Settings</Text>
+      </Box>
+
+      {SETTINGS.map((setting, i) => {
+        const isSelected = i === selected;
+        const prefix = isSelected ? '▸ ' : '  ';
+        let value: string;
+
+        if (setting.key === 'enabled') {
+          value = config.enabled ? 'ON' : 'OFF';
+        } else if (setting.key === 'serviceUrl' && editing && isSelected) {
+          value = editBuffer + '█';
+        } else {
+          value = String(config[setting.key as keyof SafeClawConfig]);
+        }
+
+        const showArrows = isSelected && setting.type === 'cycle';
+
+        return (
+          <Box key={setting.key}>
+            <Text color={isSelected ? 'cyan' : undefined} bold={isSelected}>
+              {prefix}
+              {setting.label.padEnd(16)}
+            </Text>
+            {showArrows && <Text dimColor>{'◀ '}</Text>}
+            <Text
+              color={
+                setting.key === 'enabled'
+                  ? config.enabled ? 'green' : 'red'
+                  : undefined
+              }
+            >
+              {value}
+            </Text>
+            {showArrows && <Text dimColor>{' ▶'}</Text>}
+          </Box>
+        );
+      })}
+
+      <Box marginTop={1}>
+        <Text dimColor>
+          {editing
+            ? '  type to edit · enter to save · esc to cancel'
+            : '  ↑↓ navigate · ←→ change · enter to edit URL · q quit'}
+        </Text>
+      </Box>
+
+      <Box>
+        <Text dimColor>{'  Saves to ~/.safeclaw/config.json'}</Text>
+      </Box>
+    </Box>
+  );
+}

package/tui/Status.tsx

@@ -0,0 +1,99 @@
+import React, { useState, useEffect } from 'react';
+import { Text, Box } from 'ink';
+import { type SafeClawConfig } from './config.js';
+
+interface StatusProps {
+  config: SafeClawConfig;
+}
+
+interface HealthData {
+  status: string;
+  version?: string;
+  engine_ready?: boolean;
+}
+
+export default function Status({ config }: StatusProps) {
+  const [health, setHealth] = useState<HealthData | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [lastCheck, setLastCheck] = useState<Date | null>(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() as HealthData;
+        setHealth(data);
+        setError(null);
+      } else {
+        setHealth(null);
+        setError(`HTTP ${res.status}`);
+      }
+    } catch {
+      setHealth(null);
+      setError('Cannot connect');
+    }
+    setLastCheck(new Date());
+  };
+
+  useEffect(() => {
+    checkHealth();
+    const interval = setInterval(checkHealth, 10000);
+    return () => clearInterval(interval);
+  }, []);
+
+  const connected = health !== null;
+  const dot = '●';
+  const dotColor = connected ? 'green' : 'red';
+  const statusText = connected
+    ? `Connected (${config.serviceUrl.replace(/^https?:\/\//, '').replace(/\/api\/v1$/, '')})`
+    : error ?? 'Disconnected';
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Box marginBottom={1}>
+        <Text bold>Status</Text>
+      </Box>
+
+      <Box>
+        <Text dimColor>{'  Service     '}</Text>
+        <Text color={dotColor}>{dot} </Text>
+        <Text>{statusText}</Text>
+      </Box>
+
+      <Box>
+        <Text dimColor>{'  Enforcement  '}</Text>
+        <Text>{config.enforcement}</Text>
+      </Box>
+
+      <Box>
+        <Text dimColor>{'  Fail Mode    '}</Text>
+        <Text>{config.failMode}</Text>
+      </Box>
+
+      <Box>
+        <Text dimColor>{'  Enabled      '}</Text>
+        <Text color={config.enabled ? 'green' : 'red'}>
+          {config.enabled ? 'ON' : 'OFF'}
+        </Text>
+      </Box>
+
+      {health?.version && (
+        <Box marginTop={1}>
+          <Text dimColor>{'  Service v'}</Text>
+          <Text>{health.version}</Text>
+        </Box>
+      )}
+
+      {lastCheck && (
+        <Box marginTop={1}>
+          <Text dimColor>
+            {'  Last check: '}
+            {lastCheck.toLocaleTimeString()}
+          </Text>
+        </Box>
+      )}
+    </Box>
+  );
+}

package/tui/config.ts

@@ -0,0 +1,136 @@
+/**
+ * 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';
+
+// --- Types ---
+
+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;
+}
+
+// --- Constants ---
+
+export const CONFIG_PATH = join(homedir(), '.safeclaw', 'config.json');
+
+// --- Functions ---
+
+export function loadConfig(): SafeClawConfig {
+  const defaults: SafeClawConfig = {
+    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 as SafeClawConfig['enforcement'];
+  if (process.env.SAFECLAW_FAIL_MODE) defaults.failMode = process.env.SAFECLAW_FAIL_MODE as SafeClawConfig['failMode'];
+  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'] as const;
+  if (!validModes.includes(defaults.enforcement as any)) {
+    console.warn(`[SafeClaw] Invalid enforcement mode "${defaults.enforcement}", defaulting to "enforce"`);
+    defaults.enforcement = 'enforce';
+  }
+
+  const validFailModes = ['open', 'closed'] as const;
+  if (!validFailModes.includes(defaults.failMode as any)) {
+    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: SafeClawConfig): void {
+  let existing: Record<string, unknown> = {};
+  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 as Record<string, unknown>).serviceUrl = config.serviceUrl;
+
+  if (!existing.enforcement || typeof existing.enforcement !== 'object') {
+    existing.enforcement = {};
+  }
+  (existing.enforcement as Record<string, unknown>).mode = config.enforcement;
+  (existing.enforcement as Record<string, unknown>).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: SafeClawConfig): string {
+  const payload = JSON.stringify({
+    enabled: config.enabled,
+    enforcement: config.enforcement,
+    failMode: config.failMode,
+    serviceUrl: config.serviceUrl,
+  });
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}