local-commander-agent 0.3.48 → 0.3.49

package/bin/command-path.mjs

@@ -1,223 +1,223 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-
-const SHIM_MARKER = "@rem Local Commander managed command\r\n";
-const WRAPPER_MARKER = "# Local Commander managed command\r\n";
-const MONITOR_WRAPPER = "localcommander-monitor.ps1";
-const SHORTCUT_NAME = "Local Commander Monitor";
-const CLI_FILES = ["package.json", "bin/localcommander.mjs", "bin/monitor.mjs", "bin/monitor-agents.mjs", "bin/monitor-context.mjs", "bin/monitor-mcp.mjs", "bin/monitor-savings.mjs", "bin/command-path.mjs", "bin/network-package.mjs"];
-
-function validVersion(version) {
-  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) throw Error("PACKAGE_VERSION_INVALID");
-  return version;
-}
-
-export function commandShim(version) {
-  return SHIM_MARKER + '@echo off\r\nsetlocal DisableDelayedExpansion\r\nnode "%~dp0..\\Versions\\' + validVersion(version) +
-    '\\bin\\localcommander.mjs" %*\r\nexit /b %errorlevel%\r\n';
-}
-
-// Visible launcher for the Start menu shortcut. PowerShell hosts node directly so Ctrl+C
-// ends the monitor without cmd's "Terminate batch job" prompt; the window stays open with
-// local guidance only when the monitor could not start or ended with an error.
-export function monitorWrapper(version) {
-  return WRAPPER_MARKER + [
-    "# 'Continue' keeps monitor stderr lines (for example unavailable snapshots) from ending the view when output is redirected.",
-    "$ErrorActionPreference = 'Continue'",
-    "try { $Host.UI.RawUI.WindowTitle = '" + SHORTCUT_NAME + "' } catch {}",
-    "$cli = [IO.Path]::Combine([IO.Path]::GetDirectoryName($PSScriptRoot), 'Versions', '" + validVersion(version) + "', 'bin', 'localcommander.mjs')",
-    "$code = 1",
-    "try {",
-    "  if (-not (Test-Path -LiteralPath $cli -PathType Leaf)) { throw 'LOCAL_COMMANDER_CLI_MISSING' }",
-    "  & node $cli monitor --watch",
-    "  $code = $LASTEXITCODE",
-    "} catch { Write-Host ('' + $_) }",
-    "if ($code -ne 0) {",
-    "  Write-Host ''",
-    "  Write-Host 'Local Commander Monitor could not start or ended with an error.'",
-    "  Write-Host 'Node.js 20+ must be installed and Local Commander must be installed for this Windows user.'",
-    "  Write-Host 'Check the installation in a terminal:  npx local-commander-agent@latest status'",
-    "  Write-Host 'Reinstall or update:                   npx local-commander-agent@latest update'",
-    "  Write-Host 'Help: https://localcmd.app/support'",
-    "  Write-Host ''",
-    "  Read-Host 'Press Enter to close this window' | Out-Null",
-    "}",
-    "exit $code",
-    ""
-  ].join("\r\n");
-}
-
-async function plainDirectory(directory) {
-  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
-  const stat = await fs.lstat(directory);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) throw Error("INSTALL_DIRECTORY_INVALID");
-}
-async function regularOrMissing(file) {
-  const stat = await fs.lstat(file).catch(error => { if (error.code !== "ENOENT") throw error; });
-  if (stat && (!stat.isFile() || stat.isSymbolicLink())) throw Error("INSTALL_STATE_INVALID");
-}
-
-export async function installCommandFiles(packageRoot, installRoot, version) {
-  const shim = commandShim(version);
-  const runtime = path.join(installRoot, "Versions", version);
-  const bin = path.join(installRoot, "bin");
-  for (const directory of [installRoot, path.join(installRoot, "Versions"), runtime, path.join(runtime, "bin"), bin]) await plainDirectory(directory);
-  for (const file of CLI_FILES) {
-    const source = path.join(packageRoot, file), target = path.join(runtime, file);
-    await regularOrMissing(source);
-    await regularOrMissing(target);
-    if (path.resolve(source).toLowerCase() !== path.resolve(target).toLowerCase()) await fs.copyFile(source, target);
-  }
-  await writeManaged(path.join(bin, "localcommander.cmd"), SHIM_MARKER, shim);
-  await writeManaged(path.join(bin, MONITOR_WRAPPER), WRAPPER_MARKER, monitorWrapper(version));
-  return bin;
-}
-
-// Only files that still start with their Local Commander marker are replaced; a user-owned
-// file with the same name is left untouched and reported.
-async function writeManaged(target, marker, content) {
-  await regularOrMissing(target);
-  const previous = await fs.readFile(target, "utf8").catch(error => { if (error.code !== "ENOENT") throw error; });
-  if (previous !== undefined && !previous.startsWith(marker)) throw Error("COMMAND_SHIM_CONFLICT");
-  await fs.writeFile(target, content, { mode: 0o600 });
-}
-
-export async function removeCommandFile(installRoot) {
-  for (const directory of [installRoot, path.join(installRoot, "bin")]) {
-    const stat = await fs.lstat(directory).catch(error => { if (error.code !== "ENOENT") throw error; });
-    if (!stat) return;
-    if (!stat.isDirectory() || stat.isSymbolicLink()) throw Error("INSTALL_DIRECTORY_INVALID");
-  }
-  for (const [name, marker] of [["localcommander.cmd", SHIM_MARKER], [MONITOR_WRAPPER, WRAPPER_MARKER]]) {
-    const file = path.join(installRoot, "bin", name);
-    await regularOrMissing(file);
-    const content = await fs.readFile(file, "utf8").catch(error => { if (error.code !== "ENOENT") throw error; });
-    if (content?.startsWith(marker)) await fs.unlink(file);
-  }
-}
-
-// The per-user Start menu entry targets the stable managed wrapper, so it survives version
-// updates and npm cache removal. Ownership is recorded in the shortcut description; an
-// unrelated shortcut with the same display name is never overwritten or removed.
-export const START_MENU_SCRIPT = String.raw`
-$ErrorActionPreference = 'Stop'
-$marker = 'Local Commander managed shortcut'
-$folderName = if ($env:LC_SHORTCUT_FOLDER) { $env:LC_SHORTCUT_FOLDER } else { 'Programs' }
-$programs = [Environment]::GetFolderPath($folderName)
-if (-not $programs) { throw 'START_MENU_UNAVAILABLE' }
-$link = Join-Path $programs ($env:LC_SHORTCUT_NAME + '.lnk')
-$shell = New-Object -ComObject WScript.Shell
-$exists = Test-Path -LiteralPath $link
-if ($exists) {
-  $item = Get-Item -LiteralPath $link -Force
-  if ($item.PSIsContainer -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'SHORTCUT_CONFLICT' }
-  if ($shell.CreateShortcut($link).Description -ne $marker) { throw 'SHORTCUT_CONFLICT' }
-}
-if ($env:LC_SHORTCUT_REMOVE -eq '1') {
-  if ($exists) { Remove-Item -LiteralPath $link -Force }
-} else {
-  $shortcut = $shell.CreateShortcut($link)
-  $shortcut.TargetPath = $env:LC_SHORTCUT_TARGET
-  $shortcut.Arguments = $env:LC_SHORTCUT_ARGUMENTS
-  $shortcut.WorkingDirectory = $env:LC_SHORTCUT_DIRECTORY
-  $shortcut.Description = $marker
-  $shortcut.WindowStyle = 1
-  $shortcut.Save()
-}
-Write-Output 'SHORTCUT_READY'
-`;
-
-function powershellPath() {
-  return path.join(process.env.SystemRoot || "C:\\Windows", "System32/WindowsPowerShell/v1.0/powershell.exe");
-}
-
-function runStartMenuScript(env) {
-  const result = spawnSync(powershellPath(),
-    ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(START_MENU_SCRIPT, "utf16le").toString("base64")],
-    { windowsHide: true, encoding: "utf8", timeout: 15_000, env: { ...process.env, LC_SHORTCUT_NAME: SHORTCUT_NAME, ...env } });
-  if (result.error) throw Error("SHORTCUT_UPDATE_FAILED");
-  if (result.status === 0 && result.stdout.trim() === "SHORTCUT_READY") return;
-  throw Error(/SHORTCUT_CONFLICT/.test(result.stderr) ? "SHORTCUT_CONFLICT" : "SHORTCUT_UPDATE_FAILED");
-}
-
-export function installStartMenuShortcut(bin, workingDirectory = os.homedir()) {
-  const wrapper = path.join(bin, MONITOR_WRAPPER);
-  if (!path.isAbsolute(bin) || /["\r\n\0]/.test(bin) || !path.isAbsolute(workingDirectory) || /["\r\n\0]/.test(workingDirectory)) throw Error("COMMAND_PATH_INVALID");
-  runStartMenuScript({
-    LC_SHORTCUT_REMOVE: "0",
-    LC_SHORTCUT_TARGET: powershellPath(),
-    LC_SHORTCUT_ARGUMENTS: '-NoLogo -NoProfile -ExecutionPolicy Bypass -File "' + wrapper + '"',
-    LC_SHORTCUT_DIRECTORY: workingDirectory
-  });
-  return SHORTCUT_NAME;
-}
-
-export function removeStartMenuShortcut() {
-  runStartMenuScript({ LC_SHORTCUT_REMOVE: "1" });
-}
-
-// A named shortcut (Start menu + Desktop) that launches a browser already routed through the proxy.
-export function installBrowserShortcut(name, target, args, workingDirectory = os.homedir()) {
-  if (!name || /["\r\n\0\\/]/.test(name) || !path.isAbsolute(target) || /["\r\n\0]/.test(target) || /[\r\n\0]/.test(args)) throw Error("SHORTCUT_PARAM_INVALID");
-  for (const folder of ["Programs", "Desktop"]) runStartMenuScript({
-    LC_SHORTCUT_FOLDER: folder, LC_SHORTCUT_NAME: name, LC_SHORTCUT_REMOVE: "0",
-    LC_SHORTCUT_TARGET: target, LC_SHORTCUT_ARGUMENTS: args, LC_SHORTCUT_DIRECTORY: workingDirectory
-  });
-  return name;
-}
-
-export function removeBrowserShortcut(name) {
-  for (const folder of ["Programs", "Desktop"]) { try { runStartMenuScript({ LC_SHORTCUT_FOLDER: folder, LC_SHORTCUT_NAME: name, LC_SHORTCUT_REMOVE: "1" }); } catch { /* best effort */ } }
-}
-
-// Read the registry's raw value so %VARIABLE% entries and its value type survive.
-export const USER_PATH_SCRIPT = String.raw`
-$ErrorActionPreference = 'Stop'
-$target = $env:LC_COMMAND_BIN
-$remove = $env:LC_COMMAND_PATH_REMOVE -eq '1'
-$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
-try {
-  $raw = $key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
-  if ($raw -isnot [string]) { throw 'USER_PATH_INVALID' }
-  $kind = [Microsoft.Win32.RegistryValueKind]::ExpandString
-  if ($key.GetValueNames() -contains 'Path') { $kind = $key.GetValueKind('Path') }
-  if ($kind -ne [Microsoft.Win32.RegistryValueKind]::String -and $kind -ne [Microsoft.Win32.RegistryValueKind]::ExpandString) { throw 'USER_PATH_INVALID' }
-  $entries = $raw.Split(';')
-  $kept = @($entries | Where-Object {
-    $expanded = [Environment]::ExpandEnvironmentVariables($_.Trim().Trim('"')).Replace('/', '\').TrimEnd('\')
-    -not [string]::Equals($expanded, $target.TrimEnd('\'), [StringComparison]::OrdinalIgnoreCase)
-  })
-  $next = $raw
-  if ($remove) { $next = [string]::Join(';', $kept) }
-  elseif ($kept.Count -eq $entries.Count) {
-    $separator = if ($raw.Length -gt 0 -and -not $raw.EndsWith(';')) { ';' } else { '' }
-    $next = $raw + $separator + $target
-  }
-  if ($next.Length -gt 32766) { throw 'USER_PATH_TOO_LONG' }
-  if ($next -cne $raw) { $key.SetValue('Path', $next, $kind) }
-} finally { $key.Dispose() }
-Add-Type -TypeDefinition @'
-using System;
-using System.Runtime.InteropServices;
-public static class LocalCommanderEnvironment {
-  [DllImport("user32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
-  public static extern IntPtr SendMessageTimeout(IntPtr window, uint message, IntPtr word, string value, uint flags, uint timeout, out UIntPtr result);
-}
-'@
-$result = [UIntPtr]::Zero
-[void][LocalCommanderEnvironment]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [IntPtr]::Zero, 'Environment', 2, 1000, [ref]$result)
-Write-Output 'USER_PATH_READY'
-`;
-
-export function updateUserPath(bin, remove = false) {
-  if (!path.isAbsolute(bin) || /[;"\r\n\0]/.test(bin)) throw Error("COMMAND_PATH_INVALID");
-  // The settings broadcast waits up to 1 s per top-level window; a busy desktop took 19 s (2026-10-17).
-  const result = spawnSync(powershellPath(),
-    ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(USER_PATH_SCRIPT, "utf16le").toString("base64")], {
-      windowsHide: true, encoding: "utf8", timeout: 60_000,
-      env: { ...process.env, LC_COMMAND_BIN: bin, LC_COMMAND_PATH_REMOVE: remove ? "1" : "0" }
-    });
-  if (result.error || result.status !== 0 || result.stdout.trim() !== "USER_PATH_READY") throw Error("USER_PATH_UPDATE_FAILED");
-}
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const SHIM_MARKER = "@rem Local Commander managed command\r\n";
+const WRAPPER_MARKER = "# Local Commander managed command\r\n";
+const MONITOR_WRAPPER = "localcommander-monitor.ps1";
+const SHORTCUT_NAME = "Local Commander Monitor";
+const CLI_FILES = ["package.json", "bin/localcommander.mjs", "bin/monitor.mjs", "bin/monitor-agents.mjs", "bin/monitor-context.mjs", "bin/monitor-mcp.mjs", "bin/monitor-savings.mjs", "bin/command-path.mjs", "bin/network-package.mjs"];
+
+function validVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) throw Error("PACKAGE_VERSION_INVALID");
+  return version;
+}
+
+export function commandShim(version) {
+  return SHIM_MARKER + '@echo off\r\nsetlocal DisableDelayedExpansion\r\nnode "%~dp0..\\Versions\\' + validVersion(version) +
+    '\\bin\\localcommander.mjs" %*\r\nexit /b %errorlevel%\r\n';
+}
+
+// Visible launcher for the Start menu shortcut. PowerShell hosts node directly so Ctrl+C
+// ends the monitor without cmd's "Terminate batch job" prompt; the window stays open with
+// local guidance only when the monitor could not start or ended with an error.
+export function monitorWrapper(version) {
+  return WRAPPER_MARKER + [
+    "# 'Continue' keeps monitor stderr lines (for example unavailable snapshots) from ending the view when output is redirected.",
+    "$ErrorActionPreference = 'Continue'",
+    "try { $Host.UI.RawUI.WindowTitle = '" + SHORTCUT_NAME + "' } catch {}",
+    "$cli = [IO.Path]::Combine([IO.Path]::GetDirectoryName($PSScriptRoot), 'Versions', '" + validVersion(version) + "', 'bin', 'localcommander.mjs')",
+    "$code = 1",
+    "try {",
+    "  if (-not (Test-Path -LiteralPath $cli -PathType Leaf)) { throw 'LOCAL_COMMANDER_CLI_MISSING' }",
+    "  & node $cli monitor --watch",
+    "  $code = $LASTEXITCODE",
+    "} catch { Write-Host ('' + $_) }",
+    "if ($code -ne 0) {",
+    "  Write-Host ''",
+    "  Write-Host 'Local Commander Monitor could not start or ended with an error.'",
+    "  Write-Host 'Node.js 20+ must be installed and Local Commander must be installed for this Windows user.'",
+    "  Write-Host 'Check the installation in a terminal:  npx local-commander-agent@latest status'",
+    "  Write-Host 'Reinstall or update:                   npx local-commander-agent@latest update'",
+    "  Write-Host 'Help: https://localcmd.app/support'",
+    "  Write-Host ''",
+    "  Read-Host 'Press Enter to close this window' | Out-Null",
+    "}",
+    "exit $code",
+    ""
+  ].join("\r\n");
+}
+
+async function plainDirectory(directory) {
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const stat = await fs.lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw Error("INSTALL_DIRECTORY_INVALID");
+}
+async function regularOrMissing(file) {
+  const stat = await fs.lstat(file).catch(error => { if (error.code !== "ENOENT") throw error; });
+  if (stat && (!stat.isFile() || stat.isSymbolicLink())) throw Error("INSTALL_STATE_INVALID");
+}
+
+export async function installCommandFiles(packageRoot, installRoot, version) {
+  const shim = commandShim(version);
+  const runtime = path.join(installRoot, "Versions", version);
+  const bin = path.join(installRoot, "bin");
+  for (const directory of [installRoot, path.join(installRoot, "Versions"), runtime, path.join(runtime, "bin"), bin]) await plainDirectory(directory);
+  for (const file of CLI_FILES) {
+    const source = path.join(packageRoot, file), target = path.join(runtime, file);
+    await regularOrMissing(source);
+    await regularOrMissing(target);
+    if (path.resolve(source).toLowerCase() !== path.resolve(target).toLowerCase()) await fs.copyFile(source, target);
+  }
+  await writeManaged(path.join(bin, "localcommander.cmd"), SHIM_MARKER, shim);
+  await writeManaged(path.join(bin, MONITOR_WRAPPER), WRAPPER_MARKER, monitorWrapper(version));
+  return bin;
+}
+
+// Only files that still start with their Local Commander marker are replaced; a user-owned
+// file with the same name is left untouched and reported.
+async function writeManaged(target, marker, content) {
+  await regularOrMissing(target);
+  const previous = await fs.readFile(target, "utf8").catch(error => { if (error.code !== "ENOENT") throw error; });
+  if (previous !== undefined && !previous.startsWith(marker)) throw Error("COMMAND_SHIM_CONFLICT");
+  await fs.writeFile(target, content, { mode: 0o600 });
+}
+
+export async function removeCommandFile(installRoot) {
+  for (const directory of [installRoot, path.join(installRoot, "bin")]) {
+    const stat = await fs.lstat(directory).catch(error => { if (error.code !== "ENOENT") throw error; });
+    if (!stat) return;
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw Error("INSTALL_DIRECTORY_INVALID");
+  }
+  for (const [name, marker] of [["localcommander.cmd", SHIM_MARKER], [MONITOR_WRAPPER, WRAPPER_MARKER]]) {
+    const file = path.join(installRoot, "bin", name);
+    await regularOrMissing(file);
+    const content = await fs.readFile(file, "utf8").catch(error => { if (error.code !== "ENOENT") throw error; });
+    if (content?.startsWith(marker)) await fs.unlink(file);
+  }
+}
+
+// The per-user Start menu entry targets the stable managed wrapper, so it survives version
+// updates and npm cache removal. Ownership is recorded in the shortcut description; an
+// unrelated shortcut with the same display name is never overwritten or removed.
+export const START_MENU_SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+$marker = 'Local Commander managed shortcut'
+$folderName = if ($env:LC_SHORTCUT_FOLDER) { $env:LC_SHORTCUT_FOLDER } else { 'Programs' }
+$programs = [Environment]::GetFolderPath($folderName)
+if (-not $programs) { throw 'START_MENU_UNAVAILABLE' }
+$link = Join-Path $programs ($env:LC_SHORTCUT_NAME + '.lnk')
+$shell = New-Object -ComObject WScript.Shell
+$exists = Test-Path -LiteralPath $link
+if ($exists) {
+  $item = Get-Item -LiteralPath $link -Force
+  if ($item.PSIsContainer -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'SHORTCUT_CONFLICT' }
+  if ($shell.CreateShortcut($link).Description -ne $marker) { throw 'SHORTCUT_CONFLICT' }
+}
+if ($env:LC_SHORTCUT_REMOVE -eq '1') {
+  if ($exists) { Remove-Item -LiteralPath $link -Force }
+} else {
+  $shortcut = $shell.CreateShortcut($link)
+  $shortcut.TargetPath = $env:LC_SHORTCUT_TARGET
+  $shortcut.Arguments = $env:LC_SHORTCUT_ARGUMENTS
+  $shortcut.WorkingDirectory = $env:LC_SHORTCUT_DIRECTORY
+  $shortcut.Description = $marker
+  $shortcut.WindowStyle = 1
+  $shortcut.Save()
+}
+Write-Output 'SHORTCUT_READY'
+`;
+
+function powershellPath() {
+  return path.join(process.env.SystemRoot || "C:\\Windows", "System32/WindowsPowerShell/v1.0/powershell.exe");
+}
+
+function runStartMenuScript(env) {
+  const result = spawnSync(powershellPath(),
+    ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(START_MENU_SCRIPT, "utf16le").toString("base64")],
+    { windowsHide: true, encoding: "utf8", timeout: 15_000, env: { ...process.env, LC_SHORTCUT_NAME: SHORTCUT_NAME, ...env } });
+  if (result.error) throw Error("SHORTCUT_UPDATE_FAILED");
+  if (result.status === 0 && result.stdout.trim() === "SHORTCUT_READY") return;
+  throw Error(/SHORTCUT_CONFLICT/.test(result.stderr) ? "SHORTCUT_CONFLICT" : "SHORTCUT_UPDATE_FAILED");
+}
+
+export function installStartMenuShortcut(bin, workingDirectory = os.homedir()) {
+  const wrapper = path.join(bin, MONITOR_WRAPPER);
+  if (!path.isAbsolute(bin) || /["\r\n\0]/.test(bin) || !path.isAbsolute(workingDirectory) || /["\r\n\0]/.test(workingDirectory)) throw Error("COMMAND_PATH_INVALID");
+  runStartMenuScript({
+    LC_SHORTCUT_REMOVE: "0",
+    LC_SHORTCUT_TARGET: powershellPath(),
+    LC_SHORTCUT_ARGUMENTS: '-NoLogo -NoProfile -ExecutionPolicy Bypass -File "' + wrapper + '"',
+    LC_SHORTCUT_DIRECTORY: workingDirectory
+  });
+  return SHORTCUT_NAME;
+}
+
+export function removeStartMenuShortcut() {
+  runStartMenuScript({ LC_SHORTCUT_REMOVE: "1" });
+}
+
+// A named shortcut (Start menu + Desktop) that launches a browser already routed through the proxy.
+export function installBrowserShortcut(name, target, args, workingDirectory = os.homedir()) {
+  if (!name || /["\r\n\0\\/]/.test(name) || !path.isAbsolute(target) || /["\r\n\0]/.test(target) || /[\r\n\0]/.test(args)) throw Error("SHORTCUT_PARAM_INVALID");
+  for (const folder of ["Programs", "Desktop"]) runStartMenuScript({
+    LC_SHORTCUT_FOLDER: folder, LC_SHORTCUT_NAME: name, LC_SHORTCUT_REMOVE: "0",
+    LC_SHORTCUT_TARGET: target, LC_SHORTCUT_ARGUMENTS: args, LC_SHORTCUT_DIRECTORY: workingDirectory
+  });
+  return name;
+}
+
+export function removeBrowserShortcut(name) {
+  for (const folder of ["Programs", "Desktop"]) { try { runStartMenuScript({ LC_SHORTCUT_FOLDER: folder, LC_SHORTCUT_NAME: name, LC_SHORTCUT_REMOVE: "1" }); } catch { /* best effort */ } }
+}
+
+// Read the registry's raw value so %VARIABLE% entries and its value type survive.
+export const USER_PATH_SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+$target = $env:LC_COMMAND_BIN
+$remove = $env:LC_COMMAND_PATH_REMOVE -eq '1'
+$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
+try {
+  $raw = $key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+  if ($raw -isnot [string]) { throw 'USER_PATH_INVALID' }
+  $kind = [Microsoft.Win32.RegistryValueKind]::ExpandString
+  if ($key.GetValueNames() -contains 'Path') { $kind = $key.GetValueKind('Path') }
+  if ($kind -ne [Microsoft.Win32.RegistryValueKind]::String -and $kind -ne [Microsoft.Win32.RegistryValueKind]::ExpandString) { throw 'USER_PATH_INVALID' }
+  $entries = $raw.Split(';')
+  $kept = @($entries | Where-Object {
+    $expanded = [Environment]::ExpandEnvironmentVariables($_.Trim().Trim('"')).Replace('/', '\').TrimEnd('\')
+    -not [string]::Equals($expanded, $target.TrimEnd('\'), [StringComparison]::OrdinalIgnoreCase)
+  })
+  $next = $raw
+  if ($remove) { $next = [string]::Join(';', $kept) }
+  elseif ($kept.Count -eq $entries.Count) {
+    $separator = if ($raw.Length -gt 0 -and -not $raw.EndsWith(';')) { ';' } else { '' }
+    $next = $raw + $separator + $target
+  }
+  if ($next.Length -gt 32766) { throw 'USER_PATH_TOO_LONG' }
+  if ($next -cne $raw) { $key.SetValue('Path', $next, $kind) }
+} finally { $key.Dispose() }
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class LocalCommanderEnvironment {
+  [DllImport("user32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  public static extern IntPtr SendMessageTimeout(IntPtr window, uint message, IntPtr word, string value, uint flags, uint timeout, out UIntPtr result);
+}
+'@
+$result = [UIntPtr]::Zero
+[void][LocalCommanderEnvironment]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [IntPtr]::Zero, 'Environment', 2, 1000, [ref]$result)
+Write-Output 'USER_PATH_READY'
+`;
+
+export function updateUserPath(bin, remove = false) {
+  if (!path.isAbsolute(bin) || /[;"\r\n\0]/.test(bin)) throw Error("COMMAND_PATH_INVALID");
+  // The settings broadcast waits up to 1 s per top-level window; a busy desktop took 19 s (2026-10-17).
+  const result = spawnSync(powershellPath(),
+    ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(USER_PATH_SCRIPT, "utf16le").toString("base64")], {
+      windowsHide: true, encoding: "utf8", timeout: 60_000,
+      env: { ...process.env, LC_COMMAND_BIN: bin, LC_COMMAND_PATH_REMOVE: remove ? "1" : "0" }
+    });
+  if (result.error || result.status !== 0 || result.stdout.trim() !== "USER_PATH_READY") throw Error("USER_PATH_UPDATE_FAILED");
+}