development.md

@@ -72,7 +72,7 @@ Renderer never touches Node/Electron directly — everything goes through the `w
 - Registries (apps.json, wines.json, prefixes.json) are rewritten whole via writeJson(); playtime lives in its own tiny file so the registry is not rewritten while a game runs.
 - Deleting user data needs a confirm modal; best-effort cleanup is try/catch-and-ignore with a comment saying why it is safe to ignore.
 - Windows apps run through runGame()/buildEnv() — never spawn wine directly elsewhere (prefix handling, Proton env and playtime live there).
-- Native Linux apps run through linuxrunner.runLinuxGame()/buildLinuxEnv() the same way: HOME and the XDG folders are redirected into `{prefix}/linux_pfx/`, and bwrap (when the probe says it works) forces the same layout with mounts. Never spawn a native app elsewhere. `game.kind` is absent on old entries — that means Windows; `game.isolation` is one of four levels, resolved by linuxrunner.resolveLevel: `none` (plain run), `relaxed` (bwrap + the whole host filesystem mounted writable at sandbox.FS_ROOT) and `isolated` (bwrap with the stock read-only profile), with `auto` (default) meaning relaxed where bwrap works and none where it does not. Only `auto` may weaken itself — an explicit relaxed/isolated answers `sandbox-required` instead ("no silent downgrade"). library.js keeps exactly these four values, both when reading the registry and when a patch is saved (anything else falls back to `auto`), and the level always lands in the log and the UI. resolveLevel awaits the probe when nothing has measured yet: a shortcut boots HEADLESS, so no renderer ran `sandbox:status` — without that wait `auto` would read an empty cache and quietly pick `none` (and an explicit level would refuse a machine that can sandbox perfectly well).
+- Native Linux apps run through linuxrunner.runLinuxGame()/buildLinuxEnv() the same way: HOME and the XDG folders are redirected into `{prefix}/linux_pfx/`, and bwrap (when the probe says it works) forces the same layout with mounts. Never spawn a native app elsewhere. `game.kind` is absent on old entries — that means Windows; `game.isolation` is one of four levels, resolved by linuxrunner.resolveLevel: `none` (plain run), `relaxed` (bwrap + the whole host filesystem mounted writable at sandbox.FS_ROOT) and `isolated` (bwrap with the stock read-only profile), with `auto` (default) meaning relaxed where bwrap works and none where it does not. Only `auto` may weaken itself — an explicit relaxed/isolated answers `sandbox-required` instead ("no silent downgrade"), and library.js maps the values launcher 0.5.x wrote (`off` → none, `require` → isolated) both when reading the registry and when a patch is saved. The level always lands in the log and the UI. resolveLevel awaits the probe when nothing has measured yet: a shortcut boots HEADLESS, so no renderer ran `sandbox:status` — without that wait `auto` would read an empty cache and quietly pick `none` (and an explicit level would refuse a machine that can sandbox perfectly well).
 - Under bwrap ONLY two things stay writable: the redirected home and the app's own folder (`writableAppDir`: inside files/apps, or the folder the app was imported from — never `/usr`, `/etc`, `/bin`… and never files/wines). Portable apps write logs and data next to themselves and a read-only app folder makes them refuse to start (Prism Launcher: "couldn't create a log file - Read-only file system"). Everything else is `EROFS` by design — at the isolated level. Relaxed is the deliberate exception and says so in the UI: `FS_ROOT` is the same filesystem, mounted writable, so "everything else" is only unreachable through the real paths.
 - Two pipes feed one log in spawnTracked: neither may end the stream (pipe(ws, { end: false }), closed when both sources drained, at the latest LOG_DRAIN_MS after the exit) and the write stream carries an error listener. Ending it at `exit` while a pipe still had data killed the whole launcher with ERR_STREAM_WRITE_AFTER_END.
 - A prefix or wine build a running app uses cannot be renamed/deleted (wine holds files open there): the guards sit next to the handlers in src/ipc/, use the games service's running list plus library.js helpers (prefixNameForGame/gamesUsingPrefix/is*InUse) and answer `{ ok:false, error:'inUse'|'hasApps', apps:[names] }` for the toast.
@@ -83,7 +83,7 @@ Renderer never touches Node/Electron directly — everything goes through the `w
 ### Native Linux apps
 
 - Entry point detection (linuxapp.js): ELF, `.AppImage`, or a `.desktop` whose `Exec=` points at one; `lib/`, `share/` … are skipped. The icon comes from the `.desktop` `Icon=`, an image next to the program, or the system theme — `extractIconFromExe` is PE-only.
