shieldcortex 3.2.1 → 3.2.2

package/dist/index.js

@@ -10,6 +10,7 @@
  *   shieldcortex --mode mcp              # Start MCP server
  *   shieldcortex --mode api              # Start visualization API server
  *   shieldcortex --mode both             # Start both servers
+ *   shieldcortex --mode worker           # Start headless background worker
  *   shieldcortex --dashboard             # Start API + Dashboard (admin panel)
  *   shieldcortex --db /path/to.db        # Custom database path
  *   shieldcortex scan "text"             # Quick content scan (no MCP/ML)
@@ -24,9 +25,10 @@
  *   shieldcortex hook pre-compact        # Run pre-compact hook (for settings.json)
  *   shieldcortex hook session-start      # Run session-start hook (for settings.json)
  *   shieldcortex hook session-end        # Run session-end hook (for settings.json)
- *   shieldcortex service install         # Auto-start dashboard on login
- *   shieldcortex service repair          # Rebuild auto-start service with current install path
- *   shieldcortex service uninstall       # Remove auto-start
+ *   shieldcortex service install         # Install persistent ShieldCortex service
+ *   shieldcortex service install --headless  # Recommended for always-on servers
+ *   shieldcortex service repair          # Rebuild persistent service with current install path
+ *   shieldcortex service uninstall       # Remove persistent service
  *   shieldcortex service status          # Check service status
  *   shieldcortex openclaw install        # Install OpenClaw hook
  *   shieldcortex openclaw uninstall      # Remove OpenClaw hook
@@ -107,12 +109,18 @@ function parseArgs() {
         }
         else if (args[i] === '--mode' && args[i + 1]) {
             const mode = args[i + 1].toLowerCase();
-            if (mode === 'mcp' || mode === 'api' || mode === 'both' || mode === 'dashboard') {
+            if (mode === 'mcp' || mode === 'api' || mode === 'both' || mode === 'dashboard' || mode === 'worker') {
                 result.mode = mode;
             }
             i++;
         }
     }
+    if (args[0] === 'dashboard')
+        result.mode = 'dashboard';
+    if (args[0] === 'api')
+        result.mode = 'api';
+    if (args[0] === 'worker')
+        result.mode = 'worker';
     return result;
 }
 /**
@@ -298,6 +306,33 @@ function startDashboard() {
     });
     return dashboard;
 }
+async function startWorkerMode(dbPath) {
+    const { initDatabase } = await import('./database/init.js');
+    const { startDefaultWorker } = await import('./worker/brain-worker.js');
+    initDatabase(dbPath);
+    startDefaultWorker();
+    console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║             ShieldCortex Worker Service                     ║
+╠══════════════════════════════════════════════════════════════╣
+║  Running headless background worker                         ║
+║  Heartbeats keep this device online in ShieldCortex Cloud   ║
+║  Sync retries and graph maintenance remain active           ║
+╚══════════════════════════════════════════════════════════════╝
+  `);
+    const keepAlive = setInterval(() => {
+        // Intentionally empty. BrainWorker timers are unref()'d, so the service
+        // needs one referenced timer to remain alive as a daemon.
+    }, 60 * 60 * 1000);
+    const shutdown = (signal) => {
+        console.log(`\nReceived ${signal}, stopping ShieldCortex worker...`);
+        clearInterval(keepAlive);
+        stopDefaultWorker();
+        process.exit(0);
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
 function checkLocalHttp(url, expectedStatus = [200], timeoutMs = 1200) {
     return new Promise((resolve) => {
         const req = http.get(url, { timeout: timeoutMs }, (res) => {
@@ -339,6 +374,7 @@ ${bold}COMMANDS${reset}
   ${cyan}scan-skill${reset} <path>     Scan an agent instruction file for threats
   ${cyan}scan-skills${reset}           Scan all installed skills/hooks
   ${cyan}dashboard${reset}             Open the local security dashboard
+  ${cyan}worker${reset}                Run headless background sync + heartbeat worker
   ${cyan}status${reset}                Show current protection status
   ${cyan}doctor${reset}                Diagnose installation issues
   ${cyan}quickstart${reset} [target]    Detect the fastest setup path
@@ -364,6 +400,7 @@ ${bold}EXAMPLES${reset}
   shieldcortex scan "ignore previous instructions"
   shieldcortex scan-skill ~/.claude/skills/my-skill/SKILL.md
   shieldcortex dashboard
+  shieldcortex worker
   shieldcortex license activate sc_pro_...
   shieldcortex config --cloud-enable --cloud-api-key <key>
   shieldcortex cloud sync --full
@@ -438,7 +475,7 @@ ${bold}DOCS${reset}
     }
     // Handle "service" subcommand before normal mode parsing
     if (process.argv[2] === 'service') {
-        await handleServiceCommand(process.argv[3] || '');
+        await handleServiceCommand(process.argv[3] || '', process.argv.slice(4));
         return;
     }
     // Handle "config" subcommand (cloud sync configuration)
@@ -633,7 +670,7 @@ ${bold}DOCS${reset}
         'doctor', 'quickstart', 'setup', 'install', 'migrate', 'uninstall', 'hook',
         'openclaw', 'clawdbot', 'copilot', 'service', 'config', 'status',
         'graph', 'license', 'licence', 'audit', 'iron-dome', 'scan', 'cloud',
-        'scan-skill', 'scan-skills', 'dashboard', 'api',
+        'scan-skill', 'scan-skills', 'dashboard', 'api', 'worker',
     ]);
     const arg = process.argv[2];
     if (arg && !arg.startsWith('-') && !knownCommands.has(arg)) {
@@ -708,6 +745,10 @@ ${bold}DOCS${reset}
         }
         await startMcpServer(dbPath);
     }
+    else if (mode === 'worker') {
+        console.log('Starting ShieldCortex in headless worker mode...');
+        await startWorkerMode(dbPath);
+    }
     else {
         // MCP mode (default) - for Claude Code integration
         await startMcpServer(dbPath);

package/dist/service/install.d.ts

@@ -1,15 +1,20 @@
 /**
- * Cross-platform service installer for ShieldCortex dashboard auto-start.
+ * Cross-platform service installer for persistent ShieldCortex background service.
  *
  * Supports:
  *  - macOS: LaunchAgent plist
  *  - Linux: systemd user service
  *  - Windows: VBS script in Startup folder
  */
