ispyx 1.0.6 → 1.1.0

package/README.md

@@ -2,6 +2,8 @@
 
 # ispyx
 
+<p align="center"><a href="docs/showcase/ispyx-demo.mp4"><img src="docs/showcase/ispyx-demo.gif" alt="ispyx demo: an AI clicks, drags cards between columns, types and scrolls while an eye fires a beam at the pointer" width="720"></a></p>
+
 A local desktop-control [MCP](https://modelcontextprotocol.io) server. It lets an AI assistant use your computer the way a person does: look at the screen, move the mouse, click, drag, scroll, type, press hotkeys and use the clipboard.
 
 - Runs on your machine, talks to the AI app over **stdio**, opens **no network port** (the settings panel only listens while it is open).

package/native/win32-unlock/provider/install.ps1

@@ -0,0 +1,84 @@
+# Elevated setup step for the "let the AI unlock this PC" feature. Run by src/platform/win32/unlock.js via
+# Start-Process -Verb RunAs (one UAC prompt, per docs/unlock-windows.md). Never called with the password as a
+# plain argument: SecretFile is a path to a temp file (domain\nusername\npassword) that this script reads once
+# and deletes, so the password never appears in a process command line (visible via Task Manager / WMI).
+# ResultFile: Start-Process -Verb RunAs runs this in its own console with no stdout/stderr redirection back to
+# the caller (confirmed: -RedirectStandardOutput is rejected together with -Verb, same as -WindowStyle), so the
+# only way the caller learns what happened is this file.
+param(
+    [Parameter(Mandatory)][string]$SecretFile,
+    [Parameter(Mandatory)][string]$DllPath,
+    [Parameter(Mandatory)][string]$ResultFile
+)
+Set-StrictMode -Version 2
+$ErrorActionPreference = 'Stop'
+
+try {
+    $lines = Get-Content -Path $SecretFile -Encoding UTF8
+    $domain = $lines[0]
+    $username = $lines[1]
+    $password = $lines[2]
+    if ([string]::IsNullOrEmpty($domain)) { $domain = $env:COMPUTERNAME }
+    if ([string]::IsNullOrEmpty($username) -or [string]::IsNullOrEmpty($password)) {
+        throw 'Missing username or password.'
+    }
+
+    Add-Type -AssemblyName System.Security
+
+    $root = 'C:\ProgramData\ispyx'
+    New-Item -ItemType Directory -Force -Path $root | Out-Null
+    icacls $root /inheritance:r | Out-Null
+    icacls $root /grant 'SYSTEM:(OI)(CI)F' 'Administrators:(OI)(CI)F' | Out-Null
+
+    function Write-LenPrefixed([System.IO.MemoryStream]$ms, [string]$s) {
+        $bytes = [System.Text.Encoding]::UTF8.GetBytes($s)
+        $ms.Write([BitConverter]::GetBytes([uint32]$bytes.Length), 0, 4)
+        $ms.Write($bytes, 0, $bytes.Length)
+    }
+    $ms = New-Object System.IO.MemoryStream
+    Write-LenPrefixed $ms $domain
+    Write-LenPrefixed $ms $username
+    Write-LenPrefixed $ms $password
+    $plain = $ms.ToArray()
+    $protected = [System.Security.Cryptography.ProtectedData]::Protect($plain, $null, [System.Security.Cryptography.DataProtectionScope]::LocalMachine)
+    [Array]::Clear($plain, 0, $plain.Length) # best effort; managed GC may have copied it already
+
+    $secretPath = Join-Path $root 'unlock.secret'
+    [System.IO.File]::WriteAllBytes($secretPath, $protected)
+    icacls $secretPath /inheritance:r | Out-Null
+    icacls $secretPath /grant 'SYSTEM:F' 'Administrators:F' | Out-Null
+
+    # The resident (this same user, not elevated day to day) needs write access to just this one file. (A
+    # named Win32 event was tried here instead, to drop the watcher's poll loop entirely -- reverted: a named
+    # kernel object only exists while some process holds a handle open, and nothing in this architecture runs
+    # continuously between an enable() and a much later signal() to be that holder. See docs/unlock-windows.md.
+    # The watcher still avoids polling, via FindFirstChangeNotificationW on this directory instead.)
+    $signalPath = Join-Path $root 'unlock.signal'
+    if (-not (Test-Path $signalPath)) { New-Item -ItemType File -Path $signalPath | Out-Null }
+    $me = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+    icacls $signalPath /inheritance:r | Out-Null
+    icacls $signalPath /grant 'SYSTEM:F' 'Administrators:F' "${me}:M" | Out-Null
+
+    # regsvr32's exit code is not trustworthy with /s (confirmed in docs/unlock-windows.md); verify by reading
+    # the registry back instead of trusting $LASTEXITCODE.
+    # LogonUI loads this DLL as SYSTEM, so it must live somewhere only admins can write -- never in the npm
+    # package dir (user-writable): that would let any local user swap it and get code running as SYSTEM.
+    $installedDll = Join-Path $root 'ispyx_unlock.dll'
+    try { Copy-Item -Path $DllPath -Destination $installedDll -Force } catch {
+        # Already loaded by LogonUI from a previous install: keep it if it is byte-identical.
+        if (-not (Test-Path $installedDll) -or (Get-FileHash $installedDll).Hash -ne (Get-FileHash $DllPath).Hash) { throw }
+    }
+    regsvr32.exe /s $installedDll 2>$null
+    $actual = (Get-ItemProperty -Path 'HKLM:\SOFTWARE\Classes\CLSID\{1aa7e1e6-21de-4ad5-ae6e-454401b4b427}\InprocServer32' -Name '(default)' -ErrorAction SilentlyContinue).'(default)'
+    if ($actual -ne $installedDll) {
+        throw "Registration did not take effect (registry has '$actual', expected '$installedDll')."
+    }
+
+    Set-Content -Path $ResultFile -Value 'OK' -NoNewline
+    exit 0
+} catch {
+    Set-Content -Path $ResultFile -Value "ERROR: $($_.Exception.Message)" -NoNewline
+    exit 1
+} finally {
+    Remove-Item -Path $SecretFile -Force -ErrorAction SilentlyContinue
+}

package/native/win32-unlock/provider/uninstall.ps1

@@ -0,0 +1,17 @@
+# Elevated teardown for the "let the AI unlock this PC" feature: unregisters the Credential Provider and deletes
+# the stored secret and the installed DLL copy. Run by src/platform/win32/unlock.js via Start-Process -Verb
+# RunAs. See install.ps1 for why ResultFile exists (no stdout/stderr redirection back to the caller with -Verb RunAs).
+param(
+    [Parameter(Mandatory)][string]$ResultFile
+)
+Set-StrictMode -Version 2
+$ErrorActionPreference = 'Continue' # best effort: still clean up what we can if one step fails
+
+$root = 'C:\ProgramData\ispyx'
+regsvr32.exe /u /s (Join-Path $root 'ispyx_unlock.dll') 2>$null
+Remove-Item -Path (Join-Path $root 'unlock.secret') -Force -ErrorAction SilentlyContinue
+Remove-Item -Path (Join-Path $root 'unlock.signal') -Force -ErrorAction SilentlyContinue
+# May be held open by a running LogonUI until the next lock cycle; harmless once unregistered.
+Remove-Item -Path (Join-Path $root 'ispyx_unlock.dll') -Force -ErrorAction SilentlyContinue
+Set-Content -Path $ResultFile -Value 'OK' -NoNewline
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ispyx",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Local desktop-control MCP server: lets an AI use your keyboard, mouse and screen (windows, screenshots, clicks, typing, clipboard). stdio only, Windows and macOS.",
   "type": "module",
   "main": "src/server.js",
@@ -9,6 +9,9 @@
   },
   "files": [
     "src/",
+    "native/win32-unlock/bin/",
+    "native/win32-unlock/provider/install.ps1",
+    "native/win32-unlock/provider/uninstall.ps1",
     "README.md",
     "LICENSE",
     "config.example.json"
@@ -48,6 +51,7 @@
     "hook-test": "node test/hook-life.js",
     "shutdown-test": "node test/shutdown-all.js",
     "scan-test": "node test/scan.js",
+    "laser-test": "node test/laser.js",
     "radar-multi-test": "node test/radar-multi.js",
     "scan-multi-test": "node test/scan-multi.js",
     "auth-test": "node test/auth.js",

package/src/core/panel/README.md

@@ -31,6 +31,7 @@ Only `version` and `platform` are required. Every other key is optional and the
   recent: [{ time, tool, summary }],          // time = epoch ms
   stopLabel,                                  // e.g. "Esc x3" or "⌥ Option + Esc"
   effectsEnabled, passwordSet, denylist: [],
+  unlockSupported, unlockEnabled,             // win32 only: "Let the AI unlock this PC"
   autostart: boolean, autostartLabel?,        // label defaults by platform
   permissions: [{ id: 'accessibility' | 'screen-recording', title, detail, granted }],
   connect: { claudeCodeCommand, desktopConfigJson, desktopConfigPath } }
