lightman-agent 1.0.23 → 1.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightman-agent",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "LIGHTMAN Agent - System-level daemon for museum display machines",
   "private": false,
   "type": "module",

package/scripts/install-windows.ps1

@@ -529,15 +529,25 @@ Set-ItemProperty -Path $SP -Name "InactivityTimeoutSecs" -Value 0 -ErrorAction S
 try { Disable-ScheduledTask -TaskName "\Microsoft\Windows\Shell\CreateObjectTask" -ErrorAction SilentlyContinue | Out-Null } catch { }
 Write-Host "  Lock screen fully disabled"
 
-# --- 15. Sleep ---
-Write-Host "[15/19] Disabling sleep..." -ForegroundColor Yellow
-powercfg /change monitor-timeout-ac 0 2>&1 | Out-Null
-powercfg /change standby-timeout-ac 0 2>&1 | Out-Null
-powercfg /change hibernate-timeout-ac 0 2>&1 | Out-Null
-
-# --- 16. Harden ---
-Write-Host "[16/19] Hardening Windows..." -ForegroundColor Yellow
-$WU = "HKLM:\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate\AU"
+# --- 15. Sleep ---
+Write-Host "[15/19] Disabling sleep..." -ForegroundColor Yellow
+powercfg /change monitor-timeout-ac 0 2>&1 | Out-Null
+powercfg /change standby-timeout-ac 0 2>&1 | Out-Null
+powercfg /change hibernate-timeout-ac 0 2>&1 | Out-Null
+
+# --- 15b. Display topology ---
+Write-Host "[15b/19] Enforcing display extend mode..." -ForegroundColor Yellow
+if (Test-Path "$env:SystemRoot\System32\DisplaySwitch.exe") {
+    & "$env:SystemRoot\System32\DisplaySwitch.exe" /extend 2>&1 | Out-Null
+    Start-Sleep -Seconds 2
+    Write-Host "  Display mode set to Extend"
+} else {
+    Write-Host "  DisplaySwitch.exe not found - skipped" -ForegroundColor DarkYellow
+}
+
+# --- 16. Harden ---
+Write-Host "[16/19] Hardening Windows..." -ForegroundColor Yellow
+$WU = "HKLM:\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate\AU"
 if (-not (Test-Path $WU)) { New-Item -Path $WU -Force | Out-Null }
 Set-ItemProperty -Path $WU -Name "NoAutoRebootWithLoggedOnUsers" -Value 1
 Set-ItemProperty -Path $WU -Name "AUOptions" -Value 2

package/scripts/launch-multi-kiosk.ps1

