Skip to content

Lock File Handling During Install/Uninstall

This document describes how lock files (vayu.lock) are handled during installation and uninstallation across all platforms.

Overview

One engine runs per data directory. The engine takes an exclusive lock at startup and exits 1 with "Another instance of Vayu Engine is already running" when another engine holds it. What it locks differs by platform:

  • Linux and macOS: a flock on the data directory itself, plus one on vayu.lock inside it. The directory lock is the guard: a flock lives on an inode, so a lock on the file alone was released for every newcomer the moment something unlinked the file, and two engines then served one database (issue #2422). Deleting vayu.lock no longer lets a second engine in. The file is still locked so an engine from before this change, which locks only the file, and a current one keep each other out. A filesystem that cannot lock a directory (some network volumes answer ENOTSUP or EINVAL) falls back to the file alone, and the engine logs a warning that the guard is weaker there.
  • Windows: vayu.lock is opened with share mode 0 and byte-locked, so it cannot be deleted while the engine holds it.

Every platform releases the lock when the engine process ends, however it ends. vayu.lock itself is the PID record the app reads (checkLockFile): it holds the PID of the running engine process and is located at:

  • Windows: %APPDATA%\Vayu\vayu.lock
  • macOS: ~/Library/Application Support/Vayu/vayu.lock
  • Linux: ~/.config/Vayu/vayu.lock

The directory is app.getPath("userData"), which main.ts sets to USER_DATA_DIR_NAME (app/electron/constants.ts) before anything opens a file there. engineDataDirectory() (app/electron/sidecar.ts) is the one place that resolves it; anything else naming a directory is a copy that can drift.

Platform-Specific Handling

Windows (NSIS Installer)

Installation (installer.nsh): - Checks if Vayu is running and prompts user to close it - Kills any orphaned vayu-engine.exe processes - Removes stale lock files during installation - Not on an updated launch. "Restart to install" runs the installer with --updated (not /S) while the app is still shutting down - the renderer's save flush, then the engine's graceful exit. customInit does none of the three there: no prompt, no taskkill, no lock Delete. electron-builder's own running-app check waits for the app to exit and force-kills only after, and a lock left behind is reclaimed by app startup (#1882)

Uninstallation (installer.nsh): - Kills running Vayu and engine processes before uninstall - "Keep my data" removes only the lock file; "Delete everything" removes the whole data directory, and logs a skip rather than deleting anything if that directory is not there - Lock file path: $APPDATA\${APP_DATA_DIR}\vayu.lock

NSIS cannot read package.json, so the script defines APP_DATA_DIR once and uses it everywhere rather than spelling a path. app/electron/installer-nsh-paths.test.ts fails if that define drifts from the name, if any path bypasses it, or if a path segment anywhere in the file - comments included - is productName. It is the Windows counterpart to the Script lint job's check over the shell scripts, which covers ~/.config/ and cannot see a .nsh file.

Both macros also flip NSIS back to the user's shell context around those paths. An all-users install leaves NSIS in the machine context, where $APPDATA is not the roaming profile Electron writes userData to - so a correctly named path would still miss the real directory in that install mode.

Until #1393 the script named productName for both, so "Delete everything" ran RMDir /r over $APPDATA\Vayu and removed nothing the app owns - the same wrong-directory defect the Linux hooks had, and worse, because here it was a promise about the user's data rather than a no-op.

macOS (DMG)

Installation: - No install hooks (DMG doesn't support them) - Lock file cleanup handled automatically in app startup (see below)

Uninstallation: - User manually drags app to Trash - Lock file cleanup handled automatically in app startup on next launch

Linux (.deb Package)

Installation: - No maintainer script of Vayu's. The package's postinst is the one electron-builder generates; stale locks are reclaimed by app startup (see below)

Uninstallation: - app/installer/linux-prerm.sh, wired as fpm's --before-remove in app/electron-builder.json, kills any running vayu-engine so dpkg does not replace or remove the binary underneath a live process. It touches no path, which is why running as root does not break it - Lock file cleanup handled automatically in app startup

A postinst and a postrm hook used to clean the lock file here. They were removed (#1356): both looked for $HOME/.config/vayu/vayu.lock, a directory the app has never written, and dpkg runs maintainer scripts as root, so even the right directory name would have resolved under /root rather than the installing user's home. The recovery they attempted - read the PID, verify it belongs to vayu-engine, remove the file if not - is what startup already does, against a path it resolves rather than spells, and at every launch rather than only at install time.

They also cost more than they looked. afterInstall and afterRemove are passed to fpm as --after-install and --after-remove, which replace electron-builder's generated maintainer scripts rather than running alongside them, so every .deb built while those hooks existed shipped the lock cleanup in place of the /usr/bin/vayu-client alternative, the chrome-sandbox mode fix, the mime and desktop database updates and the AppArmor profile Ubuntu 24 requires. Removing them restores all of it. Anything a future hook needs to do belongs in a script that keeps that generated content, not one that supersedes it.

AppImage: - No install/uninstall hooks - Lock file cleanup handled automatically in app startup

Automatic Cleanup on App Startup

The Electron sidecar (app/electron/sidecar.ts) automatically handles stale lock files:

  1. Checks lock file before starting the engine
  2. Reads PID from lock file
  3. Verifies process is still running - cheap first, subprocess second: a signal-0 probe answers a PID nothing holds, and only a live PID is worth a tasklist / ps call to verify the name
  4. Removes stale lock only when that is proven: the PID is dead, or the name read back is not vayu-engine
  5. Keeps the lock of a live PID whose name could not be read (below)
  6. Waits for, then replaces, a live engine that never answers /health (below)
  7. Logs warnings for debugging

This ensures that: - Stale locks from crashes are cleaned up - Reinstalls work correctly - No manual intervention needed

A PID it cannot classify keeps its lock, and is never killed (issue

2422). The name check is a subprocess (ps -p <pid> -o comm=, or tasklist

on Windows), and it can fail to run: ps missing from a minimal container, a tasklist that errors. engineProcessState answers unknown then, distinct from not-engine, because a live PID whose name cannot be read may be the engine. The sidecar treats it as live for the lock (it is not removed) and as unverified for the kill (the name-verified kill refuses it, so a recycled PID is never signalled). Startup stays bounded: the PID goes through the wait below on the same health budget, the stop's grace period, then the spawn, and the engine's own lock decides whether this session's engine can start. A PID recycled by another program on such a system costs that wait once; the new engine then writes its own PID over the file.

A live engine is replaced, never adopted (issue #2356). The lock file can point at a PID that is alive and answering /health: an orphan from a crashed session, two installed builds sharing a data directory, or an engine started by hand on this data directory. Every write to file trust (an allowed folder, a picked file) needs the grant secret the app passes the engine it spawns, and that engine was given another launch's secret or none, so EngineSidecar stops it (POST /shutdown, then the same PID kill the graceful path already falls back to) and spawns its own on the same port. That also covers an engine built for a different Vayu release (issue #1492).

Only an engine serving this data directory is stopped (issue #3328). An engine answering /health on a candidate port is the app's when the dataDir it reports matches the app's data directory (both resolved, no trailing separator, case ignored on Windows only). One serving another directory - a standalone vayu-engine for vayu-cli, a second app instance on another profile - holds its port like any other program: never sent /shutdown, never killed, and the next candidate is tried. An engine too old to report dataDir is never the app's, with or without a live lock: the lock proves the app's engine exists, not that this answering engine is it, so it is left alone and its port counted held. After upgrading across that change, an orphan of the old release must be quit by hand (the port-in-use error names it). A standalone daemon is left alone only when its --data-dir differs from the app's, which is <repo>/engine/data in a development build: a daemon run from engine/ with its defaults serves that same directory and is replaced, so give it its own --data-dir.

A live lock PID that does not answer /health is waited for, then replaced (issue #1905). Between "stale" and "healthy" there is a third case: the PID is alive and is a Vayu engine, but nothing answers on the port. It is either still starting - an orphan from a crashed session reads its database and runs migrations before it listens - or hung. Spawning beside it loses the flock, and reporting the port as held would blame another program for Vayu's own engine. So EngineSidecar polls /health on the same ramped budget a freshly spawned engine gets (ENGINE_HEALTH_POLL_BUDGET_MS). An engine that answers in time as this data directory's is asked to shut down and replaced like any other (above); an answer from an engine serving another directory does not end the wait. One that does not is stopped by PID (the name-verified kill, so a recycled PID is left alone), the port is given ENGINE_PORT_RELEASE_DELAY_MS to clear, the replaced PID is logged, and this instance spawns its own. The port-in-use error (EnginePortInUseError) is left for ports held when the lock file names no live Vayu engine, or held by an engine serving another data directory.

A live lock is looked for on every candidate port (issue #2118). The engine may run on 9876 or a fallback (ENGINE_PORT_CANDIDATES), so with a live lock PID every candidate is asked for /health before any free port is taken: an orphan left on a fallback port is replaced there even after 9876 has come free, and an engine serving another data directory on an earlier candidate does not shadow it. When it answers on none, the wait above watches the first free candidate (where a still-starting engine, not yet listening, would be), or the first not held by another data directory's engine when none is free. When every candidate is held by such engines, startup reports "Another Vayu engine is using port 9876" without waiting.

The engine releases the lock after its database has closed (issue #2420). run_daemon (engine/src/daemon.cpp) holds the lock in an InstanceLock declared before the Database, so on the way out the database's destructor - its close-time WAL checkpoint included - runs first and the lock goes last, on an early exit and a thrown startup error as much as on a graceful shutdown. A replacement that wins the lock therefore never meets its predecessor's connection at its own startup probe. A graceful shutdown's final refresh of <db>.bak (issue #2421) runs before the database closes, so the lock is held through that copy too, and a replacement never starts against a backup still being written. If something else still holds the database when an engine starts (a sqlite3 shell left in a transaction, a sync agent), the engine waits for it (10 s on each connection it opens), then exits 1 naming the database and leaves every file as it was, rather than treating the held file as corrupt (db-schema.md). Because the lock is held before the database opens, the startup reconcile that marks running and pending runs as failed only ever meets runs a dead engine left behind; the lock is the whole ownership check, and run rows carry no owner.

Manual Cleanup

Quit Vayu first. A lock file left behind after that is only a stale PID record (the lock itself went with the engine process), and removing it is safe:

Windows:

Remove-Item "$env:APPDATA\Vayu\vayu.lock"

macOS/Linux:

rm ~/.config/Vayu/vayu.lock
# or on macOS:
rm ~/Library/Application\ Support/Vayu/vayu.lock

Removing it while an engine still runs frees nothing: on Windows the delete fails, and on Linux and macOS the engine keeps its lock on the data directory, so a second engine is still refused. To stop an engine that will not quit, end the process whose PID the file names.

Implementation Details

Windows Implementation

  • Uses tasklist and taskkill commands
  • NSIS macros: customInit, customUnInit, customUnInstall
  • File: app/installer/installer.nsh

Linux Maintainer Scripts

  • app/installer/linux-prerm.sh: pre-removal, kills a running vayu-engine
  • It is the only one Vayu writes. The packaged .deb still carries a postinst and a postrm, both generated by electron-builder: the /usr/bin/vayu-client alternative, the chrome-sandbox mode, the mime and desktop databases and the AppArmor profile Ubuntu 24 needs. afterInstall and afterRemove replace those generated scripts rather than adding to them, which is what made the two removed hooks worse than dead: every .deb built while they existed shipped their lock-file cleanup instead of that setup.

Electron Sidecar

  • Function: checkLockFile() - reads the lock file's PID and classifies it
  • Function: engineProcessState() - cross-platform process check with process name verification, answering engine, not-engine or unknown. process.kill(pid, 0) first on every platform (no subprocess, and the stale-lock case ends there), then tasklist / ps to verify the name against PID reuse; a name check that cannot run answers unknown, which keeps the lock and is never killed
  • Method: liveLockPid() - removes the lock only for a not-engine PID
  • Method: identify() - whose engine answers /health on a port: ours (its dataDir is this app's), foreign (another dataDir, or none reported), or none
  • Method: replaceAnsweringEngine() - stops a healthy engine of ours start() finds already on the port, so it can spawn its own
  • Method: replaceLockedEngine() - settles a live lock PID: waits on pollWithinBudget() for ours to answer, then asks it to shut down if it answered or kills it if it stayed silent
  • Automatic cleanup in start() method
  • File: app/electron/sidecar.ts

Testing

To test lock file handling:

  1. Start Vayu - lock file should be created
  2. Kill engine process - lock file should remain
  3. Restart Vayu - stale lock should be detected and removed
  4. Reinstall - the first launch after it reclaims any lock left behind
  5. Delete the lock under a live engine (Linux and macOS) - with an engine running, remove vayu.lock and start vayu-engine --data-dir <same dir>: the second engine exits 1 with "already running" and the first is untouched. engine/tests/file_lock_test.cpp asserts the same in-process

Troubleshooting

Issue: Lock file prevents engine from starting after crash

Solution: A crash releases the lock with the process, so the file left behind names a dead PID and the app cleans it up on startup. An engine that still refuses to start is refused by a live engine on the same data directory, not by the file: stop the PID it names (see Manual Cleanup above).

Issue: Multiple instances error after uninstall/reinstall

Solution: Startup reclaims a lock whose PID is dead or provably not vayu-engine, so launching the reinstalled app is the fix. A live engine that never answers /health is replaced automatically after the health budget; if the engine still refuses to start, the replacement kill failed - stop the PID in the lock file. Removing the lock file does not help while that engine lives.