@@ -51,6 +52,7 @@ Sections, top to bottom: header (icon, headline, status, version/uptime/pid), Pe
 | `openPermissionSettings` | permission id | "Open Settings" |
 | `showConfigFile` | none | reveal `desktopConfigPath` (or its folder) |
 | `copy` | text | clipboard fallback; the page tries `navigator.clipboard` first |
+| `setUnlock` | `{on, password, current}` | win32 only; "Let the AI unlock this PC". Always the resident's own account. `current` is the ispyx panel password, asked for when one is set (same as `removeDeny`) |
 
 ## Windows server (`index.js`)
 

package/src/core/panel/index.js

@@ -8,14 +8,14 @@ import { fileURLToPath } from 'node:url';
 const PAGE = fileURLToPath(new URL('./page.html', import.meta.url));
 const COOKIE = 'ispyx_panel';
 // Explicit whitelist; an action is also callable only if the host's `actions` object defines it.
-const ACTIONS = ['quit', 'setAutostart', 'setEffects', 'openLog', 'copy', 'close', 'requestPermission', 'openPermissionSettings', 'showConfigFile', 'clearRecent', 'addDeny', 'removeDeny', 'setPassword', 'setAuthRequired', 'update', 'checkUpdate'];
+const ACTIONS = ['quit', 'setAutostart', 'setEffects', 'openLog', 'copy', 'close', 'requestPermission', 'openPermissionSettings', 'showConfigFile', 'clearRecent', 'addDeny', 'removeDeny', 'setPassword', 'setAuthRequired', 'setUnlock', 'update', 'checkUpdate'];
 const BOOL_ACTIONS = new Set(['setAutostart', 'setEffects']);
 const STRING_ACTIONS = new Set(['copy', 'requestPermission', 'openPermissionSettings', 'addDeny']); // value must be a short string
-// value is an object of short strings (and a boolean for setAuthRequired.on)
-const OBJECT_ACTIONS = { setPassword: ['current', 'next'], setAuthRequired: ['current'], removeDeny: ['name', 'current'] };
+// value is an object of short strings (and a boolean for setAuthRequired.on / setUnlock.on)
+const OBJECT_ACTIONS = { setPassword: ['current', 'next'], setAuthRequired: ['current'], removeDeny: ['name', 'current'], setUnlock: ['password', 'current'] };
 const objectOk = (name, v) => {
   if (!v || typeof v !== 'object' || Array.isArray(v)) return false;
-  if (name === 'setAuthRequired' && typeof v.on !== 'boolean') return false;
+  if ((name === 'setAuthRequired' || name === 'setUnlock') && typeof v.on !== 'boolean') return false;
   return OBJECT_ACTIONS[name].every((k) => v[k] === undefined || (typeof v[k] === 'string' && v[k].length <= 200));
 };
 const PERMISSION_IDS = new Set(['accessibility', 'screen-recording']);

package/src/core/panel/page.html