-export declare function installService(): Promise<void>;
-export declare function repairService(): Promise<void>;
+import { type ServiceMode } from './templates.js';
+interface ServiceOptions {
+    mode?: ServiceMode;
+}
+export declare function installService(options?: ServiceOptions): Promise<void>;
+export declare function repairService(options?: ServiceOptions): Promise<void>;
 export declare function uninstallService(options?: {
     cleanLogs?: boolean;
 }): Promise<void>;
 export declare function serviceStatus(): Promise<void>;
-export declare function handleServiceCommand(subcommand: string): Promise<void>;
+export declare function handleServiceCommand(subcommand: string, args?: string[]): Promise<void>;
+export {};

package/dist/service/install.js

@@ -1,5 +1,5 @@
 /**
- * Cross-platform service installer for ShieldCortex dashboard auto-start.
+ * Cross-platform service installer for persistent ShieldCortex background service.
  *
  * Supports:
  *  - macOS: LaunchAgent plist
@@ -21,7 +21,13 @@ function detectPlatform() {
         default: return 'linux';
     }
 }
-function getServiceConfig() {
+function detectDefaultServiceMode(platform) {
+    if (platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+        return 'worker';
+    }
+    return 'dashboard';
+}
+function getServiceConfig(mode) {
     const logsDir = path.join(os.homedir(), '.shieldcortex', 'logs');
     fs.mkdirSync(logsDir, { recursive: true });
     return {
@@ -29,33 +35,40 @@ function getServiceConfig() {
         nodeBinDir: path.dirname(process.execPath),
         entryPoint: path.resolve(__dirname, '..', 'index.js'),
         logsDir,
+        mode,
     };
 }
 function inspectServiceEntryPoint(platform, servicePath) {
     if (!fs.existsSync(servicePath)) {
-        return { entryPoint: null, stale: false };
+        return { entryPoint: null, stale: false, mode: null };
     }
     try {
         const content = fs.readFileSync(servicePath, 'utf-8');
         let entryPoint = null;
+        let mode = null;
         if (platform === 'macos') {
             const matches = [...content.matchAll(/<string>([^<]+)<\/string>/g)].map((match) => match[1]);
             entryPoint = matches.find((value) => value.endsWith('index.js')) ?? null;
+            mode = matches.find((value) => value === 'dashboard' || value === 'api' || value === 'worker') ?? null;
         }
         else if (platform === 'linux') {
             const match = content.match(/ExecStart=\S+\s+(\S+index\.js)/);
             entryPoint = match?.[1] ?? null;
+            const modeMatch = content.match(/ExecStart=\S+\s+\S+index\.js\s+--mode\s+(dashboard|api|worker)/);
+            mode = modeMatch?.[1] ?? null;
         }
         else {
             const match = content.match(/Run\s+\"\"[^\"]+\"\"\s+\"\"([^\"]+index\.js)\"\"/);
             entryPoint = match?.[1] ?? null;
+            const modeMatch = content.match(/--mode\s+(dashboard|api|worker)/);
+            mode = modeMatch?.[1] ?? null;
         }
-        const currentEntryPoint = getServiceConfig().entryPoint;
+        const currentEntryPoint = getServiceConfig(detectDefaultServiceMode(platform)).entryPoint;
         const stale = !!entryPoint && (entryPoint.includes('/.npm/_npx/') || entryPoint !== currentEntryPoint);
-        return { entryPoint, stale };
+        return { entryPoint, stale, mode };
     }
     catch {
-        return { entryPoint: null, stale: false };
+        return { entryPoint: null, stale: false, mode: null };
     }
 }
 function getServicePath(platform) {
@@ -70,13 +83,33 @@ function getServicePath(platform) {
         }
     }
 }
-export async function installService() {
+function summarizeServiceMode(mode) {
+    switch (mode) {
+        case 'worker':
+            return 'headless worker (recommended for servers and always-on cloud devices)';
+        case 'api':
+            return 'API service';
+        default:
+            return 'dashboard + API';
+    }
+}
+function tryEnableLinuxLinger() {
+    const username = process.env.USER || os.userInfo().username;
+    try {
+        execSync(`loginctl enable-linger "${username}"`, { stdio: 'ignore' });
+        console.log('Enabled systemd linger for persistent background service.');
+    }
+    catch {
+        console.log('Note: systemd linger was not enabled automatically.');
+        console.log(`      On headless Linux servers, run: sudo loginctl enable-linger ${username}`);
+    }
+}
+export async function installService(options = {}) {
     const platform = detectPlatform();
-    const config = getServiceConfig();
+    const mode = options.mode ?? detectDefaultServiceMode(platform);
+    const config = getServiceConfig(mode);
     const servicePath = getServicePath(platform);
-    // Ensure parent directory exists
     fs.mkdirSync(path.dirname(servicePath), { recursive: true });
-    // Generate and write service file
     let content;
     switch (platform) {
         case 'macos':
@@ -91,7 +124,6 @@ export async function installService() {
     }
     fs.writeFileSync(servicePath, content, 'utf-8');
     console.log(`Service file written to: ${servicePath}`);
-    // Enable and start the service
     try {
         switch (platform) {
             case 'macos':
@@ -101,6 +133,9 @@ export async function installService() {
             case 'linux':
                 execSync('systemctl --user daemon-reload', { stdio: 'inherit' });
                 execSync('systemctl --user enable --now shieldcortex-dashboard.service', { stdio: 'inherit' });
+                if (mode === 'worker' || mode === 'api') {
+                    tryEnableLinuxLinger();
+                }
                 console.log('Service enabled via systemd.');
                 break;
             case 'windows':
@@ -114,13 +149,22 @@ export async function installService() {
         console.log(`The service file was written to ${servicePath} — you can enable it manually.`);
         return;
     }
-    console.log('\nShieldCortex dashboard will now auto-start on login.');
-    console.log(`  API:       http://localhost:3001`);
-    console.log(`  Dashboard: http://localhost:3030`);
+    console.log(`\nShieldCortex ${summarizeServiceMode(mode)} will now auto-start.`);
+    if (mode === 'dashboard') {
+        console.log('  API:       http://localhost:3001');
+        console.log('  Dashboard: http://localhost:3030');
+    }
+    else if (mode === 'api') {
+        console.log('  API:       http://localhost:3001');
+    }
+    else {
+        console.log('  Heartbeat: keeps the device online in ShieldCortex Cloud');
+        console.log('  Sync:      processes background memory/graph sync retries');
+    }
 }
-export async function repairService() {
+export async function repairService(options = {}) {
     await uninstallService();
-    await installService();
+    await installService(options);
 }
 function cleanLogsDirectory() {
     const logsDir = path.join(os.homedir(), '.shieldcortex', 'logs');
@@ -145,7 +189,6 @@ export async function uninstallService(options) {
                 execSync('systemctl --user disable --now shieldcortex-dashboard.service', { stdio: 'inherit' });
                 break;
             case 'windows':
-                // Just delete the file — no daemon to stop
                 break;
         }
     }
@@ -168,11 +211,11 @@ export async function serviceStatus() {
     console.log(`Path:      ${servicePath}`);
     if (inspection.entryPoint) {
         console.log(`Entry:     ${inspection.entryPoint}`);
+        console.log(`Mode:      ${inspection.mode ?? 'unknown'}`);
         console.log(`Healthy:   ${inspection.stale ? 'no (repair recommended)' : 'yes'}`);
     }
     if (!installed)
         return;
-    // Check if running
     try {
         switch (platform) {
             case 'macos': {
@@ -198,13 +241,22 @@ export async function serviceStatus() {
         console.log('Repair:    shieldcortex service repair');
     }
 }
-export async function handleServiceCommand(subcommand) {
+function parseServiceModeArgs(args) {
+    if (args.includes('--dashboard'))
+        return 'dashboard';
+    if (args.includes('--api'))
+        return 'api';
+    if (args.includes('--headless') || args.includes('--worker'))
+        return 'worker';
+    return undefined;
+}
+export async function handleServiceCommand(subcommand, args = []) {
     switch (subcommand) {
         case 'install':
-            await installService();
+            await installService({ mode: parseServiceModeArgs(args) });
             break;
         case 'repair':
-            await repairService();
+            await repairService({ mode: parseServiceModeArgs(args) });
             break;
         case 'uninstall':
             await uninstallService({ cleanLogs: process.argv.includes('--clean-logs') });
@@ -213,7 +265,7 @@ export async function handleServiceCommand(subcommand) {
             await serviceStatus();
             break;
         default:
-            console.log('Usage: shieldcortex service <install|repair|uninstall|status>');
+            console.log('Usage: shieldcortex service <install|repair|uninstall|status> [--dashboard|--api|--headless]');
             process.exit(1);
     }
 }

package/dist/service/templates.d.ts

@@ -1,11 +1,13 @@
 /**
- * Platform-specific service file templates for auto-starting ShieldCortex dashboard.
+ * Platform-specific service file templates for auto-starting ShieldCortex.
  */