@@ -0,0 +1,185 @@
+# LIGHTMAN shell multi-screen launcher
+# Runs in the interactive shell session and launches one browser window per display.
+
+param(
+    [Parameter(Mandatory = $true)][string]$BrowserPath,
+    [Parameter(Mandatory = $true)][string]$MultiConfigPath,
+    [Parameter(Mandatory = $true)][string]$FallbackUrl,
+    [string]$LogFile = "C:\ProgramData\Lightman\logs\shell.log"
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-Log {
+    param([string]$Message)
+    try {
+        Add-Content -Path $LogFile -Value "[$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss.fff')] $Message"
+    } catch {
+        # Logging should never block kiosk startup.
+    }
+}
+
+function Resolve-DisplayNumber {
+    param([string]$HardwareId)
+    if ([string]::IsNullOrWhiteSpace($HardwareId)) { return $null }
+    $trimmed = $HardwareId.Trim()
+    if ($trimmed -match '^\d+$') { return [int]$trimmed }
+    if ($trimmed -match 'DISPLAY(\d+)$') { return [int]$matches[1] }
+    return $null
+}
+
+function Pick-Screen {
+    param(
+        [array]$Screens,
+        [string]$HardwareId,
+        [int]$ScreenIndex,
+        [System.Collections.Generic.HashSet[string]]$Used
+    )
+
+    $displayNo = Resolve-DisplayNumber -HardwareId $HardwareId
+    if ($displayNo) {
+        $suffix = "DISPLAY$displayNo"
+        foreach ($s in $Screens) {
+            if ($Used.Contains($s.DeviceName)) { continue }
+            if ($s.DeviceName.ToUpperInvariant().EndsWith($suffix)) { return $s }
+        }
+    }
+
+    if (-not [string]::IsNullOrWhiteSpace($HardwareId)) {
+        foreach ($s in $Screens) {
+            if ($Used.Contains($s.DeviceName)) { continue }
+            if ($s.DeviceName.Equals($HardwareId, [System.StringComparison]::OrdinalIgnoreCase)) { return $s }
+        }
+    }
+
+    if ($ScreenIndex -ge 0 -and $ScreenIndex -lt $Screens.Count) {
+        $preferred = $Screens[$ScreenIndex]
+        if ($preferred -and -not $Used.Contains($preferred.DeviceName)) { return $preferred }
+    }
+
+    foreach ($s in $Screens) {
+        if (-not $Used.Contains($s.DeviceName)) { return $s }
+    }
+
+    return $null
+}
+
+if (-not (Test-Path $BrowserPath)) {
+    Write-Log "ERROR: Browser path not found: $BrowserPath"
+    exit 1
+}
+
+Add-Type -AssemblyName System.Windows.Forms
+$screens = [System.Windows.Forms.Screen]::AllScreens | Sort-Object { $_.DeviceName }
+Write-Log "Detected $($screens.Count) display(s) in shell session"
+
+if (-not (Test-Path $MultiConfigPath)) {
+    Write-Log "Multi config not found. Launching fallback URL."
+    $fallback = Start-Process -FilePath $BrowserPath -ArgumentList @(
+        "--kiosk",
+        "--noerrdialogs",
+        "--disable-infobars",
+        "--disable-session-crashed-bubble",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--autoplay-policy=no-user-gesture-required",
+        "--disable-features=TranslateUI",
+        "--user-data-dir=C:\ProgramData\Lightman\chrome-kiosk",
+        $FallbackUrl
+    ) -PassThru
+    if ($fallback) { Wait-Process -Id $fallback.Id -ErrorAction SilentlyContinue }
+    exit 0
+}
+
+$json = Get-Content -Raw $MultiConfigPath | ConvertFrom-Json
+$entries = @($json.entries)
+if ($entries.Count -le 1) {
+    Write-Log "Multi config has $($entries.Count) entry. Launching fallback URL."
+    $fallback = Start-Process -FilePath $BrowserPath -ArgumentList @(
+        "--kiosk",
+        "--noerrdialogs",
+        "--disable-infobars",
+        "--disable-session-crashed-bubble",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--autoplay-policy=no-user-gesture-required",
+        "--disable-features=TranslateUI",
+        "--user-data-dir=C:\ProgramData\Lightman\chrome-kiosk",
+        $FallbackUrl
+    ) -PassThru
+    if ($fallback) { Wait-Process -Id $fallback.Id -ErrorAction SilentlyContinue }
+    exit 0
+}
+
+$usedScreens = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::OrdinalIgnoreCase)
+$processes = @()
+
+for ($i = 0; $i -lt $entries.Count; $i++) {
+    $entry = $entries[$i]
+    $entryIndex = 0
+    try { $entryIndex = [int]$entry.screenIndex } catch { $entryIndex = $i }
+    $entryHardwareId = [string]$entry.hardwareId
+    $entryUrl = [string]$entry.url
+    if ([string]::IsNullOrWhiteSpace($entryUrl)) { $entryUrl = $FallbackUrl }
+
+    $screen = Pick-Screen -Screens $screens -HardwareId $entryHardwareId -ScreenIndex $entryIndex -Used $usedScreens
+    if (-not $screen) {
+        Write-Log "WARN: No available screen for mapping index $i (hardwareId='$entryHardwareId')."
+        continue
+    }
+
+    $null = $usedScreens.Add($screen.DeviceName)
+
+    $screenSlot = [Array]::IndexOf($screens, $screen)
+    if ($screenSlot -lt 0) { $screenSlot = $entryIndex }
+    $userDataDir = "C:\ProgramData\Lightman\chrome-kiosk-screen-$screenSlot"
+    New-Item -ItemType Directory -Path $userDataDir -Force | Out-Null
+
+    $x = [int]$screen.Bounds.X
+    $y = [int]$screen.Bounds.Y
+    $w = [int]$screen.Bounds.Width
+    $h = [int]$screen.Bounds.Height
+
+    Write-Log "Launching $($screen.DeviceName) at ${w}x${h}@${x},${y} -> $entryUrl"
+
+    $proc = Start-Process -FilePath $BrowserPath -ArgumentList @(
+        "--kiosk",
+        "--noerrdialogs",
+        "--disable-infobars",
+        "--disable-session-crashed-bubble",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--autoplay-policy=no-user-gesture-required",
+        "--disable-features=TranslateUI",
+        "--window-position=$x,$y",
+        "--window-size=$w,$h",
+        "--user-data-dir=$userDataDir",
+        $entryUrl
+    ) -PassThru
+
+    if ($proc) { $processes += $proc }
+    Start-Sleep -Milliseconds 300
+}
+
+if ($processes.Count -eq 0) {
+    Write-Log "WARN: Multi launch created no browser process. Starting fallback."
+    $fallback = Start-Process -FilePath $BrowserPath -ArgumentList @(
+        "--kiosk",
+        "--noerrdialogs",
+        "--disable-infobars",
+        "--disable-session-crashed-bubble",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--autoplay-policy=no-user-gesture-required",
+        "--disable-features=TranslateUI",
+        "--user-data-dir=C:\ProgramData\Lightman\chrome-kiosk",
+        $FallbackUrl
+    ) -PassThru
+    if ($fallback) { Wait-Process -Id $fallback.Id -ErrorAction SilentlyContinue }
+    exit 0
+}
+
+$pids = $processes | ForEach-Object { $_.Id }
+Write-Log "Waiting on multi-screen browser processes: $($pids -join ', ')"
+Wait-Process -Id $pids -ErrorAction SilentlyContinue
+Write-Log "Multi-screen browser session ended"