@@ -37,6 +37,7 @@ h2{font-size:11px;letter-spacing:.05em;text-transform:uppercase;color:var(--mute
 button{font:inherit;color:var(--fg);background:var(--card);border:1px solid var(--line);border-radius:7px;padding:4px 12px;cursor:pointer;box-shadow:0 1px 0 rgba(0,0,0,.04)}
 button:hover{background:var(--fill)}
 button:active{filter:brightness(.95)}
+button:disabled{opacity:.55;cursor:default;filter:none}
 button:focus-visible,.sw input:focus-visible+i{outline:2px solid var(--acc);outline-offset:2px}
 button.pri{background:var(--acc);border-color:var(--acc);color:var(--accfg);font-weight:600}
 button.pri:hover{filter:brightness(.96);background:var(--acc)}
@@ -155,6 +156,14 @@ button.link:hover{background:none;color:var(--fg)}
   </div>
 </section>
 
+<section id="sUnlock" hidden>
+  <h2>Unattended unlock</h2>
+  <div class="card">
+    <div class="item line" id="rUnlock" hidden><label for="unlockOn">Let the AI unlock this PC</label><span class="sw"><input type="checkbox" id="unlockOn"><i></i></span></div>
+    <div class="item" id="rUnlockNote" hidden><p class="note">Weakens the lock screen on purpose: stores this account's Windows password so the AI can unlock a locked session without you there. Needs a local account with a password (not a Microsoft-account PIN sign-in).</p></div>
+  </div>
+</section>
+
 <dialog id="dlg">
   <form id="dlgForm">
     <h3 id="dlgT"></h3>
@@ -316,6 +325,10 @@ function render(s){
   show("sSafe",hasPw||hasDeny||hasAuth);show("rPw",hasPw);show("rAuth",hasAuth);show("rDeny",hasDeny);
   if(hasPw){setText("pwTxt",s.passwordSet?"Password is set":"No password yet");setText("pwBtn",s.passwordSet?"Change…":"Set…")}
   if(hasAuth&&!busy.authOn)$("authOn").checked=s.authRequired;
+
+  var hasUnlock=typeof s.unlockSupported==="boolean";
+  show("sUnlock",hasUnlock);show("rUnlock",hasUnlock);show("rUnlockNote",hasUnlock);
+  if(hasUnlock&&!busy.unlockOn)$("unlockOn").checked=!!s.unlockEnabled;
   if(hasDeny){
     var d=$("deny"),sig=s.denylist.join("\n")+"|"+!!s.passwordSet;
     if(d.dataset.sig!==sig){ // rebuild only on change so a click is never lost to the 1 s refresh
@@ -416,6 +429,22 @@ $("authOn").addEventListener("change",function(){
   }
   act("setAuthRequired",{on:want,current:undefined}).catch(function(){box.checked=!want}).then(done);
 });
+$("unlockOn").addEventListener("change",function(){
+  var want=$("unlockOn").checked,box=$("unlockOn");
+  busy.unlockOn=true;
+  var done=function(){busy.unlockOn=false;poll()};
+  if(want){
+    box.checked=false;
+    ask("Let the AI unlock this PC",[{id:"password",label:"Windows password"}],"Turn on",function(v){return act("setUnlock",{on:true,password:v.password})});
+    done();return;
+  }
+  if(last&&last.passwordSet){
+    box.checked=true;
+    ask("Turn off unattended unlock",[{id:"current",label:"Ispyx password"}],"Turn off",function(v){return act("setUnlock",{on:false,current:v.current})});
+    done();return;
+  }
+  act("setUnlock",{on:false}).catch(function(){box.checked=true}).then(done);
+});
 function removeDeny(name){
   if(last&&last.passwordSet){
     ask("Remove "+name,[{id:"current",label:"Password"}],"Remove",function(v){return act("removeDeny",{name:name,current:v.current})});

package/src/core/resident.js

@@ -11,8 +11,10 @@
 //   ./panel/index.js     startPanel({ getState, actions }) -> { url, close() }   (local web panel)
 //
 //   getState() -> { version, platform, pid, uptimeMs, clients, recent: [{ time, tool, summary }],
-//                   stopLabel, effectsEnabled, passwordSet, denylist, autostart, connect (win32) }
-//   actions    -> { quit(), setAutostart(bool), setEffects(bool), clearRecent(), showConfigFile() }
+//                   stopLabel, effectsEnabled, passwordSet, denylist, autostart, connect (win32),
+//                   unlockSupported, unlockEnabled (win32 only, when platform.unlock exists) }
+//   actions    -> { quit(), setAutostart(bool), setEffects(bool), clearRecent(), showConfigFile(),
+//                   setUnlock({on, password, current}) (win32 only) }
 //
 // Control calls over the pipe (names start with "__", handled here, never reach the tools):
 //   __ping -> 'pong'      __panel -> panel url ('' if none)      __quit -> 'bye' and the resident shuts down.
@@ -139,6 +141,7 @@ export function panelModel(ctx) {
     passwordSet: safe(() => auth.passwordSet(), false),
     authRequired: !!config.auth,
     denylist: config.denylist.slice(),
+    ...(w.unlock ? { unlockSupported: true, unlockEnabled: safe(() => w.unlock.isEnabled(), false) } : {}),
     ...(updates.state() ? { update: { ...updates.state(), ...(running ? running.progress() : {}) } } : {}),
   });
   const actions = {
@@ -176,6 +179,16 @@ export function panelModel(ctx) {
       return true;
     },
     checkUpdate: async () => { await updates.check(); return updates.state(); },
+    // Turning this on lowers the lock screen's protection, so it asks for the ispyx password when one is set,
+    // same as removeDeny. w.unlock.enable/disable throw a plain message (wrong account type, UAC cancelled, ...).
+    setUnlock: async ({ on, password, current } = {}) => {
+      if (!w.unlock) throw new PanelError('Not available on this platform.');
+      if (auth.passwordSet() && !auth.verify(current)) throw new PanelError('The password is wrong.');
+      try {
+        if (on) await w.unlock.enable({ password });
+        else await w.unlock.disable();
+      } catch (e) { throw new PanelError(e.message); }
+    },
   };
   return { getState, actions, stop: () => updates.stop() };
 }

package/src/core/server.js

@@ -101,6 +101,15 @@ function playTrail(a, z, button, opts) {
   effects.add(run);
   return stop;
 }
+/** drag: an eye beside the line fires a beam at the pointer's heels (scorch fades after a couple of seconds); the returned function ends it. */
+function playLaser(a, z) {
+  const epoch = guard.epoch;
+  let stop;
+  const stopped = new Promise((r) => { stop = r; });
+  const run = scan.laser({ x: a.sx, y: a.sy }, { x: z.sx, y: z.sy }, stopped, () => guard.epoch !== epoch).finally(() => effects.delete(run));
+  effects.add(run);
+  return stop;
+}
 /** scroll: chevrons beside the pointer while the wheel turns; the returned function ends it. */
 function playWheelCue(p, vert, horiz) {
   const epoch = guard.epoch;
@@ -594,7 +603,8 @@ server.registerTool('drag', {
     await w.sleep(40);
     w.mouseDown(b);
     guard.heldButtons.add(b);
-    const stopTrail = playTrail(a, z2, b);
+    const stopTrail = playTrail(a, z2, b, { line: false }); // start ring and end ring; the beam draws the path
+    const stopLaser = playLaser(a, z2);
     try {
       await w.sleep(40);
       await glide(z2, args, { trail: false });
@@ -603,6 +613,7 @@ server.registerTool('drag', {
       w.mouseUp(b);
       guard.heldButtons.delete(b);
       stopTrail();
+      stopLaser();
     }
   });
   return json({ ok: true, from: { x: a.sx, y: a.sy }, to: { x: z2.sx, y: z2.sy } });
@@ -801,6 +812,21 @@ server.registerTool('set_clipboard', {
   return json({ ok: true, kind: 'file', path: p });
 }, { session: false }));
 
+server.registerTool('unlock', {
+  description: 'Unlocks the Windows session if it is currently locked, using the account password stored earlier in the panel ("Let the AI unlock this PC"). Takes no input. Fails if that feature was never turned on, or if the screen is not actually locked.',
+}, action('unlock', async () => {
+  if (!w.unlock) throw new ToolError('Unattended unlock is not available on this platform.');
+  if (!w.unlock.isEnabled()) throw new ToolError('Unattended unlock was never turned on. Ask the user to enable "Let the AI unlock this PC" in the panel.');
+  if (!w.isScreenLocked()) return json({ ok: true, alreadyUnlocked: true });
+  w.unlock.signal();
+  const deadline = Date.now() + 10000;
+  while (Date.now() < deadline) {
+    await w.sleep(300);
+    if (!w.isScreenLocked()) return json({ ok: true });
+  }
+  throw new ToolError('Signalled the unlock but the screen is still locked after 10 s. The stored password may be wrong, or the account may no longer qualify.');
+}, { session: false }));
+
 // ---------------------------------------------------------------- run
 
 process.on('exit', () => guard?.releaseAll());

package/src/effects/laser.js

@@ -0,0 +1,182 @@
+// The drag laser: an eye beside the drag line fires a thick beam at the spot just behind the pointer, as if the pointer
+// were running from it. Pure drawing into premultiplied BGRA buffers (Layer.px) and the placement rules; scan.js
+// runs it (ScanAnimation.laser). Colours stay in the ispyx green family, brighter and glassier than the flat trail.
+
+const clamp = (v, lo = 0, hi = 1) => Math.min(hi, Math.max(lo, v));
+const mix = (a, b, t) => a + (b - a) * t;
+const smooth = (t) => t * t * (3 - 2 * t);
+
+export const LASER_EYE_SIZE = 112;
+export const BURN_LIFE_MS = 2000;
+export const BEAM_WIDTH = 26; // half-width in px of the full beam
+
+/**
+ * Where the eye goes: beside the line a -> b (never on it), at a random place along it and on a random side, as far
+ * from the line as the monitor `mon` {x, y, width, height} allows (up to size/2 + 190 px). Returns the eye centre.
+ */
+export function placeEye(a, b, mon, size = LASER_EYE_SIZE, rand = Math.random) {
+  const len = Math.hypot(b.x - a.x, b.y - a.y) || 1;
+  const nx = -(b.y - a.y) / len, ny = (b.x - a.x) / len;
+  const f = 0.3 + 0.4 * rand();
+  const mx = a.x + (b.x - a.x) * f, my = a.y + (b.y - a.y) * f;
+  const half = size / 2, margin = 10;
+  const fits = (c) => c.x - half >= mon.x + margin && c.x + half <= mon.x + mon.width - margin && c.y - half >= mon.y + margin && c.y + half <= mon.y + mon.height - margin;
+  const first = rand() < 0.5 ? 1 : -1;
+  for (const d of [half + 190, half + 130, half + 80]) {
+    for (const s of [first, -first]) {
+      const c = { x: mx + nx * s * d, y: my + ny * s * d };
+      if (fits(c)) return c;
+    }
+  }
+  // no room on either side (a drag across a whole small screen): the side with more room, kept on the monitor
+  const c = { x: mx + nx * first * (half + 80), y: my + ny * first * (half + 80) };
+  return { x: clamp(c.x, mon.x + margin + half, mon.x + mon.width - margin - half), y: clamp(c.y, mon.y + margin + half, mon.y + mon.height - margin - half) };
+}
+
+/** Premultiplied "over": add colour (r, g, b) with coverage a at pixel index i. */
+function over(px, i, r, g, b, a) {
+  if (a <= 0) return;
+  const k = 1 - a;
+  px[i] = b * a + px[i] * k; px[i + 1] = g * a + px[i + 1] * k; px[i + 2] = r * a + px[i + 2] * k; px[i + 3] = a * 255 + px[i + 3] * k;
+}
+
+/** A glowing flare at (cx, cy): white core, green/cyan halo, a ring and slowly turning spikes. `w` is the beam half-width. */
+function flare(px, W, H, cx, cy, w, tMs, strength) {
+  const R = Math.ceil(w * 3.6);
+  const rot = tMs * 0.0011;
+  // cos(6 * (angle + rot)) without atan2/cos per pixel: (cos a + i sin a)^6 rotated by 6 * rot
+  const cr = Math.cos(6 * rot), sr = Math.sin(6 * rot);
+  for (let y = Math.max(0, Math.floor(cy - R)); y <= Math.min(H - 1, Math.ceil(cy + R)); y++) {
+    for (let x = Math.max(0, Math.floor(cx - R)); x <= Math.min(W - 1, Math.ceil(cx + R)); x++) {
+      const dx = x + 0.5 - cx, dy = y + 0.5 - cy;
+      const r = Math.sqrt(dx * dx + dy * dy);
+      if (r > R) continue;
+      const i = (y * W + x) * 4;
+      const halo = Math.exp(-((r / (w * 2.1)) ** 2)) * 0.55 * strength;
+      over(px, i, 40, 235, 170, halo);
+      const ring = clamp(1 - Math.abs(r - w * 1.9) / 1.6) * 0.55 * strength;
+      over(px, i, 170, 255, 220, ring);
+      const c1 = r > 0 ? dx / r : 1, s1 = r > 0 ? dy / r : 0;
+      const c2 = c1 * c1 - s1 * s1, s2 = 2 * c1 * s1; // angle x2
+      const c6 = c2 * (c2 * c2 - s2 * s2) - s2 * (2 * c2 * s2), s6 = s2 * (c2 * c2 - s2 * s2) + c2 * (2 * c2 * s2); // x2 * x3 = x6
+      const k = Math.max(0, c6 * cr - s6 * sr);
+      const k2 = k * k, k4 = k2 * k2, k16 = k4 * k4 * k4 * k4; // k^22 = k^16 * k^4 * k^2
+      const spike = k16 * k4 * k2 * Math.exp(-r / (w * 1.5)) * 0.9 * strength;
+      over(px, i, 200, 255, 225, spike);
+      const core = Math.exp(-((r / (w * 1.05)) ** 2)) * strength;
+      over(px, i, 240, 255, 246, core);
+    }
+  }
+}
+
+/**
+ * The beam from (ax, ay) to (bx, by) with half-width `w` (0 = off): rounded ends and the same width all along, a soft green glow, an emerald body that
+ * darkens towards its rim, a white-green core, energy bands running along it, and a flare at each end.
+ * `tMs` animates the bands and the spikes.
+ */
+export function renderBeam(px, W, H, ax, ay, bx, by, w, tMs) {
+  if (w < 0.5) return;
+  const len = Math.hypot(bx - ax, by - ay) || 1;
+  const ux = (bx - ax) / len, uy = (by - ay) / len;
+  const pad = Math.ceil(w * 3.2);
+  const x0 = Math.max(0, Math.floor(Math.min(ax, bx) - pad)), x1 = Math.min(W - 1, Math.ceil(Math.max(ax, bx) + pad));
+  const y0 = Math.max(0, Math.floor(Math.min(ay, by) - pad)), y1 = Math.min(H - 1, Math.ceil(Math.max(ay, by) + pad));
+  const reach2 = (w * 3.1) ** 2;
+  for (let y = y0; y <= y1; y++) {
+    for (let x = x0; x <= x1; x++) {
+      const dx = x + 0.5 - ax, dy = y + 0.5 - ay;
+      const s = clamp(dx * ux + dy * uy, 0, len); // rounded ends: distance to the segment
+      const ex = dx - s * ux, ey = dy - s * uy;
+      const d2 = ex * ex + ey * ey;
+      if (d2 > reach2) continue; // most of a diagonal beam's box: no square root, nothing drawn
+      const d = Math.sqrt(d2);
+      const i = (y * W + x) * 4;
+      const hw = w; // the same width along its whole length
+      over(px, i, 20, 200, 120, Math.exp(-((d / (hw * 2.3)) ** 2)) * 0.5); // outer glow
+      const body = clamp(hw - d + 0.5);
+      if (body > 0) {
+        const band = 0.86 + 0.14 * Math.sin(s * 0.11 - tMs * 0.045);
+        const e = clamp(d / hw);
+        const k = e * e; // 0 in the middle, 1 on the rim
+        over(px, i, mix(70, 8, k) * band, mix(255, 130, k) * band, mix(150, 80, k) * band, body * 0.97);
+        const core = clamp(hw * 0.52 - d + 0.5) * (0.9 + 0.1 * band);
+        over(px, i, 238, 255, 244, core);
+      }
+    }
+  }
+  flare(px, W, H, ax, ay, w, tMs, 0.85);
+  flare(px, W, H, bx, by, w, tMs + 400, 1);
+}
+
+/**
+ * A thick line piece (a capsule); the stronger alpha wins where pieces overlap (so a burn trail has no beads at its
+ * joints). Each pixel of the bounding box is visited once and shaded by its distance to the segment: the burn
+ * redraws every piece every frame, and stamping a disc at each pixel along the line cost ~30x more.
+ */
+export function stroke(px, W, H, x0, y0, x1, y1, radius, rgb, alpha) {
+  const R = radius + 1;
+  const xa = Math.max(0, Math.floor(Math.min(x0, x1) - R)), xb = Math.min(W - 1, Math.ceil(Math.max(x0, x1) + R));
+  const ya = Math.max(0, Math.floor(Math.min(y0, y1) - R)), yb = Math.min(H - 1, Math.ceil(Math.max(y0, y1) + R));
+  const dx = x1 - x0, dy = y1 - y0, len2 = dx * dx + dy * dy;
+  const b = rgb[2], g = rgb[1], r = rgb[0];
+  for (let y = ya; y <= yb; y++) {
+    const py = y + 0.5 - y0;
+    for (let x = xa; x <= xb; x++) {
+      const qx = x + 0.5 - x0;
+      const u = len2 > 0 ? Math.min(1, Math.max(0, (qx * dx + py * dy) / len2)) : 0;
+      const ex = qx - u * dx, ey = py - u * dy;
+      const a = clamp(radius + 0.5 - Math.sqrt(ex * ex + ey * ey)) * alpha;
+      if (a <= 0) continue;
+      const i = (y * W + x) * 4;
+      if (a * 255 <= px[i + 3]) continue;
+      px[i] = b * a; px[i + 1] = g * a; px[i + 2] = r * a; px[i + 3] = a * 255;
+    }
+  }
+}
+
+/**
+ * The scorch the beam leaves: pts = [{ x, y, t }] (buffer pixels, ms stamps), now = ms. Fresh pieces glow lime-white,
+ * cool to a charred dark line with a faint green ember rim, and disappear after BURN_LIFE_MS.
+ */
+export function renderBurn(px, W, H, pts, now) {
+  for (let pass = 0; pass < 3; pass++) {
+    for (let k = 1; k < pts.length; k++) {
+      const age = now - pts[k].t;
+      const fade = Math.pow(clamp(1 - age / BURN_LIFE_MS), 0.8);
+      if (fade <= 0.02) continue;
+      const A = pts[k - 1], B = pts[k];
+      if (pass === 0) stroke(px, W, H, A.x, A.y, B.x, B.y, 13, [22, 120, 66], 0.3 * fade);
+      else if (pass === 1) stroke(px, W, H, A.x, A.y, B.x, B.y, 9, [10, 16, 13], 0.82 * fade);
+      else {
+        const heat = clamp(1 - age / 320);
+        if (heat <= 0.03) continue;
+        stroke(px, W, H, A.x, A.y, B.x, B.y, 3.5 + 5 * heat, [mix(90, 235, heat), 255, mix(130, 215, heat)], heat * 0.95);
+      }
+    }
+  }
+}
+
+/** Sparks flying off the impact point: [{ x, y, vx, vy, t0, life }] (px, px/ms, ms). Returns the ones still alive. */
+export function renderSparks(px, W, H, sparks, now) {
+  const alive = [];
+  for (const s of sparks) {
+    const age = now - s.t0;
+    if (age >= s.life) continue;
+    alive.push(s);
+    const f = 1 - age / s.life;
+    const x = s.x + s.vx * age, y = s.y + s.vy * age + 0.0005 * age * age;
+    const px0 = x - s.vx * 26 * f, py0 = y - s.vy * 26 * f;
+    stroke(px, W, H, px0, py0, x, y, 0.9 + 1.2 * f, [210, 255, 225], f);
+  }
+  return alive;
+}
+
+/** New sparks at (x, y), flying away from the beam source (ax, ay) in a fan. */
+export function spawnSparks(list, x, y, ax, ay, now, count = 2, rand = Math.random) {
+  const base = Math.atan2(y - ay, x - ax);
+  for (let n = 0; n < count; n++) {
+    const ang = base + (rand() - 0.5) * 2.4;
+    const v = 0.12 + rand() * 0.34;
+    list.push({ x, y, vx: Math.cos(ang) * v, vy: Math.sin(ang) * v, t0: now, life: 260 + rand() * 260 });
+  }
+}

package/src/effects/scan.js

@@ -2,6 +2,7 @@
 // a glowing green scan line that sweeps the region from top to bottom. Two click-through, per-pixel-alpha windows;
 // pixels are drawn in software into DIB sections, so nothing here depends on GDI+.
 import platform from '../platform/index.js';
+import { LASER_EYE_SIZE, BEAM_WIDTH, BURN_LIFE_MS, placeEye, renderBeam, renderBurn, renderSparks, spawnSparks } from './laser.js';
 
 const clamp = (v, lo = 0, hi = 1) => Math.min(hi, Math.max(lo, v));
 const mix = (a, b, t) => a + (b - a) * t;
@@ -310,7 +311,7 @@ export class ScanAnimation {
    * fading with age. When `stopped` resolves (button released) the trail fades out and rings mark the end.
    * `bounds` {left, top, right, bottom}: where the drag can go. Never throws.
    */
-  async trail(start, bounds, stopped, cancelled = () => false, button = 'left', { marker: showMarker = true, life = TRAIL_LIFE_MS, ring = true } = {}) {
+  async trail(start, bounds, stopped, cancelled = () => false, button = 'left', { marker: showMarker = true, life = TRAIL_LIFE_MS, ring = true, line = true } = {}) {
     if (!this.enabled) return;
     let layer = null;
     let ended = false;
@@ -338,7 +339,7 @@ export class ScanAnimation {
         }
         layer.px.fill(0);
         const fade = endAt ? 1 - clamp((t - endAt) / TRAIL_FADE_MS) : 1;
-        for (let pass = 0; pass < 2; pass++) {
+        for (let pass = 0; pass < (line ? 2 : 0); pass++) {
           for (let k = 1; k < pts.length; k++) {
             const age = (endAt ? Math.min(t, endAt) : t) - pts[k].t;
             const a = clamp(1 - age / life) * fade;
@@ -370,6 +371,97 @@ export class ScanAnimation {
     }
   }
 
+  /**
+   * drag: an eye opens beside the drag line (random side, random place along it) and fires a thick beam at the spot just
+   * behind the pointer, as if the pointer were running from it; the beam leaves a scorch that fades after a couple of
+   * seconds. Runs until the beam and the scorch are gone. `start`/`end` are desktop pixels. Never throws.
+   */
+  async laser(start, end, stopped, cancelled = () => false) {
+    if (!this.enabled || Math.hypot(end.x - start.x, end.y - start.y) < 80) return;
+    const FIRE = 260, LAG = 130, HOLD = 260, MIN_BEAM = 520, CUT = 180, EYE_CLOSE = 300;
+    let beam = null, eye = null;
+    let ended = false;
+    stopped.then(() => { ended = true; });
+    try {
+      platform.ensurePump();
+      const v = platform.virtualScreen();
+      const mid = { x: (start.x + end.x) / 2, y: (start.y + end.y) / 2 };
+      const mon = platform.listMonitors().find((q) => mid.x >= q.left && mid.x < q.left + q.width && mid.y >= q.top && mid.y < q.top + q.height);
+      const area = mon ? { x: mon.left, y: mon.top, width: mon.width, height: mon.height } : v;
+      const size = LASER_EYE_SIZE;
+      const ec = placeEye(start, end, area, size);
+      const ex = Math.round(ec.x - size / 2), ey = Math.round(ec.y - size / 2);
+      const pad = 150;
+      const left = Math.max(v.x, Math.floor(Math.min(start.x, end.x, ex) - pad)), top = Math.max(v.y, Math.floor(Math.min(start.y, end.y, ey) - pad));
+      const right = Math.min(v.x + v.width, Math.ceil(Math.max(start.x, end.x, ex + size) + pad)), bottom = Math.min(v.y + v.height, Math.ceil(Math.max(start.y, end.y, ey + size) + pad));
+      beam = new platform.Layer(Math.max(40, right - left), Math.max(40, bottom - top));
+      eye = new platform.Layer(size, size);
+      const samples = [{ x: start.x, y: start.y, t: 0 }]; // where the pointer was, and when
+      const burn = [];
+      let sparks = [];
+      let endAt = 0, cutAt = 0, tau = 0, lastT = 0, lastBurn = 0, last = { x: start.x, y: start.y };
+      const pointAt = (u) => {
+        for (let k = 1; k < samples.length; k++) {
+          if (samples[k].t >= u) {
+            const a = samples[k - 1], b = samples[k];
+            const f = b.t > a.t ? (u - a.t) / (b.t - a.t) : 1;
+            return { x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f };
+          }
+        }
+        return { x: samples[samples.length - 1].x, y: samples[samples.length - 1].y };
+      };
+      const t0 = performance.now();
+      for (;;) {
+        const tf = performance.now(), t = tf - t0;
+        if (cancelled()) break;
+        if (!endAt) {
+          const c = platform.cursorPos();
+          if (Math.hypot(c.x - samples[samples.length - 1].x, c.y - samples[samples.length - 1].y) >= 1) samples.push({ x: c.x, y: c.y, t });
+          if (ended) { endAt = t; cutAt = Math.max(endAt + HOLD, FIRE + MIN_BEAM); samples.push({ x: samples[samples.length - 1].x, y: samples[samples.length - 1].y, t }); }
+        }
+        const eyeEnd = cutAt ? cutAt + CUT + EYE_CLOSE : Infinity;
+        const firing = t >= FIRE && !(cutAt && t >= cutAt + CUT);
+        const grow = ease(clamp((t - FIRE) / 120));
+        const shrink = cutAt ? 1 - ease(clamp((t - cutAt) / CUT)) : 1;
+        const w = BEAM_WIDTH * grow * shrink;
+        // the beam's end follows the pointer's path about LAG ms behind it, catching up fast from the start point
+        if (t >= FIRE) tau = Math.min(tau + (t - lastT) * 2.2, Math.max(0, t - LAG), samples[samples.length - 1].t);
+        lastT = t;
+        const T = t >= FIRE ? pointAt(tau) : samples[samples.length - 1];
+        const open = t < FIRE ? ease(t / FIRE) : cutAt && t >= cutAt + CUT ? 1 - ease(clamp((t - cutAt - CUT) / EYE_CLOSE)) : 1;
+        // the pupil looks at the beam's end
+        const dx = T.x - ec.x, dy = T.y - ec.y, dl = Math.hypot(dx, dy) || 1;
+        const gx = (dx / dl) * 0.95, gy = (dy / dl) * 0.95;
+        renderEye(eye.px, size, open, gx, gy, t < FIRE ? clamp((t - 70) / (FIRE - 70)) : 1);
+        const pp = pupilPos(size, gx, gy);
+        // the eye trembles while it fires (the beam starts at the shaken pupil)
+        const sh = firing ? 4.5 * grow * shrink : 0;
+        const sx = (Math.random() - 0.5) * 2 * sh, sy = (Math.random() - 0.5) * 2 * sh;
+        beam.px.fill(0);
+        if (firing && w >= 1 && Math.hypot(T.x - last.x, T.y - last.y) >= 1) {
+          burn.push({ x: T.x - left, y: T.y - top, t });
+          lastBurn = t;
+          last = { x: T.x, y: T.y };
+          spawnSparks(sparks, T.x - left, T.y - top, ex + pp.x - left, ey + pp.y - top, t);
+        }
+        renderBurn(beam.px, beam.width, beam.height, burn, t);
+        if (firing && w >= 1) renderBeam(beam.px, beam.width, beam.height, ex + sx + pp.x - left, ey + sy + pp.y - top, T.x - left, T.y - top, w, t);
+        sparks = renderSparks(beam.px, beam.width, beam.height, sparks, t);
+        beam.present(left, top, 255);
+        if (t < eyeEnd) eye.present(Math.round(ex + sx), Math.round(ey + sy), 255 * open);
+        else if (eye.shown) eye.present(ex, ey, 0, 1);
+        if (t >= eyeEnd && t - lastBurn > BURN_LIFE_MS && !sparks.length) break;
+        await new Promise((r) => setTimeout(r, Math.max(1, 16 - (performance.now() - tf))));
+      }
+    } catch (e) {
+      process.stderr.write(`ispyx: laser effect failed (${e.message})
+`);
+    } finally {
+      beam?.destroy();
+      eye?.destroy();
+    }
+  }
+
   /**
    * scroll: chevrons beside the pointer travel in the scroll direction while the wheel turns (until `stopped`
    * resolves, at least 380 ms, then a short fade). dirV: +1 up / -1 down / 0, dirH: +1 right / -1 left / 0. Never throws.

package/src/platform/CONTRACT.md

@@ -129,3 +129,9 @@ Other platforms may lack these; callers must feature-test (`if (platform.Tray)`)
   Quit. Methods: `setTooltip(s)`, `destroy()`. Re-adds itself when Explorer restarts. Callbacks never throw into the host.
 - `autostart` `{ get(), set(on), command() }`: per-user HKCU Run entry `Ispyx` that starts `src/server.js` hidden
   via `wscript.exe` + `%APPDATA%\ispyx\start.vbs`. `ISPYX_AUTOSTART_VALUE` overrides the value name (tests).
+- `unlock` (`src/platform/win32/unlock.js`): `{ isEnabled(), checkAccount(), enable({password}), disable(), signal() }`.
+  "Let the AI unlock this PC" (see `docs/unlock-windows.md`). Only ever unlocks the account the resident itself
+  runs as, so `enable` asks for just the password. `enable`/`disable` run an
+  elevated `.ps1` in `native/win32-unlock/provider/` (one UAC prompt each); `signal()` never needs elevation.
+  `checkAccount()` refuses PIN/Microsoft-account and passwordless sign-ins (no replayable secret exists for
+  those). The `unlock` MCP tool (`src/core/server.js`) calls `signal()` then polls `isScreenLocked()`.

package/src/platform/win32/index.js

@@ -28,4 +28,5 @@ export const dataDir = () => {
 };
 export { Layer, textMask } from './layer.js';
 export { Tray } from './tray.js';
+export * as unlock from './unlock.js';
 export { autostart } from './autostart.js';

package/src/platform/win32/unlock.js

@@ -0,0 +1,140 @@
+// Optional win32 feature: "Let the AI unlock this PC" (see docs/unlock-windows.md for the full design and what
+// was validated). All native work lives in native/win32-unlock/provider (Rust Credential Provider COM DLL,
+// built separately, not part of this package's install) and its install.ps1/uninstall.ps1, each one elevated
+// UAC prompt, never run automatically.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = 'C:\\ProgramData\\ispyx';
+const SECRET_PATH = path.join(ROOT, 'unlock.secret');
+const SIGNAL_PATH = path.join(ROOT, 'unlock.signal');
+const PROVIDER_DIR = fileURLToPath(new URL('../../../native/win32-unlock/provider/', import.meta.url));
+const DLL_PATH = fileURLToPath(new URL('../../../native/win32-unlock/bin/ispyx_unlock.dll', import.meta.url));
+
+function run(cmd, args) {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '', err = '';
+    p.stdout.on('data', (d) => { out += d; });
+    p.stderr.on('data', (d) => { err += d; });
+    p.on('close', (code) => resolve({ code, out, err }));
+    p.on('error', (e) => resolve({ code: -1, out, err: e.message }));
+  });
+}
+
+/**
+ * Runs a .ps1 elevated (one UAC prompt) and waits for it. Resolves { code, out }.
+ * -WindowStyle cannot be combined with -Verb RunAs in Windows PowerShell 5.1 (Start-Process throws a parameter
+ * error before the UAC prompt even appears) -- confirmed hitting exactly this, so it is deliberately omitted.
+ */
+function runElevated(scriptPath, args) {
+  const psArgs = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, ...args];
+  const quoted = psArgs.map((a) => `'${String(a).replace(/'/g, "''")}'`).join(',');
+  const outer = `try { $p = Start-Process -FilePath powershell.exe -Verb RunAs -Wait -PassThru -ArgumentList @(${quoted}); exit $p.ExitCode } catch { Write-Output "ELEVATE-FAILED: $($_.Exception.Message)"; exit 1 }`;
+  return run('powershell.exe', ['-NoProfile', '-Command', outer]);
+}
+
+/**
+ * Runs an elevated .ps1 that takes a trailing -ResultFile path and writes 'OK' or 'ERROR: ...' there (the
+ * elevated child's own stdout/stderr never reaches this process -- see install.ps1's header comment). Resolves
+ * { ok, message }.
+ */
+async function runElevatedScript(scriptPath, args) {
+  const resultFile = path.join(os.tmpdir(), `ispyx-unlock-result-${crypto.randomBytes(8).toString('hex')}.tmp`);
+  try {
+    const { out } = await runElevated(scriptPath, [...args, resultFile]);
+    let result = '';
+    try { result = fs.readFileSync(resultFile, 'utf8'); } catch { /* elevation itself never ran the script */ }
+    if (result) {
+      return result.startsWith('ERROR:') ? { ok: false, message: result.slice(6).trim() } : { ok: true, message: result };
+    }
+    const outer = out.trim().split('\n').pop() || '';
+    return { ok: false, message: outer.replace(/^ELEVATE-FAILED:\s*/, '') || 'Setup was cancelled or failed.' };
+  } finally {
+    try { fs.unlinkSync(resultFile); } catch { /* did not get created, or the script already removed it */ }
+  }
+}
+
+/**
+ * `fs.existsSync` returns false on ANY stat error, not just "missing" -- and the secret file's ACL (by design,
+ * see install.ps1) denies read to this account's normal, non-elevated token, which is exactly the context the
+ * resident always runs in. So existsSync would report "not enabled" right after a successful install. statSync
+ * + checking the error code distinguishes "really missing" (ENOENT) from "there, just can't read it" (anything
+ * else) -- confirmed hitting this directly: a real install left this returning false until fixed.
+ */
+export function isEnabled() {
+  try {
+    fs.statSync(SECRET_PATH);
+    return true;
+  } catch (e) {
+    return e.code !== 'ENOENT';
+  }
+}
+
+/**
+ * Local-account check (see docs/unlock-windows.md "Known gaps" for why PIN/Microsoft-account and passwordless
+ * accounts cannot work here). Resolves { ok: true } or { ok: false, reason }.
+ *
+ * Deliberately does NOT try to detect "no password set" up front: the one signal Windows exposes for that,
+ * UserFlags' UF_PASSWD_NOTREQD bit ("net user"'s "Password required"), means the password-policy check is
+ * waived for this account, not that the password is blank -- confirmed a false positive on a real account with
+ * a working password. A wrong/blank stored secret is already caught safely at unlock time (one attempt, no
+ * retry -- see credential.rs), so there is no need to predict it here.
+ */
+export async function checkAccount() {
+  const ps = `
+    $src = $null
+    try { $src = (Get-LocalUser -Name $env:USERNAME -ErrorAction Stop).PrincipalSource.ToString() } catch {}
+    [PSCustomObject]@{ principalSource = $src } | ConvertTo-Json -Compress
+  `;
+  const { code, out } = await run('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', ps]);
+  if (code !== 0) return { ok: false, reason: 'Could not check the account type.' };
+  let info;
+  try { info = JSON.parse(out.trim().split('\n').pop()); } catch { return { ok: false, reason: 'Could not check the account type.' }; }
+  if (info.principalSource && info.principalSource !== 'Local') {
+    return { ok: false, reason: 'This looks like a Microsoft-account or PIN-only sign-in. Unattended unlock only supports a local account with a password.' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Panel action: writes the DPAPI secret and registers the Credential Provider (one UAC prompt). Only the
+ * password is asked for in the panel -- the account is always the one the resident itself runs as, since that
+ * is the only session this mechanism can ever unlock.
+ */
+export async function enable({ password }) {
+  if (!password) throw new Error('Enter the Windows account password.');
+  const check = await checkAccount();
+  if (!check.ok) throw new Error(check.reason);
+  const username = os.userInfo().username;
+  const domain = process.env.USERDOMAIN || '';
+  const tmp = path.join(os.tmpdir(), `ispyx-unlock-${crypto.randomBytes(8).toString('hex')}.tmp`);
+  fs.writeFileSync(tmp, `${domain}\n${username}\n${password}\n`);
+  try {
+    const r = await runElevatedScript(path.join(PROVIDER_DIR, 'install.ps1'), [tmp, DLL_PATH]);
+    if (!r.ok) throw new Error(r.message);
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* install.ps1 deletes it too either way */ }
+  }
+}
+
+/** Panel action: unregisters the Credential Provider and deletes the stored secret (one UAC prompt). */
+export async function disable() {
+  const r = await runElevatedScript(path.join(PROVIDER_DIR, 'uninstall.ps1'), []);
+  if (!r.ok) throw new Error(r.message);
+}
+
+/**
+ * Called by the `unlock` tool while the screen is locked: touches the signal file the Credential Provider
+ * watches (a named Win32 event was tried instead, to drop the watcher's poll loop entirely -- reverted, see
+ * docs/unlock-windows.md: a named kernel object only exists while some process holds a handle open, and
+ * nothing here runs continuously between an enable() and a much later signal() to be that holder). Never
+ * needs elevation -- the install step already granted this account write access to this one file.
+ */
+export function signal() {
+  fs.writeFileSync(SIGNAL_PATH, '1');
+}