+export type ServiceMode = 'dashboard' | 'api' | 'worker';
 export interface ServiceConfig {
     nodePath: string;
     nodeBinDir: string;
     entryPoint: string;
     logsDir: string;
+    mode: ServiceMode;
 }
 export declare function launchdPlist(config: ServiceConfig): string;
 export declare function systemdUnit(config: ServiceConfig): string;

package/dist/service/templates.js

@@ -1,6 +1,16 @@
 /**
- * Platform-specific service file templates for auto-starting ShieldCortex dashboard.
+ * Platform-specific service file templates for auto-starting ShieldCortex.
  */
+function modeLabel(mode) {
+    switch (mode) {
+        case 'worker':
+            return 'Worker';
+        case 'api':
+            return 'API';
+        default:
+            return 'Dashboard';
+    }
+}
 export function launchdPlist(config) {
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -13,7 +23,7 @@ export function launchdPlist(config) {
     <string>${config.nodePath}</string>
     <string>${config.entryPoint}</string>
     <string>--mode</string>
-    <string>dashboard</string>
+    <string>${config.mode}</string>
   </array>
   <key>RunAtLoad</key>
   <true/>
@@ -33,12 +43,12 @@ export function launchdPlist(config) {
 }
 export function systemdUnit(config) {
     return `[Unit]
-Description=ShieldCortex Dashboard
+Description=ShieldCortex ${modeLabel(config.mode)}
 After=network.target
 
 [Service]
 Type=simple
-ExecStart=${config.nodePath} ${config.entryPoint} --mode dashboard
+ExecStart=${config.nodePath} ${config.entryPoint} --mode ${config.mode}
 Restart=on-failure
 RestartSec=5
 StandardOutput=append:${config.logsDir}/dashboard-stdout.log
@@ -53,5 +63,5 @@ export function windowsVbs(config) {
     const nodePath = config.nodePath.replace(/\//g, '\\');
     const entryPoint = config.entryPoint.replace(/\//g, '\\');
     return `Set WshShell = CreateObject("WScript.Shell")
-WshShell.Run """${nodePath}"" ""${entryPoint}"" --mode dashboard", 0, False`;
+WshShell.Run """${nodePath}"" ""${entryPoint}"" --mode ${config.mode}", 0, False`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "Trustworthy memory and security for AI agents. Recall debugging, review queue, OpenClaw session capture, and memory poisoning defence for Claude Code, OpenClaw, LangChain, and MCP agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",