-- The redirected home starts as a COPY of the desktop preferences (kdeglobals, kdedefaults/kdeglobals, gtk-3.0|gtk-4.0/settings.ini, qt5ct/qt6ct, Trolltech.conf, user-dirs.dirs). Without the seed Qt falls back to its built-in light palette (measured: `#eff0f1` against the host's `#202326`). The copy keeps following the host while the app has not touched it: the hashes of what PLWL wrote live in `{prefix}/linux_pfx/.seeded.json`, OUTSIDE the app's home, and a copy with no marker entry (what an older launcher left) counts as ours and is refreshed. The PulseAudio cookie is seeded once, because with a redirected home Pulse looks in `$HOME/.config/pulse/cookie` and the app otherwise comes up silent; `~/.Xauthority` is refreshed instead, since nothing exports XAUTHORITY to a sandboxed app.
+- The redirected home starts as a COPY of the desktop preferences (kdeglobals, kdedefaults/kdeglobals, gtk-3.0|gtk-4.0/settings.ini, qt5ct/qt6ct, Trolltech.conf, user-dirs.dirs). Without the seed Qt falls back to its built-in light palette (measured: `#eff0f1` against the host's `#202326`). The copy keeps following the host while the app has not touched it: the hashes of what PLWL wrote live in `{prefix}/linux_pfx/.seeded.json`, OUTSIDE the app's home, and a prefix from an older launcher is adopted on evidence (byte-identical with the host, or the copy is older than the host's file). The PulseAudio cookie is seeded once, because with a redirected home Pulse looks in `$HOME/.config/pulse/cookie` and the app otherwise comes up silent; `~/.Xauthority` is refreshed instead, since nothing exports XAUTHORITY to a sandboxed app.
 - Host fonts/icons/themes/colour schemes are not copied but `--ro-bind` under `/tmp/.plwl-host/…` and prepended to XDG_DATA_DIRS: live, and unable to write back into the user's `~`. Symlinks were measured and rejected — the prefix is mounted ON `~`, so a link to `~/.config/kdeglobals` points at itself (`Too many levels of symbolic links`); without bwrap the same link writes through into the real home.
 - `forceX11` (per app) sets XDG_SESSION_TYPE=x11 + QT_QPA_PLATFORM=xcb + GDK_BACKEND=x11 so the app and everything it launches falls back to XWayland, where window icons still exist at all (Wayland forbids them; a compiled GLFW probe showed XDG_SESSION_TYPE picks X11 vs Wayland, `GLFW_PLATFORM` does not exist). `game.env` still wins.
 - SESSION_MANAGER is dropped in the sandbox: the session socket sits in the private `/tmp`, so the pointer led nowhere (Qt: "Could not open network socket").
@@ -91,7 +91,6 @@ Renderer never touches Node/Electron directly — everything goes through the `w
 - **Reset Linux config** on every prefix row removes exactly what PLWL seeded (DESKTOP_SEEDS, the pulse cookie, `home/.Xauthority`, `.seeded.json`) plus the folders that existed only for the seed, so the next start seeds clean. syncDesktopConfig can only follow a copy it can still prove is its own; the reset does not argue. App data (`data/`, `cache/`, `state/`, `config/<app>/`, the rest of `home/`) is never touched, and a running app from that prefix blocks it (the usual `inUse` guard).
 - With HOME bound straight to `{prefix}/linux_pfx/home`, the user's real `~` is invisible to the app — one reason absolute paths an app wrote into its config before the import (Prism's instance `JavaPath`) do not resolve. `relaxed` does not change that shadowing, but it does make the real filesystem reachable through `FS_ROOT`/home/… — and `none` gives the app the real paths outright, which is what those two levels are for.
 - A clicked link belongs to the host desktop, so it leaves through `org.freedesktop.portal.OpenURI`: the `xdg-open` BINARY is replaced inside the sandbox (a written shim `--ro-bind` over `/usr/bin/xdg-open`) and Qt execs it (measured — `QGenericUnixServices` picks `xdg-open` first, and reaches the portal itself only under `/.flatpak-info`/`SNAP`, which a bwrap profile does not have); Electron does the same. GIO resolves an URI IN-PROCESS, which no shim can reach: for that the prefix seeds `home/.plwl/open-url` (launcher-written, like the shim) plus a desktop entry and a `mimeapps.list` naming it the default for `x-scheme-handler/http|https`, `text/html`, `x-scheme-handler/file` and `inode/directory`. Without the seed GIO falls back to the host's `/usr/share` list — measured: it offered `brave-origin.desktop`, and `gio open` answered "The specified location is not supported". Measured end to end (both backends): the portal launches the host's `helium.desktop` with the exact URI. `GIO_USE_PORTALS=1` was measured and REJECTED: it opened NOTHING and still reported success (GIO's portal path wants a sandbox marker this launcher does not fake). A KDE-native app resolving the link in-process through KIO (`kde-open`) stays uncovered — KDE ignores the seeded list (measured).
-- The games service owns a run through the entry object it created: a start that failed, and the exit of a PREVIOUS run of the same app (stopped, then relaunched — SIGKILL is asynchronous), may not clear the new run's entry or close its request watcher (`forget`/`handleExit` compare that object). A start still in flight is never pruned, however long its isolated hand-off copy takes, because pruning it would drop the watcher mid-start; Stop during that window only records a kill request (`killRequests`), which the start fulfils the moment it has a pid — clearing the state there instead would let a second launch race past the first. Measured in test/games-service.test.js.
 - The portal is not told about a FOLDER or a document, which is what "Open Pack Folder" or a drop asks for: it cannot see a path from in here and answers `Response` 2 for `file://` (measured, while https answered 0). The shim leaves those in `home/.plwl/open-request` (written as `.part` and renamed, so nothing ever reads half a request) — a live bind of the app's home, so it reaches an app that is ALREADY running — and the launcher opens it out here with the host's own `xdg-open` (openrelay.js: `createOpenRelay` watches that folder for exactly as long as the app runs, consumes each request once, and quits watching on exit). The target is rewritten on the way out — the private `$HOME` back to `{prefix}/linux_pfx/home`, `FS_ROOT` back to `/` at relaxed — so the host opens the REAL folder and never a path that only exists inside. Nothing in the sandbox can start a host program itself: measured, the host's own `xdg-open` run in there ends in `kde-open`, which exits 0 and opens no window at all. A scheme nothing on the host claims ends in the desktop's own "choose an application" dialog, which is the point of handing it out instead of guessing.
 - The portal's `Response` is NOT read back: it is a signal addressed to the caller's own bus connection, so a separate `gdbus monitor` never receives it (measured: 15 calls, 15 timeouts, while the portal did open what it was given) and the readback only cost the app 3 s per click before giving up. Only whether the call went out is trusted, so a machine without a portal needs no special case any more: the call fails, and the request file is what still lands. (0.5.x had the host's own script parked inside the sandbox as the shim's fallback; measured, that route opens nothing.)
 - A file handed over (a shortcut's `--file %f`, a drop on it) is the one path the sandbox cannot see by itself: a file out of the user's home is buried under the prefix home, one out of `/tmp` sits behind the private tmpfs, and the rest of the machine is read-only. Per-file `--bind` (what 0.5.0 did) is the wrong tool: a mount cannot be added to a namespace that is ALREADY running, so a hand-off into a running app could never be served that way. `handedPathFor` instead names the document in the one shape the chosen level can reach, and the app is told nothing else: `none` → the real path; `relaxed` → `FS_ROOT` + the real path; `isolated` → a copy in `{prefix}/linux_pfx/home/plwl-handoff/<name>`, which is a live bind of the app's home, so it reaches a running app too (measured end to end in test/linux-e2e.js: both levels hand a document to a sandbox that is already up). Copies are one per name and refreshed on every open (the folder cannot grow), written through a `.part` name and renamed so nothing ever reads a half-written document, and the app's edits stay in the copy — that IS the level's promise. A handed path that is gone fails the hand-off instead of launching an app with no document.
@@ -141,12 +140,11 @@ node test/lansync-pending-links.test.js  # links to files created later, startup
 node test/lansync-consent.test.js        # accept / decline / timeout gate
 node test/lansync-token.test.js          # long-sync token expiry (sliding TTL)
 node test/bench-sync.js                  # timing: cold vs cached sync
-node test/linux-sandbox.test.js          # bwrap argv profile + the four levels, handed paths, mode gate
+node test/linux-sandbox.test.js          # bwrap argv profile + the four levels, handed paths, mode migration
 node test/linux-env.test.js              # redirected HOME/XDG_* for both backends
 node test/linux-import.test.js           # ELF/AppImage/.desktop detection + icons
 node test/linux-links.test.js            # link opening: shim binds + mime seed
 node test/linux-open.test.js             # what an app opens: the script + the launcher relay
-node test/games-service.test.js          # run bookkeeping: the request watcher, Stop while starting
 node test/linux-sync.test.js             # linux_pfx stays out of a sync
 node test/linux-e2e.js                   # REAL runs: plain, relaxed (+ its mount), isolated, hand-off into a running app
 npm start                                # click through the flow you touched

package.json

@@ -1,7 +1,7 @@
 {
   "name": "PLWL",
   "productName": "PLWL",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "description": "Portable Linux Wine Launcher",
   "main": "src/main.js",
   "scripts": {

src/ipc/games.js

@@ -22,9 +22,11 @@ function sendToWindow(win, channel, data) {
 // Game-process state: id -> { pid, resolved prefix name and wine id }, frozen
 // at launch (the in-use guards must name what the process really locked).
 // onGamesChanged fires in the main process when the running set changes.
+const STARTUP_GRACE_MS = 60000
+
 function createGamesService({ getWindow, onGamesChanged, sandbox, onHandoffProgress, openRelay }) {
   const running = new Map()
-  const starting = new Set()
+  const startedAt = new Map()
   const killRequests = new Set()
   let onGameExit = null
   const notifyChanged = () => {
@@ -41,20 +43,15 @@ function createGamesService({ getWindow, onGamesChanged, sandbox, onHandoffProgr
     }
   }
 
-  // Everything a run owns once it is over: the entry and the watcher on the
-  // app's request folder (openrelay.js).
-  function forget(id) {
-    const entry = running.get(id)
-    running.delete(id)
-    starting.delete(id)
-    if (entry && entry.openRoot && openRelay) openRelay.unwatch(entry.openRoot)
-  }
-
-  // A dead process must not answer "already running" - but a start that is
-  // still in flight owns its entry, however long a hand-off copy takes.
+  // a stale entry (no pid yet / dead pid) must not answer "already running"
   function prune() {
     for (const [id, entry] of [...running]) {
-      if (!starting.has(id) && !alive(entry.pid)) forget(id)
+      if (alive(entry.pid)) continue
+      const age = Date.now() - (startedAt.get(id) || 0)
+      if (!entry.pid && age < STARTUP_GRACE_MS) continue // may still be starting
+      running.delete(id)
+      startedAt.delete(id)
+      if (entry.openRoot && openRelay) openRelay.unwatch(entry.openRoot)
     }
   }
 
@@ -89,10 +86,11 @@ function createGamesService({ getWindow, onGamesChanged, sandbox, onHandoffProgr
     return require('../wines').resolveWine(game.wine || 'system')
   }
 
-  // `entry` is the run that exited: a previous run of the same app (stopped and
-  // then relaunched) must not take the new run's entry and watcher away.
-  function handleExit(id, entry) {
-    if (running.get(id) === entry) forget(id)
+  function handleExit(id) {
+    const entry = running.get(id)
+    running.delete(id)
+    startedAt.delete(id)
+    if (entry && entry.openRoot && openRelay) openRelay.unwatch(entry.openRoot)
     sendToWindow(getWindow(), 'games:changed')
     notifyChanged()
     if (onGameExit) onGameExit(id)
@@ -143,50 +141,48 @@ function createGamesService({ getWindow, onGamesChanged, sandbox, onHandoffProgr
       }
     }
     const openRoot = openRootFor(game)
-    const entry = { pid: null, prefix: library.prefixNameForGame(game), wine: wine ? wine.id : '', openRoot }
-    running.set(id, entry)
+    running.set(id, { pid: null, prefix: library.prefixNameForGame(game), wine: wine ? wine.id : '', openRoot })
     // the app may ask for a folder the moment it paints its window, so the
     // request file is watched before the run starts
     if (openRoot && openRelay) openRelay.watch(openRoot)
-    starting.add(id)
+    startedAt.set(id, Date.now())
     try {
-      const res = await run({ onExit: () => handleExit(id, entry), openFile, onProgress: handoffProgress })
+      const res = await run({ onExit: () => handleExit(id), openFile, onProgress: handoffProgress })
       // stop requested while still starting: kill and clear
       if (killRequests.has(id)) {
         killRequests.delete(id)
         if (res.pid) killProcessGroup(res.pid)
-        forget(id)
+        running.delete(id)
+        startedAt.delete(id)
         sendToWindow(win, 'games:changed')
         notifyChanged()
         return { ok: true, pid: null, logFile: res.logFile || null }
       }
       // no pid: never keep the entry, it would block the next launch
       if (!res.pid) {
-        forget(id)
+        running.delete(id)
+        startedAt.delete(id)
         return { ok: false, error: 'not-started' }
       }
-      starting.delete(id)
-      entry.pid = res.pid
+      const entry = running.get(id)
+      if (entry) entry.pid = res.pid
       sendToWindow(win, 'games:changed')
       notifyChanged()
       return { ok: true, pid: res.pid, logFile: res.logFile || null }
     } catch (err) {
-      killRequests.delete(id)
-      forget(id)
+      running.delete(id)
+      startedAt.delete(id)
       return { ok: false, error: String((err && err.message) || err) }
     }
   }
 
-  // Stop clears the state - except while a run is still starting: that start
-  // kills it the moment it has a pid, and clearing the entry here would let a
-  // second launch race past the running one.
+  // Stop always clears the state.
   async function kill(id) {
     const entry = running.get(id)
-    if (entry && !entry.pid) killRequests.add(id)
-    else {
-      if (entry) killProcessGroup(entry.pid)
-      forget(id)
-    }
+    if (entry) killProcessGroup(entry.pid)
+    else if (running.has(id)) killRequests.add(id)
+    running.delete(id)
+    startedAt.delete(id)
     sendToWindow(getWindow(), 'games:changed')
     notifyChanged()
     return { ok: true }

src/library.js

@@ -38,6 +38,7 @@ function loadGames() {
       g[k] = usePrefix && isPrefixRel(g[k]) ? path.join(usePrefix, g[k]) : resolvePortablePath(g[k])
     }
     if (g.iconSource) g.iconSource = resolvePortablePath(g.iconSource)
+    // an entry written by an older launcher keeps its meaning
     if (g.isolation !== undefined) g.isolation = isolationMode(g.isolation)
     const ps = readPlaySeconds(g.id)
     if (ps != null) g.playSeconds = ps
@@ -115,14 +116,19 @@ function isLinuxGame(game) {
   return !!game && game.kind === 'linux'
 }
 
-// none = plain run, relaxed = whole host filesystem mounted writable, isolated
-// = the stock read-only profile, auto = relaxed where bwrap works.
+// none = plain run, relaxed = bwrap + the whole host filesystem mounted rw,
+// isolated = bwrap + handed documents copied in, auto = relaxed where bwrap
+// works and none where it does not.
 const ISOLATION_MODES = ['auto', 'none', 'relaxed', 'isolated']
+// Modes written by launcher 0.5.x: `off` was the plain run, `require` was
+// "bwrap or refuse" - which is exactly what the strictest level means now.
+const LEGACY_ISOLATION_MODES = { off: 'none', require: 'isolated' }
 
-// One known mode, always: an unknown value would otherwise reach the runner and
-// pick a level nobody asked for.
+// One known mode, always: an unknown value would otherwise reach the runner
+// and pick something nobody asked for.
 function isolationMode(value) {
-  return ISOLATION_MODES.includes(value) ? value : 'auto'
+  const mode = LEGACY_ISOLATION_MODES[value] || value
+  return ISOLATION_MODES.includes(mode) ? mode : 'auto'
 }
 
 function sanitizeLinuxPatch(patch) {

src/linuxrunner.js

@@ -27,8 +27,10 @@ const XDG_LAYOUT = {
   XDG_STATE_HOME: ['state', path.join('.local', 'state')]
 }
 
-// Write access goes to the folder the app was imported from and nowhere else
-// outside its home: a portable app writes its logs next to itself.
+// Write access is handed out to the folder the app was imported from and to
+// nothing else outside its home: a portable app writes its logs and data next
+// to itself (Prism Launcher refuses to start otherwise), while system trees
+// must never come back writable.
 const SYSTEM_DIRS = ['/bin', '/sbin', '/lib', '/lib32', '/lib64', '/libx32', '/usr', '/etc', '/boot', '/proc', '/sys', '/dev', '/run']
 
 function writableAppDir(game) {
@@ -73,8 +75,9 @@ function copyFromHost(src, dst, { refresh = false } = {}) {
   }
 }
 
-// With HOME redirected there is no pulse cookie, and everything through Pulse
-// comes up silent; copied once, then the app owns it.
+// PulseAudio looks for its cookie under $HOME/.config/pulse; with HOME
+// redirected there is none, and sound dies for everything going through
+// Pulse. Copied once - the app owns it afterwards.
 function seedPulseCookie(root) {
   const dst = path.join(root, 'config', 'pulse', 'cookie')
   const seeded = copyFromHost(path.join(os.homedir(), '.config', 'pulse', 'cookie'), dst)
@@ -85,8 +88,9 @@ function seedPulseCookie(root) {
   }
 }
 
-// The host's desktop preferences, not its data: without them Qt/GTK fall back
-// to their built-in light look (KDE's dark palette lives in kdeglobals).
+// The host's desktop preferences, not its data: a redirected home has no
+// theme at all, and Qt/GTK then fall back to their built-in light look (KDE's
+// dark palette lives in kdeglobals).
 const DESKTOP_SEEDS = [
   'kdeglobals',
   'kdedefaults/kdeglobals',
@@ -98,17 +102,21 @@ const DESKTOP_SEEDS = [
   'user-dirs.dirs'
 ]
 
-// The host's desktop *data* (fonts, icons, themes) is not copied but handed
-// over read-only: see buildBwrapArgs.
+// The host's desktop *data* - fonts, icons, themes, colour schemes - is not
+// copied but handed over read-only (see buildBwrapArgs), so it follows the
+// host without an import.
 const DATA_SHARES = ['fonts', 'icons', 'themes', 'color-schemes']
 
-// A clicked link is the host desktop's business: the association naming a
-// browser lives in the host's own home, so the URI goes to the host's portal.
+// A clicked link is the host desktop's business: in here there is no default
+// browser at all, because the association (mimeapps.list) and the .desktop
+// file it names live in the host's own home. Handing the URI to the host's
+// portal is the only route that ends in the browser the user actually chose.
 const PORTAL_BUS = 'org.freedesktop.portal.Desktop'
 const PORTAL_METHOD = 'org.freedesktop.portal.OpenURI.OpenURI'
 const OPEN_BINS = ['/usr/bin/xdg-open', '/bin/xdg-open', '/usr/local/bin/xdg-open']
-// Launcher-owned files in the redirected home (never mounted into a sandbox),
-// rewritten whenever they differ.
+// Launcher-owned files, kept in the redirected home: the app never edits them,
+// and each is rewritten whenever it differs. The prefix root is not mounted in
+// the sandbox, so nothing a link needs may live there.
 const SHIM_NAME = 'xdg-open'
 const OPENER_NAME = 'open-url'
 const OPENER_DESKTOP = 'plwl-url-opener.desktop'
@@ -147,10 +155,19 @@ function writeIfChanged(file, text, mode) {
   }
 }
 
-// The one script both hand-offs run: xdg-open's stand-in inside a sandbox, and
-// what the seeded desktop entry starts. A scheme goes to the host's portal
-// (chooser included), a path to the request file the launcher watches - the
-// portal's answer is unreadable (development.md), the call is all we can trust.
+// The one script both hand-offs run: it takes xdg-open's place inside a
+// sandbox and it is what the seeded desktop entry starts. A URI with a scheme
+// belongs to the host's portal, which also puts up its own "choose an
+// application" when nothing claims that scheme; everything else - every local
+// document, folder or plain path - is left in the request file for the
+// launcher (see openrelay.js), with the path rewritten first, because the
+// private home and the whole-disk mount are the two names the host answers to
+// differently. Nothing in here starts a host program itself: measured, the
+// host's own xdg-open *inside* the sandbox ends in kde-open, which exits 0 and
+// opens no window at all. The portal's answer is not read back either: it is a
+// signal addressed to the caller's own bus connection, so a separate monitor
+// never receives it (measured: 15 calls, 15 timeouts, while the portal did
+// open what it was given) - only whether the call itself went out can be used.
 function handOffScript({ hostHome, fsRoot, request }) {
   const cases = [
     `file://"$HOME") arg="file://${hostHome}" ;;`,
@@ -170,7 +187,8 @@ function handOffScript({ hostHome, fsRoot, request }) {
 arg="$1"
 [ -n "$arg" ] || exit 1
 
-# a link is the host portal's from here on; anything else falls back
+# the portal owns a link from here on, chooser and all; only a call that does
+# not go out at all (no portal on this machine) falls back to the launcher
 open_portal() {
   command -v gdbus >/dev/null 2>&1 || return 1
   gdbus call --session --dest ${PORTAL_BUS} \\
@@ -192,13 +210,13 @@ printf '%s\\n' "$arg" > "${request}.part" && mv "${request}.part" "${request}" |
 `
 }
 
-// The stand-in for xdg-open inside the sandbox, and (same script) what the
-// seeded desktop entry runs: a browser started in here would be the wrong one,
-// with an empty profile growing inside the prefix.
+// The stand-in for xdg-open inside the sandbox.
 function writeUrlShim(root, opts) {
   return writeIfChanged(path.join(root, SHIM_REL), handOffScript(opts), 0o755)
 }
 
+// What the seeded desktop entry runs. Same hand-off: a browser started in here
+// would be the wrong one, with an empty profile growing inside the prefix.
 function writeUrlOpener(root, opts) {
   return writeIfChanged(path.join(root, OPENER_REL), handOffScript(opts), 0o755)
 }
@@ -210,10 +228,14 @@ function linkOpenerName() {
   return text === 'sandbox.linkOpener' ? 'PLWL' : text
 }
 
-// GIO resolves an URI in-process (gtk_show_uri, `gio open`) and would pick a
-// system browser in here: naming our opener the default for exactly these types
-// changes only its answer. GIO's own portal path is not reachable (it wants a
-// sandbox marker this launcher does not fake).
+// GIO resolves an URI in-process (gtk_show_uri, `gio open`) against the MIME
+// lists, and the host's default browser is not among the choices in here: it
+// would open a system browser, or none at all. Naming our opener as the
+// default for exactly these types leaves that resolution alone and changes
+// only its answer - including the two a local document comes in as (measured:
+// Qt hands xdg-open a file:// URI, GIO resolves a folder by inode/directory).
+// The portal itself is not reachable this way - GIO looks for a sandbox marker
+// this launcher does not fake (measured: GIO_USE_PORTALS opens nothing).
 function writeMimeSeed(root, home) {
   const desktop = [
     '[Desktop Entry]',
@@ -230,8 +252,10 @@ function writeMimeSeed(root, home) {
   return writeIfChanged(path.join(root, MIME_REL), mime, 0o644)
 }
 
-// Everything an opened thing needs: the hand-off script, the association naming
-// it the default, and - in a sandbox - xdg-open replaced by the same script.
+// Everything an opened thing needs: the hand-off script, the association
+// naming it as the default, and - in a sandbox - xdg-open replaced by the same
+// script. A machine without a portal needs no special case: the script's call
+// is what fails there, and the request file is what still lands.
 function urlRouting({ root, home, sandboxed, fsRoot = false }) {
   const target = OPEN_BINS.find(bin => fs.existsSync(bin)) || ''
   const opts = { hostHome: path.join(root, 'home'), fsRoot, request: requestPath(home) }
@@ -249,12 +273,22 @@ function hashOf(file) {
   }
 }
 
-// Hashes of what we seeded, kept in the prefix root: the app only ever sees
-// home/config/data/cache/state.
+function mtimeOf(file) {
+  try {
+    return fs.statSync(file).mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+// Hashes of what we put in the prefix, so a host change can be followed while
+// the app has not touched our copy. Kept in the prefix root: the app only
+// ever sees home/config/data/cache/state.
 const SEED_MARKER = '.seeded.json'
 
-// Keeps a seeded preference following the host while the copy is provably ours;
-// an app's own edit is never overwritten.
+// Copies a preference in, then keeps following it for as long as we can prove
+// the copy is still ours: an unusable theme is worse than a stale one, and an
+// app's own edit is never overwritten.
 function syncDesktopConfig(root) {
   const hostConfig = path.join(os.homedir(), '.config')
   const markerFile = path.join(root, SEED_MARKER)
@@ -266,12 +300,19 @@ function syncDesktopConfig(root) {
     const hostHash = hashOf(src)
     if (!hostHash) continue
     const known = marker[rel]
-    if (fs.existsSync(dst) && known) {
+    if (fs.existsSync(dst)) {
       const current = hashOf(dst)
-      // the app owns it now, or there is nothing to do
-      if (current !== known || current === hostHash) continue
+      if (known) {
+        // the app owns it now, or there is nothing to do
+        if (current !== known || current === hostHash) continue
+      } else if (current !== hostHash && mtimeOf(dst) >= mtimeOf(src)) {
+        // a prefix from an older launcher: an identical copy is ours, and so is
+        // one the host's file has since outgrown. A copy that is not older than
+        // the host's is the app's own - ties stay with the app
+        continue
+      }
     }
-    // no marker entry: the copy is ours (seeded before the marker existed)
+    // refresh: this is provably still our own copy
     if (copyFromHost(src, dst, { refresh: true })) {
       marker[rel] = hostHash
       changed = true
@@ -284,8 +325,9 @@ function syncDesktopConfig(root) {
   }
 }
 
-// X11 access: a cookie is session state, not data, so XAUTHORITY is refreshed
-// rather than seeded once.
+// X11 access: XAUTHORITY usually lives in /run/user (bound), but a launcher
+// started without it would leave X11 dead inside. Refreshed: a cookie is
+// session state, not data.
 function seedXauthority(root) {
   copyFromHost(path.join(os.homedir(), '.Xauthority'), path.join(root, 'home', '.Xauthority'), { refresh: true })
 }
@@ -301,8 +343,10 @@ function seededRelPaths() {
   ]
 }
 
-// Drops what we seeded (and the hashes tracking it) so the next start seeds
-// clean ones; the app's own files in the same folders are never touched.
+// syncDesktopConfig only follows the host while the copy is provably ours, so
+// an app that edited its own theme keeps it forever. The reset drops our
+// copies (and the hashes that track them) and lets the next start seed clean
+// ones - the app's own files in the same folders are never touched.
 function resetSeededConfig(name) {
   const root = prefixLinuxRoot(name)
   const removed = []
@@ -334,8 +378,9 @@ function ensureLinuxPfx(name) {
   return root
 }
 
-// XWayland is the only place a window can carry its own icon, and GLFW/Qt/GTK
-// all read these, so one switch moves the whole process tree back to X11.
+// Wayland cannot carry a window icon and the compositor only guesses one from
+// the app id; XWayland can, and GLFW/Qt/GTK all read these, so one flag moves
+// the whole process tree (Prism and the Minecraft it launches) back to X11.
 const X11_ENV = { XDG_SESSION_TYPE: 'x11', QT_QPA_PLATFORM: 'xcb', GDK_BACKEND: 'x11' }
 
 // The theme data sits in front of the inherited list: on the host the user's
@@ -359,8 +404,10 @@ function buildLinuxEnv({ game, backend = 'env', fsRoot = false }) {
   for (const [key, [hostDir, sandboxSub]] of Object.entries(XDG_LAYOUT)) {
     env[key] = sandboxed ? path.join(home, sandboxSub) : path.join(root, hostDir)
   }
-  // The X session manager sits in the private /tmp, so its pointer would lead
-  // to a dead socket. XDG_RUNTIME_DIR stays the host's (it weakens isolation).
+  // XDG_RUNTIME_DIR stays the host's: Wayland, PipeWire and the session bus
+  // live there. It weakens the isolation, and the UI says so.
+  // The X session manager sits in the private /tmp, so its pointer would only
+  // lead to a dead socket; clients skip it when it is absent.
   if (sandboxed) delete env.SESSION_MANAGER
   // the host's fonts/icons/themes: mounted read-only by buildBwrapArgs, or - in
   // a plain run, where nothing is hidden - just put on the search path
@@ -368,19 +415,23 @@ function buildLinuxEnv({ game, backend = 'env', fsRoot = false }) {
   if (game.forceX11) Object.assign(env, X11_ENV)
   // the app's own environment comes last: it overrides everything above
   for (const [k, v] of Object.entries(game.env || {})) env[k] = v
-  // an opened link or document leaves for the host desktop (see openrelay.js)
+  // an opened link or document must leave for the host desktop; `home` is where
+  // the seeded desktop entry has to find the opener, so it is resolved first
   return { env, root, home, prefixName, prefixDir: prefixPath(prefixName), routing: urlRouting({ root, home, sandboxed, fsRoot }) }
 }
 
-// Where a handed document goes inside the app's own home - a live bind, so a
-// copy written here reaches an app that is already running too.
+// Where a handed document goes inside the app's own home. The prefix home is
+// a live bind of a host folder, so a copy written here is visible to an app
+// that is already running - the one route a running namespace can be reached
+// through at all.
 const HANDOFF_DIR = 'plwl-handoff'
 // Copies above this are worth a popup: below it the copy is over before a
 // window could paint, and the launcher would flash for nothing.
 const STAGE_NOTICE_BYTES = 50 * 1000 * 1000
 
-// Awaited because a shortcut boots HEADLESS: without a measurement "auto" would
-// quietly pick the weaker level.
+// The probe measures once and answers from its cache afterwards. It is awaited
+// here because a shortcut boots HEADLESS: no renderer ran, so nothing else
+// would have measured, and "auto" would quietly pick the weaker level.
 async function levelStatus(sandbox) {
   if (!sandbox || typeof sandbox.status !== 'function') return null
   const cached = sandbox.status()
@@ -393,8 +444,11 @@ async function levelStatus(sandbox) {
   }
 }
 
-// `auto` is the only level that may weaken itself: a machine without bwrap runs
-// the app plain, while an explicit relaxed/isolated refuses instead.
+// bwrap when it works, plain run otherwise - unless the app demands a sandbox.
+// `auto` is the only level allowed to take a weaker one: a machine that cannot
+// sandbox runs the app plain, while an explicit relaxed/isolated refuses
+// instead of quietly dropping the promise. (Values written by launcher 0.5.x
+// are mapped to these four by library.js.)
 async function resolveLevel({ game, sandbox }) {
   const policy = (game && game.isolation) || 'auto'
   const status = await levelStatus(sandbox)
@@ -429,9 +483,15 @@ function linuxPathFor(file) {
   return abs
 }
 
-// The document a shortcut was handed, in the shape the chosen level can reach:
-// none = the host path, relaxed = through FS_ROOT, isolated = a copy in the
-// app's own home (refreshed on every open). '' when there is nothing to hand over.
+// The document a shortcut was handed, in the one shape the chosen level can
+// reach - and the app is told nothing else, so a second hand-off names the
+// same file the same way.
+//   none     the host path, exactly what a shell would name
+//   relaxed  the same file through the whole-host mount every run carries
+//   isolated a copy in the app's own home, refreshed on every open (one copy
+//            per name, so the folder cannot grow; the app's edits stay in the
+//            copy - that is this level's promise)
+// Returns '' when there is nothing to hand over, so argv stays honest.
 async function handedPathFor({ openFile, level, root, home, onProgress }) {
   if (!openFile) return ''
   const abs = linuxPathFor(openFile)

src/openrelay.js

@@ -1,27 +1,30 @@
 'use strict'
 
-// What a sandboxed app asked to open - a folder, a document, a path: nothing in
-// there can start a host program (measured), so the hand-off script leaves the
-// host-rewritten target in a request file inside the app's home (a live bind)
-// and the launcher opens it here with the host's own xdg-open.
+// What a sandboxed app asks to open: a folder, a document, a link the portal
+// refused. The app cannot start anything out here itself - measured, the host's
+// own xdg-open *inside* the sandbox ends in kde-open, which exits 0 and opens no
+// window - so the hand-off script leaves the (already host-rewritten) path in a
+// request file inside the app's home, which is a live bind, and the launcher
+// opens it here with the host's own xdg-open.
 
 const fs = require('fs')
 const path = require('path')
 const { spawn } = require('child_process')
 
-// The hand-off protocol, in one place: the folder PLWL owns inside an app's home
-// (the shim and opener are written there too) and the file the launcher watches.
+// The hand-off protocol, in one place: the folder PLWL owns inside an app's
+// home (the shim and the opener are written there too) and the file the
+// launcher watches.
 const PLWL_DIR = '.plwl'
 const REQUEST_NAME = 'open-request'
 const DRAIN_DEBOUNCE_MS = 60
 
-// `homeDir` is that home as the host sees it: a live bind, so a write is here
-// the moment it lands.
+// `homeDir` is that home as the host sees it - the prefix's own `home`, which
+// is a live bind, so what the app writes is here the moment it lands.
 const requestPath = homeDir => path.join(homeDir, PLWL_DIR, REQUEST_NAME)
 const requestFile = root => requestPath(path.join(root, 'home'))
 
-// detached: the opened program is the desktop's child, and outlives a launcher
-// that quit to the tray
+// detached: the opened program is the desktop's child, not the launcher's - it
+// must outlive a launcher that quits to the tray and never hold it open
 function openOnHost(target) {
   spawn('xdg-open', [target], { detached: true, stdio: 'ignore' }).unref()
 }
@@ -29,8 +32,9 @@ function openOnHost(target) {
 function createOpenRelay({ open = openOnHost, onError = null } = {}) {
   const watchers = new Map()
 
-  // consumed before it is opened: a second click overwrites the file, so nothing
-  // is opened twice and nothing is lost
+  // the request is consumed before it is opened: a second click while the first
+  // program starts writes a fresh file, so nothing is opened twice and nothing
+  // is dropped
   function drain(root) {
     let target = ''
     try {
@@ -47,8 +51,8 @@ function createOpenRelay({ open = openOnHost, onError = null } = {}) {
     }
   }
 
-  // a request written before the watcher was up (the app's first window) must
-  // not be missed, so drain once first
+  // watch from the moment the app starts: a request written before the watcher
+  // was up (the app's first window) must not be missed, so drain once first
   function watch(root) {
     if (!root || watchers.has(root)) return
     const file = requestFile(root)

src/sandbox.js

@@ -4,8 +4,9 @@ const { execFile } = require('child_process')
 const fs = require('fs')
 const path = require('path')
 
-// bwrap only works when unprivileged namespaces really work (Ubuntu's AppArmor
-// kills it), so a functional probe decides - never `which bwrap`.
+// bubblewrap is only usable when unprivileged user namespaces actually work:
+// Ubuntu 24.04 ships bwrap but AppArmor kills it ("Failed to unshare user
+// namespace"), so a functional probe decides - not `which bwrap`.
 const PROBE_TIMEOUT_MS = 3000
 // /bin/true is a symlink on most distros but missing on a few; env is the
 // last resort that still exits 0.
@@ -92,18 +93,23 @@ function createSandboxProbe({ timeoutMs = PROBE_TIMEOUT_MS } = {}) {
   }
 }
 
-// Host theme data is mounted read-only here and listed in XDG_DATA_DIRS (inside
-// the private /tmp, where the app cannot mistake it for its own data). A bind,
-// not a symlink: the prefix is mounted over ~, so a link would point at itself.
+// Host theme data (fonts, icons, colour schemes) is mounted read-only under
+// this path - inside the private /tmp the app cannot mistake it for its own
+// data, and the caller lists it in XDG_DATA_DIRS. A bind, not a symlink: the
+// prefix is mounted over ~, so a link back into ~ would point at itself.
 const SHARE_ROOT = '/tmp/.plwl-host'
 
-// Relaxed isolation mounts the whole host filesystem writable here. It takes
-// the private /tmp (bwrap creates the mount point itself) and one fixed string,
-// so a hand-off into an app that is ALREADY running resolves too.
+// Relaxed isolation hands the app the whole host filesystem as ONE writable
+// mount. It has to sit under the private /tmp: bubblewrap creates a mount
+// point itself, and the root of a read-only root cannot be written (measured:
+// "Can't create file /PLWL_FS_ROOT: Read-only file system"). Being there, one
+// path string works in every run - which is what a hand-off into an app that
+// is ALREADY running needs, since a mount cannot be added to a live namespace.
 const FS_ROOT = '/tmp/plwl-fs-root'
 
 // The bwrap profile for a native Linux app. Pure: the caller decides which
-// devices and host folders exist, so the argv is testable as-is.
+// devices and host folders exist on this machine, so the argv is testable
+// as-is.
 function buildBwrapArgs({
   dataRoot,
   user,
@@ -136,13 +142,16 @@ function buildBwrapArgs({
     '--tmpfs', '/tmp',
     // X11 sockets live in /tmp, which the tmpfs above just emptied
     ...(x11 ? ['--ro-bind', x11, x11] : []),
-    // relaxed: the whole host filesystem, writable. Nothing is hidden, and the
-    // app may write anywhere on the machine - that is this level's price.
+    // relaxed: the host filesystem, whole and writable. Nothing is hidden in
+    // here, so a document handed over later can be opened - and saved - where
+    // the app was told it is. The price is the filesystem promise itself: an
+    // app at this level may write anywhere on the machine.
     ...(fsRoot ? ['--bind', '/', FS_ROOT] : []),
     // the host's theme data, read-only: fonts, icons, colour schemes
     ...shares.flatMap(dir => ['--ro-bind', dir, path.join(SHARE_ROOT, path.basename(dir))]),
-    // an opened link or document belongs to the host desktop, so xdg-open is
-    // replaced by the launcher's hand-off script (linuxrunner.js)
+    // an opened link or document belongs to the host desktop: xdg-open is
+    // replaced by the launcher's hand-off script (the portal for a link, the
+    // launcher itself for a document - see linuxrunner.js)
     ...(urlOpener && urlOpener.shim ? ['--ro-bind', urlOpener.shim, urlOpener.target] : []),
     // hard profile: nothing of anybody's /home is even readable
     ...(hideHome ? ['--tmpfs', '/home', '--tmpfs', '/root', '--tmpfs', '/mnt', '--tmpfs', '/media'] : []),