package/scripts/lightman-shell.bat

@@ -13,11 +13,13 @@ REM   5. Launches Chrome fullscreen
 REM   6. If Chrome crashes, relaunches in 3 seconds (infinite loop)
 REM ================================================================
 
-set INSTALL_DIR=C:\Program Files\Lightman\Agent
-set CONFIG_FILE=%INSTALL_DIR%\agent.config.json
-set URL_SIDECAR=C:\ProgramData\Lightman\kiosk-url.txt
-set CHROME_DATA=C:\ProgramData\Lightman\chrome-kiosk
-set LOG_FILE=C:\ProgramData\Lightman\logs\shell.log
+set INSTALL_DIR=C:\Program Files\Lightman\Agent
+set CONFIG_FILE=%INSTALL_DIR%\agent.config.json
+set URL_SIDECAR=C:\ProgramData\Lightman\kiosk-url.txt
+set MULTI_SIDECAR=C:\ProgramData\Lightman\kiosk-multi.json
+set MULTI_LAUNCHER=%INSTALL_DIR%\scripts\launch-multi-kiosk.ps1
+set CHROME_DATA=C:\ProgramData\Lightman\chrome-kiosk
+set LOG_FILE=C:\ProgramData\Lightman\logs\shell.log
 
 REM Ensure directories exist
 if not exist "C:\ProgramData\Lightman\logs" mkdir "C:\ProgramData\Lightman\logs"
@@ -116,8 +118,14 @@ set MAX_WAIT=60
     timeout /t 1 /nobreak >nul
     goto wait_for_agent
 
-:agent_ready
-echo [%date% %time%] Agent ready >> "%LOG_FILE%"
+:agent_ready
+echo [%date% %time%] Agent ready >> "%LOG_FILE%"
+
+REM Force Windows into Extend mode so all connected displays are usable.
+if exist "%SystemRoot%\System32\DisplaySwitch.exe" (
+    "%SystemRoot%\System32\DisplaySwitch.exe" /extend >nul 2>&1
+    timeout /t 2 /nobreak >nul
+)
 
 REM ----------------------------------------------------------------
 REM Infinite Chrome loop
@@ -139,9 +147,18 @@ REM ----------------------------------------------------------------
         )
     )
 
-    echo [%date% %time%] Launching browser: %URL% >> "%LOG_FILE%"
-
-    start /wait "" "%BROWSER%" --kiosk --noerrdialogs --disable-infobars --disable-session-crashed-bubble --no-first-run --no-default-browser-check --start-fullscreen --disable-translate --disable-extensions --autoplay-policy=no-user-gesture-required --disable-features=TranslateUI --user-data-dir="%CHROME_DATA%" "%URL%"
+    set MULTI_COUNT=0
+    if exist "%MULTI_SIDECAR%" (
+        for /f "delims=" %%c in ('node -e "try{const fs=require('fs');const p=String.raw`%MULTI_SIDECAR%`;const j=JSON.parse(fs.readFileSync(p,'utf8'));const n=Array.isArray(j&&j.entries)?j.entries.length:0;console.log(n)}catch(e){console.log(0)}" 2^>nul') do set MULTI_COUNT=%%c
+    )
+
+    if %MULTI_COUNT% gtr 1 if exist "%MULTI_LAUNCHER%" (
+        echo [%date% %time%] Launching multi-screen shell session (%MULTI_COUNT% screens) >> "%LOG_FILE%"
+        powershell -ExecutionPolicy Bypass -NoProfile -File "%MULTI_LAUNCHER%" -BrowserPath "%BROWSER%" -MultiConfigPath "%MULTI_SIDECAR%" -FallbackUrl "%URL%" -LogFile "%LOG_FILE%"
+    ) else (
+        echo [%date% %time%] Launching browser: %URL% >> "%LOG_FILE%"
+        start /wait "" "%BROWSER%" --kiosk --noerrdialogs --disable-infobars --disable-session-crashed-bubble --no-first-run --no-default-browser-check --start-fullscreen --disable-translate --disable-extensions --autoplay-policy=no-user-gesture-required --disable-features=TranslateUI --user-data-dir="%CHROME_DATA%" "%URL%"
+    )
 
     echo [%date% %time%] Browser exited (code: %errorlevel%). Restarting in 3s... >> "%LOG_FILE%"
     timeout /t 3 /nobreak >nul

package/src/index.ts

@@ -111,10 +111,26 @@ async function main(): Promise<void> {
     serverUrl: config.serverUrl,
     identity,
     logger,
-    onMessage: (msg: WsMessage) => {
-      handleServerMessage(msg, commandExecutor, logger, powerScheduler, startSerialBridge, stopSerialBridge, startOscBridge, stopOscBridge, multiScreenKiosk, getIdentity, kioskManager, watchdog, startPresenceSensor, stopPresenceSensor);
-    },
-  });
+    onMessage: (msg: WsMessage) => {
+      handleServerMessage(
+        msg,
+        commandExecutor,
+        logger,
+        powerScheduler,
+        startSerialBridge,
+        stopSerialBridge,
+        startOscBridge,
+        stopOscBridge,
+        multiScreenKiosk,
+        getIdentity,
+        kioskManager,
+        watchdog,
+        startPresenceSensor,
+        stopPresenceSensor,
+        () => lastKnownTotalScreens
+      );
+    },
+  });
 
   // 4. Start health monitor
   const healthMonitor = new HealthMonitor(
@@ -163,14 +179,15 @@ async function main(): Promise<void> {
   const kioskManager = new KioskManager(kioskConfig, logger);
   registerKioskCommands(commandExecutor.register.bind(commandExecutor), kioskManager, logger);
 
-  // Multi-screen kiosk manager — handles multiple Chrome instances on multi-display devices
-  const multiScreenKiosk = new MultiScreenKioskManager(kioskConfig, logger);
-  const getIdentity = () => identity!;
-  registerMultiScreenKioskCommands(commandExecutor.register.bind(commandExecutor), multiScreenKiosk, getIdentity, logger);
-
-  // Detect physical screens and keep them fresh (multi-display setups can change after boot).
-  let detectedScreens = detectScreens(logger);
-  multiScreenKiosk.setDetectedScreens(detectedScreens);
+  // Multi-screen kiosk manager — handles multiple Chrome instances on multi-display devices
+  const multiScreenKiosk = new MultiScreenKioskManager(kioskConfig, logger);
+  const getIdentity = () => identity!;
+  registerMultiScreenKioskCommands(commandExecutor.register.bind(commandExecutor), multiScreenKiosk, getIdentity, logger);
+
+  // Detect physical screens and keep them fresh (multi-display setups can change after boot).
+  let lastKnownTotalScreens = 0;
+  let detectedScreens = detectScreens(logger);
+  multiScreenKiosk.setDetectedScreens(detectedScreens);
 
   const toScreenPayload = (screens: DetectedScreen[]) => (
     screens.map((s) => ({
@@ -502,24 +519,30 @@ async function main(): Promise<void> {
         // Multi-screen handling:
         // 1) Use explicit screenMap when present.
         // 2) For multi-screen apps without a saved map, auto-create placeholders.
-        const requestedScreenMap = deviceCfg?.screenMap || [];
-        const isMultiScreenApp = !!deviceCfg && deviceCfg.totalScreens > 1;
-        const effectiveRequestedMap = requestedScreenMap.length > 0
-          ? requestedScreenMap
-          : (isMultiScreenApp ? createPlaceholderScreenMap(deviceCfg.totalScreens) : []);
-
-        if (effectiveRequestedMap.length > 0) {
-          const resolved = resolveScreenMap({
-            requestedScreenMap: effectiveRequestedMap,
-            detectedScreens,
-            totalScreens: Math.max(deviceCfg?.totalScreens || 0, effectiveRequestedMap.length),
-          });
-          logger.info(
-            `[MultiKiosk] Effective map ready: requested=${effectiveRequestedMap.length}, mode=${resolved.mode}, totalScreens=${deviceCfg?.totalScreens || 0}`
-          );
-          watchdog.setMultiScreenActive(true);
-          multiScreenKiosk.applyScreenMap(effectiveRequestedMap, identity).catch((err) => {
-            logger.error('[MultiKiosk] Failed to apply effective screenMap from config:', err);
+        const requestedScreenMap = deviceCfg?.screenMap || [];
+        const totalScreens = Math.max(deviceCfg?.totalScreens || 0, requestedScreenMap.length);
+        lastKnownTotalScreens = totalScreens;
+        const effectiveRequestedMap = normalizeScreenMapForTotalScreens(requestedScreenMap, totalScreens);
+
+        if (totalScreens > 1 && detectedScreens.length < totalScreens) {
+          logger.warn(
+            `[MultiKiosk] App expects ${totalScreens} screen(s) but agent detected ${detectedScreens.length}. ` +
+            'Remaining screens may stay black until Windows reports all displays.'
+          );
+        }
+
+        if (effectiveRequestedMap.length > 0) {
+          const resolved = resolveScreenMap({
+            requestedScreenMap: effectiveRequestedMap,
+            detectedScreens,
+            totalScreens,
+          });
+          logger.info(
+            `[MultiKiosk] Effective map ready: requested=${requestedScreenMap.length}, effective=${effectiveRequestedMap.length}, mode=${resolved.mode}, totalScreens=${totalScreens}`
+          );
+          watchdog.setMultiScreenActive(true);
+          multiScreenKiosk.applyScreenMap(effectiveRequestedMap, identity).catch((err) => {
+            logger.error('[MultiKiosk] Failed to apply effective screenMap from config:', err);
           });
           return;
         }
@@ -606,10 +629,33 @@ async function main(): Promise<void> {
   logger.info('LIGHTMAN Agent running.');
 }
 
-function createPlaceholderScreenMap(totalScreens: number): ScreenMapping[] {
-  const count = Math.max(0, Math.floor(totalScreens || 0));
-  return Array.from({ length: count }, () => ({ hardwareId: '', url: '' }));
-}
+function createPlaceholderScreenMap(totalScreens: number): ScreenMapping[] {
+  const count = Math.max(0, Math.floor(totalScreens || 0));
+  return Array.from({ length: count }, () => ({ hardwareId: '', url: '' }));
+}
+
+function normalizeScreenMapForTotalScreens(
+  screenMap: ScreenMapping[] | undefined,
+  totalScreens: number
+): ScreenMapping[] {
+  const requested = Array.isArray(screenMap)
+    ? screenMap.map((m) => ({
+      hardwareId: String(m.hardwareId || ''),
+      url: String(m.url || ''),
+      ...(m.label ? { label: String(m.label) } : {}),
+    }))
+    : [];
+
+  const targetCount = Math.max(requested.length, Math.max(0, Math.floor(totalScreens || 0)));
+  if (targetCount === 0) return [];
+
+  if (requested.length >= targetCount) return requested;
+
+  return [
+    ...requested,
+    ...createPlaceholderScreenMap(targetCount - requested.length),
+  ];
+}
 
 function haveScreensChanged(prev: DetectedScreen[], next: DetectedScreen[]): boolean {
   if (prev.length !== next.length) return true;
@@ -631,22 +677,23 @@ function haveScreensChanged(prev: DetectedScreen[], next: DetectedScreen[]): boo
   return false;
 }
 
-function handleServerMessage(
-  msg: WsMessage,
-  commandExecutor: CommandExecutor,
+function handleServerMessage(
+  msg: WsMessage,
+  commandExecutor: CommandExecutor,
   logger: Logger,
   powerScheduler?: PowerScheduler,
   startSerialBridge?: (comPort: string, controllerId: string, baudRate?: number) => void,
   stopSerialBridge?: () => void,
   startOscBridgeFn?: (oscPort: number, oscAddress: string, oscHost?: string) => void,
   stopOscBridgeFn?: () => void,
-  multiScreenKiosk?: MultiScreenKioskManager,
-  getIdentity?: () => Identity,
-  kioskManager?: KioskManager,
-  watchdog?: Watchdog,
-  startPresenceSensorFn?: (port?: string) => void,
-  stopPresenceSensorFn?: () => void
-): void {
+  multiScreenKiosk?: MultiScreenKioskManager,
+  getIdentity?: () => Identity,
+  kioskManager?: KioskManager,
+  watchdog?: Watchdog,
+  startPresenceSensorFn?: (port?: string) => void,
+  stopPresenceSensorFn?: () => void,
+  getTotalScreensHint?: () => number
+): void {
   switch (msg.type) {
     case 'connected':
       logger.info('Server acknowledged connection');
@@ -698,16 +745,25 @@ function handleServerMessage(
         }
 
         // Admin pushed updated screenMap via device config save
-        const screenMap = msg.payload.screenMap as ScreenMapping[] | undefined;
-        if (screenMap && Array.isArray(screenMap) && multiScreenKiosk && getIdentity) {
-          if (screenMap.length > 0) {
-            logger.info(`[MultiKiosk] Received screenMap update: ${screenMap.length} mapping(s) — killing single kiosk`);
-            if (kioskManager) kioskManager.kill().catch(() => {});
-            if (watchdog) watchdog.setMultiScreenActive(true);
-            multiScreenKiosk.applyScreenMap(screenMap, getIdentity()).catch((err) => {
-              logger.error('[MultiKiosk] Failed to apply screenMap:', err);
-            });
-          } else {
+        const screenMap = msg.payload.screenMap as ScreenMapping[] | undefined;
+        if (screenMap && Array.isArray(screenMap) && multiScreenKiosk && getIdentity) {
+          const payloadTotalScreens = Number(msg.payload.totalScreens || 0);
+          const hintTotalScreens = Math.max(
+            Number.isFinite(payloadTotalScreens) ? payloadTotalScreens : 0,
+            getTotalScreensHint ? getTotalScreensHint() : 0
+          );
+          const effectiveScreenMap = screenMap.length > 0
+            ? normalizeScreenMapForTotalScreens(screenMap, hintTotalScreens)
+            : screenMap;
+
+          if (screenMap.length > 0) {
+            logger.info(`[MultiKiosk] Received screenMap update: requested=${screenMap.length}, effective=${effectiveScreenMap.length}, totalScreens=${hintTotalScreens} — killing single kiosk`);
+            if (kioskManager) kioskManager.kill().catch(() => {});
+            if (watchdog) watchdog.setMultiScreenActive(true);
+            multiScreenKiosk.applyScreenMap(effectiveScreenMap, getIdentity()).catch((err) => {
+              logger.error('[MultiKiosk] Failed to apply screenMap:', err);
+            });
+          } else {
             // Empty screenMap — deactivate multi-screen, resume single kiosk
             logger.info('[MultiKiosk] Empty screenMap received — deactivating multi-screen');
             multiScreenKiosk.killAll().catch(() => {});
@@ -719,16 +775,25 @@ function handleServerMessage(
     case 'agent:screenMap':
       // Direct screenMap push from server
       if (msg.payload && multiScreenKiosk && getIdentity) {
-        const screenMap = msg.payload.screenMap as ScreenMapping[] | undefined;
-        if (screenMap && Array.isArray(screenMap)) {
-          if (screenMap.length > 0) {
-            logger.info(`[MultiKiosk] Received agent:screenMap: ${screenMap.length} mapping(s) — killing single kiosk`);
-            if (kioskManager) kioskManager.kill().catch(() => {});
-            if (watchdog) watchdog.setMultiScreenActive(true);
-            multiScreenKiosk.applyScreenMap(screenMap, getIdentity()).catch((err) => {
-              logger.error('[MultiKiosk] Failed to apply screenMap:', err);
-            });
-          } else {
+        const screenMap = msg.payload.screenMap as ScreenMapping[] | undefined;
+        if (screenMap && Array.isArray(screenMap)) {
+          const payloadTotalScreens = Number(msg.payload.totalScreens || 0);
+          const hintTotalScreens = Math.max(
+            Number.isFinite(payloadTotalScreens) ? payloadTotalScreens : 0,
+            getTotalScreensHint ? getTotalScreensHint() : 0
+          );
+          const effectiveScreenMap = screenMap.length > 0
+            ? normalizeScreenMapForTotalScreens(screenMap, hintTotalScreens)
+            : screenMap;
+
+          if (screenMap.length > 0) {
+            logger.info(`[MultiKiosk] Received agent:screenMap: requested=${screenMap.length}, effective=${effectiveScreenMap.length}, totalScreens=${hintTotalScreens} — killing single kiosk`);
+            if (kioskManager) kioskManager.kill().catch(() => {});
+            if (watchdog) watchdog.setMultiScreenActive(true);
+            multiScreenKiosk.applyScreenMap(effectiveScreenMap, getIdentity()).catch((err) => {
+              logger.error('[MultiKiosk] Failed to apply screenMap:', err);
+            });
+          } else {
             logger.info('[MultiKiosk] Empty agent:screenMap — deactivating multi-screen');
             multiScreenKiosk.killAll().catch(() => {});
             if (watchdog) watchdog.setMultiScreenActive(false);

package/src/services/multiScreenKiosk.ts

@@ -1,11 +1,17 @@
-import { spawn } from 'child_process';
-import type { ChildProcess } from 'child_process';
-import type { KioskConfig, ScreenMapping, MultiScreenKioskStatus, SingleScreenStatus } from '../lib/types.js';
-import type { DetectedScreen } from '../lib/screens.js';
-import type { Logger } from '../lib/logger.js';
-import { resolveDetectedScreen, resolveScreenMap } from '../lib/screenMap.js';
-
-interface ScreenInstance {
+import { spawn } from 'child_process';
+import type { ChildProcess } from 'child_process';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { basename, dirname } from 'path';
+import type { KioskConfig, ScreenMapping, MultiScreenKioskStatus, SingleScreenStatus } from '../lib/types.js';
+import type { DetectedScreen } from '../lib/screens.js';
+import type { Logger } from '../lib/logger.js';
+import { resolveDetectedScreen, resolveScreenMap } from '../lib/screenMap.js';
+
+const SHELL_MULTI_CONFIG_PATH = process.platform === 'win32'
+  ? 'C:\\ProgramData\\Lightman\\kiosk-multi.json'
+  : '/tmp/lightman-kiosk-multi.json';
+
+interface ScreenInstance {
   hardwareId: string;
   mappingId: string;
   mappingUrl: string;
@@ -30,10 +36,14 @@ export class MultiScreenKioskManager {
   private pollTimer: NodeJS.Timeout | null = null;
   private applying = false;
 
-  constructor(config: KioskConfig, logger: Logger) {
-    this.config = config;
-    this.logger = logger;
-  }
+  constructor(config: KioskConfig, logger: Logger) {
+    this.config = config;
+    this.logger = logger;
+  }
+
+  private isShellModeOnWindows(): boolean {
+    return process.platform === 'win32' && !!this.config.shellMode;
+  }
 
   /** Update the list of detected physical screens */
   setDetectedScreens(screens: DetectedScreen[]): void {
@@ -63,12 +73,18 @@ export class MultiScreenKioskManager {
     }
   }
 
-  private async _applyScreenMap(screenMap: ScreenMapping[], identity: { deviceId: string; apiKey: string }): Promise<MultiScreenKioskStatus> {
-    const resolvedMap = resolveScreenMap({
-      requestedScreenMap: screenMap,
-      detectedScreens: this.detectedScreens,
-      totalScreens: screenMap.length,
-    });
+  private async _applyScreenMap(screenMap: ScreenMapping[], identity: { deviceId: string; apiKey: string }): Promise<MultiScreenKioskStatus> {
+    if (this.isShellModeOnWindows()) {
+      this.applyShellMultiConfig(screenMap, identity);
+      this.stopPoll();
+      return this.getStatus();
+    }
+
+    const resolvedMap = resolveScreenMap({
+      requestedScreenMap: screenMap,
+      detectedScreens: this.detectedScreens,
+      totalScreens: screenMap.length,
+    });
 
     this.logger.info(
       `[MultiKiosk] Applying screen map: ${resolvedMap.screenMap.length} mapping(s), mode=${resolvedMap.mode}`
@@ -204,7 +220,7 @@ export class MultiScreenKioskManager {
   }
 
   /** Build the full URL with device credentials and screenIndex */
-  private buildUrl(path: string, identity: { deviceId: string; apiKey: string }, screenIndex?: number): string {
+  private buildUrl(path: string, identity: { deviceId: string; apiKey: string }, screenIndex?: number): string {
     let fullUrl: string;
     if (path.startsWith('http://') || path.startsWith('https://')) {
       fullUrl = path;
@@ -220,16 +236,95 @@ export class MultiScreenKioskManager {
       url.searchParams.set('screenIndex', String(screenIndex));
     }
 
-    return url.toString();
-  }
-
-  /** Navigate a single screen to a new URL */
-  async navigateScreen(hardwareId: string, url: string, identity: { deviceId: string; apiKey: string }): Promise<void> {
-    const resolvedHardwareId = resolveDetectedScreen(hardwareId, this.detectedScreens)?.hardwareId || hardwareId;
-    const existing = this.instances.get(resolvedHardwareId);
-    if (!existing) {
-      this.logger.warn(`[MultiKiosk] Cannot navigate ${hardwareId} - not in instance map`);
-      return;
+    return url.toString();
+  }
+
+  private applyShellMultiConfig(
+    screenMap: ScreenMapping[],
+    identity: { deviceId: string; apiKey: string }
+  ): void {
+    const entries = screenMap.map((mapping, index) => {
+      const resolvedHardwareId = String(mapping.hardwareId || '').trim() || String(index + 1);
+      const basePath = mapping.url || this.config.defaultUrl;
+      return {
+        hardwareId: resolvedHardwareId,
+        screenIndex: index,
+        url: this.buildUrl(basePath, identity, index),
+      };
+    });
+
+    try {
+      const dir = dirname(SHELL_MULTI_CONFIG_PATH);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+
+      writeFileSync(
+        SHELL_MULTI_CONFIG_PATH,
+        JSON.stringify({ updatedAt: Date.now(), entries }, null, 2),
+        'utf-8'
+      );
+      this.logger.info(`[MultiKiosk] Shell multi config written (${entries.length} screen(s))`);
+    } catch (err) {
+      this.logger.error('[MultiKiosk] Failed to write shell multi config:', err);
+      return;
+    }
+
+    this.killShellManagedBrowsers();
+  }
+
+  private clearShellMultiConfig(): void {
+    try {
+      if (existsSync(SHELL_MULTI_CONFIG_PATH)) {
+        rmSync(SHELL_MULTI_CONFIG_PATH, { force: true });
+      }
+    } catch (err) {
+      this.logger.warn('[MultiKiosk] Failed to clear shell multi config:', err);
+    }
+  }
+
+  private killShellManagedBrowsers(): void {
+    if (process.platform !== 'win32') return;
+
+    const browserExe = basename(this.config.browserPath || '').toLowerCase();
+    const targets = new Set<string>(['chrome.exe', 'msedge.exe']);
+    if (browserExe.endsWith('.exe')) {
+      targets.add(browserExe);
+    }
+
+    for (const exeName of targets) {
+      try {
+        const killer = spawn('taskkill', ['/IM', exeName, '/F'], {
+          stdio: 'ignore',
+          windowsHide: true,
+        });
+        killer.unref();
+      } catch {
+        // Ignore process-kill failures; shell loop can still recover.
+      }
+    }
+  }
+
+  /** Navigate a single screen to a new URL */
+  async navigateScreen(hardwareId: string, url: string, identity: { deviceId: string; apiKey: string }): Promise<void> {
+    if (this.isShellModeOnWindows()) {
+      const idx = this.desiredScreenMap.findIndex((m) => String(m.hardwareId || '').trim() === String(hardwareId || '').trim());
+      if (idx === -1) {
+        this.logger.warn(`[MultiKiosk] Cannot navigate ${hardwareId} - not in desired map`);
+        return;
+      }
+
+      const nextMap = this.desiredScreenMap.map((m) => ({ ...m }));
+      nextMap[idx] = { ...nextMap[idx], url };
+      await this.applyScreenMap(nextMap, identity);
+      return;
+    }
+
+    const resolvedHardwareId = resolveDetectedScreen(hardwareId, this.detectedScreens)?.hardwareId || hardwareId;
+    const existing = this.instances.get(resolvedHardwareId);
+    if (!existing) {
+      this.logger.warn(`[MultiKiosk] Cannot navigate ${hardwareId} - not in instance map`);
+      return;
     }
 
     this.killInstance(existing);
@@ -256,27 +351,41 @@ export class MultiScreenKioskManager {
   }
 
   /** Kill all Chrome instances */
-  async killAll(options?: { clearDesired?: boolean }): Promise<void> {
-    for (const [, instance] of this.instances) {
-      this.killInstance(instance);
-    }
-    this.instances.clear();
-    this.stopPoll();
-
-    if (options?.clearDesired !== false) {
-      this.desiredScreenMap = [];
-      this.desiredIdentity = null;
-    }
+  async killAll(options?: { clearDesired?: boolean }): Promise<void> {
+    for (const [, instance] of this.instances) {
+      this.killInstance(instance);
+    }
+    this.instances.clear();
+    this.stopPoll();
+
+    if (this.isShellModeOnWindows()) {
+      this.clearShellMultiConfig();
+      this.killShellManagedBrowsers();
+    }
+
+    if (options?.clearDesired !== false) {
+      this.desiredScreenMap = [];
+      this.desiredIdentity = null;
+    }
   }
 
-  /** Restart all Chrome instances */
-  async restartAll(identity: { deviceId: string; apiKey: string }): Promise<MultiScreenKioskStatus> {
-    this.logger.info('[MultiKiosk] Restarting all Chrome instances');
-
-    const mappings: ScreenMapping[] = [];
-    for (const [, instance] of this.instances) {
-      mappings.push({ hardwareId: instance.mappingId, url: instance.mappingUrl, label: undefined });
-    }
+  /** Restart all Chrome instances */
+  async restartAll(identity: { deviceId: string; apiKey: string }): Promise<MultiScreenKioskStatus> {
+    this.logger.info('[MultiKiosk] Restarting all Chrome instances');
+
+    if (this.isShellModeOnWindows()) {
+      if (this.desiredScreenMap.length === 0) {
+        return this.getStatus();
+      }
+      this.killShellManagedBrowsers();
+      await new Promise((r) => setTimeout(r, 2_000));
+      return this.applyScreenMap(this.desiredScreenMap, identity);
+    }
+
+    const mappings: ScreenMapping[] = [];
+    for (const [, instance] of this.instances) {
+      mappings.push({ hardwareId: instance.mappingId, url: instance.mappingUrl, label: undefined });
+    }
 
     await this.killAll({ clearDesired: false });
     await new Promise((r) => setTimeout(r, 2_000));
@@ -296,12 +405,24 @@ export class MultiScreenKioskManager {
     return this.applyScreenMap(this.desiredScreenMap, id);
   }
 
-  /** Get status of all screen instances */
-  getStatus(): MultiScreenKioskStatus {
-    const screens: SingleScreenStatus[] = [];
-    for (const [, instance] of this.instances) {
-      const running = instance.process !== null && instance.process.exitCode === null;
-      screens.push({
+  /** Get status of all screen instances */
+  getStatus(): MultiScreenKioskStatus {
+    if (this.isShellModeOnWindows() && this.desiredIdentity && this.desiredScreenMap.length > 0) {
+      return {
+        screens: this.desiredScreenMap.map((mapping, index) => ({
+          hardwareId: String(mapping.hardwareId || '').trim() || String(index + 1),
+          url: this.buildUrl(mapping.url || this.config.defaultUrl, this.desiredIdentity!, index),
+          running: false,
+          pid: null,
+          uptimeMs: null,
+        })),
+      };
+    }
+
+    const screens: SingleScreenStatus[] = [];
+    for (const [, instance] of this.instances) {
+      const running = instance.process !== null && instance.process.exitCode === null;
+      screens.push({
         hardwareId: instance.hardwareId,
         url: instance.url,
         running,
@@ -313,10 +434,13 @@ export class MultiScreenKioskManager {
     return { screens };
   }
 
-  /** Check if any screens are actively managed */
-  isActive(): boolean {
-    return this.instances.size > 0;
-  }
+  /** Check if any screens are actively managed */
+  isActive(): boolean {
+    if (this.isShellModeOnWindows()) {
+      return this.desiredScreenMap.length > 0;
+    }
+    return this.instances.size > 0;
+  }
 
   /** Cleanup on agent shutdown */
   destroy(): void {