A symptom → cause → fix index for things that go wrong while running StratoSort Stack locally. If you hit something that isn't listed here, add it after you've solved it.
Cause. Electron was bumped to a version node-abi hasn't published support for yet. The
postinstall script (scripts/postinstall.js) tries to rebuild native modules via
@electron/rebuild and bails.
Fix. Either:
- Check whether
node-abihas a newer release (npm view node-abi versions --json | tail). If yes, bump it:npm install --save-dev node-abi@latest. - Or roll Electron back to the last working version in
package.json.
Note: npm install itself still completes — the dep tree is populated. You can use most scripts
(lint, format, tests using mocks) before native rebuild succeeds.
Cause. node_modules/ wasn't installed (e.g. after a fresh clone or after npm run clean nuked
a parent dir).
Fix. npm install --no-audit --no-fund. Don't --no-verify the commit; the hook is catching a
real problem (your dev env is missing dependencies).
Cause. Preload is built by webpack.main.config.js, not the renderer config. Renderer HMR
doesn't watch it.
Fix. Run npm run build:main:dev whenever you change preload, then reload the app window. Or
use npm run dev (does both builds + electron) from scratch.
Cause. Sandbox is enabled. Runtime require() is forbidden. The module needs to be in the
webpack bundle.
Fix. Don't lazy-require. Add the dep to the relevant webpack entry. If it really has to be
loaded conditionally, move the conditional inside the bundled code, not at the require site.
Cause. Likely a CSP violation or a renderer-process exception during early bootstrap.
Fix. Run npm run start:debug and attach Chrome DevTools to the main process
(chrome://inspect). Or add --enable-logging (already in the dev script) and check
%APPDATA%\StratoSort Stack\logs\ on Windows,
~/Library/Application Support/StratoSort Stack/logs/ on macOS, or
~/.config/StratoSort Stack/logs/ on Linux.
Symptom. After double-clicking StratoSort Stack.exe or the Start Menu shortcut the busy cursor
spins, Task Manager shows several StratoSort Stack.exe entries, and no window appears for a long
time (reports range from tens of seconds to more than a minute).
Three different causes produce this.
- Windows Security scanning newly written files. The first start after installing, reinstalling
or extracting the zip (
StratoSortStack-X.X.X-win-x64.zip) is slower because Windows Security scans the app's files (about 1.8 GB) once. Expect that first start to take up to a minute or two with real-time protection on; later starts reuse the scan verdicts and are expected to take a few seconds. A second start that is as slow as the first is not this cause. Nothing in the app's own log covers this phase because the app process has not started yet. Builds up to v5.0.0 also shipped a self-extracting portable exe (StratoSortStack-X.X.X-win-x64.exe) that unpacked the whole app into a randomly named folder under%TEMP%on every start and paid this cost on every launch. Later releases replace it with the zip, which is extracted once; anyone still running that exe should move to the installer or the zip (seeINSTALL_GUIDE.md). A zip copy started from inside Explorer's compressed-folder view does not start at all, because Explorer extracts only that one exe to a temporary folder. - In-app startup (installer and zip alike). Once
StratoSort Stack.exeis running, the window is created hidden and shown onready-to-show, or force-shown afterTIMEOUTS.WINDOW_SHOW_FALLBACK(4 s) when that event is late, or straight away when the GPU process exits before the first show. Before the window is created, each check or creation of theUncategorizedfolder in Documents gives up afterTIMEOUTS.DEFAULT_FOLDER_PROBE(3 s) and startup continues without it; old-log and crash-dump cleanup waits until after the first paint. Heavyweight AI bring-up (node-llama-cpp import, GPU probing, backend selection) waits for the first paint (src/main/core/firstPaintGate.js, capped atTIMEOUTS.FIRST_PAINT_GATE, 5.1 s) and then runs behind the splash screen. A long hidden phase on the current build therefore points at the main thread being blocked (slow disk, antivirus, a hung GPU process) rather than at the AI engine, and the log tells the two apart. - A previous instance still shutting down. A launch that arrives while the previous instance is shutting down (for example right after Quit from the tray) exits on the single-instance lock before it can write a log. The instance that is shutting down records the request and starts the app again once its own shutdown has finished, so the window appears only after that. Expect an idle app to finish shutting down within a few seconds; with analysis running or a large search index to save, expect up to about a minute. When a downloaded update is installed on that quit, the update takes priority and the app does not start again by itself; start it by hand once the installer has finished.
Triage from the log (no developer tools needed). Each launch that gets as far as starting the
app writes one JSON-lines file. Every line carries time (UTC), level and msg, plus the extra
fields named below. Lines logged before the log file opens (for example the single-instance lock
result and the GPU fallback decision at module load) are not in the file.
-
Note the wall-clock time of the double-click. Press Windows key + R, type
%APPDATA%\StratoSort Stack\logs, press Enter, switch to Details view and sort by Date modified. Open the neweststratosort-YYYY-MM-DDTHH-MM-SS-mmmZ.login Notepad. The timestamp in the file name is UTC and is taken when the app process opens its log, so the gap between the double-click and that timestamp (gap A) is everything that happened before the app could log: Windows Security scanning the exe and its files, SmartScreen, and, when the app relaunched itself after a shutdown, the rest of that shutdown. A launch that produced no new file at all means the process quit before it could log: normally a second instance that handed over to one already running (which brings its window forward), or one that arrived during a shutdown (cause 3, which should then produce a new file once the shutdown ends). -
Search (Ctrl+F) for these messages in order and note the
timeof each, or "not found":[LOGGING] File logging enabledwithlogFilePathanduptimeS.uptimeSis how many seconds the process had already been alive when it opened the log (module load, single-instance lock, app ready). The file name is stamped at that same moment, so this time is already part of gap A; a value above a few seconds means most of gap A was spent inside the app process rather than in antivirus scanning before it.[perf]withnamestartup:main:time-to-app-readyanddurationMs(the same phase in milliseconds, counted from the moment the main bundle was evaluated).[STORAGE] Documents folder resolved for UncategorizedwithdocumentsPath(once per launch; where the app expects theUncategorizedfolder), then[STARTUP] Loaded custom folders:. On a first launch[STARTUP] No saved custom folders found, creating Uncategorized fallbackcomes between the two.[STARTUP] Creating window before heavyweight service startupwithuptimeS, followed by[perf]withnamestartup:main:time-to-first-window.[AppProtocol] servedwithasset(index.html, thenstyles.css) andms. Both files are tiny and are served on the main-process thread.[WINDOW] did-finish-load fired.StratoSort window ready and focusedwithuptimeS. This is the moment the window is on screen through the normal path.[WINDOW] GPU status after first showwithshownVia(ready-to-showorfallback),featureStatusanddevices.[STARTUP] First-paint gate releasedwithreason(shown,timeoutorno-window) anduptimeS. Heavyweight startup, the old-log and crash-dump cleanup, and (1 s later) the semantic search warm-up begin right after this line. Earlier builds could also logdid-finish-load, which released the gate before the window was shown.[STARTUP] Phase 1: Starting AI services..., then[LlamaService] Initializing..., then[LlamaService] System GPU detectedwithtypeandname.[LlamaService] Llama backend candidates ordered by cached selectionwithcachedBackend,candidates,prioritizedandchanged, present only whengpu-backend-cache.jsonholds a record that matches this machine (see gap D). Then[LlamaService] Llama backend candidates filtered by node-llama-cpp supportwithsupported,candidates,filteredandchanged.[LlamaService] Llama backend init failedwithbackend,durationMsanderror(count these; each one is a failed attempt), then[LlamaService] Llama backend selected(withrequestedandactual) or[LlamaService] Falling back to CPU backend, both withdurationMsand anattemptedlist that carriesdurationMsfor every candidate tried.[LlamaService] Cleared cached Llama backend after it failedwithbackendfollows a failed attempt of the remembered backend, and[LlamaService] Saved Llama backend selection for the next launchwithbackendandpreviousfollows a selection that differs from the saved record.[STARTUP] Coordinated startup completed successfully, or[STARTUP] Coordinated startup failed:followed by[STARTUP] Continuing startup in degraded mode. A startup that takes longer thanTIMEOUTS.COORDINATED_STARTUP_SOFT(45 s) logs[STARTUP] Coordinated startup still running after soft timeout; continuing(warn, withsoftTimeoutMsandhardCapMs) and keeps going; it then ends with[STARTUP] Coordinated startup completed after the soft timeout, or with[STARTUP] Coordinated startup failed after timeout. One that reachesTIMEOUTS.COORDINATED_STARTUP_HARD_CAP(180 s) logs[STARTUP] Coordinated startup hit its hard cap; aborting(error) first.
Also search for these warning and error lines, which are normally absent:
[WINDOW] ready-to-show not received within budget; showing window anyway(warn, withbudgetMsanduptimeS): the renderer had not painted within about 4 s and the window was force-shown as an empty themed frame. The time from here to[WINDOW] did-finish-load firedis how long it stayed blank.[WINDOW] Window creation timeout, releasing mutexfollowed by[WINDOW] Force-showing window after creation timeout(both warn): the window was still hidden after 60 s.[STORAGE] Uncategorized folder check is slow; keeping the saved path,[STORAGE] Recreating the Uncategorized folder is slow; keeping the saved pathand[STORAGE] Creating the Uncategorized folder is slow; continuing without it(warn, withpathandtimeoutMs): one operation on the Documents folder took longer than 3 s and startup went on without waiting for it. Ask whether Documents is redirected to OneDrive or a network share. The folder path is kept either way, the operation usually finishes in the background, and organizing creates a missing folder on the first move into it.[STORAGE] Could not create the Uncategorized folder(warn, withpath,codeanderror): Documents refused the folder. AcodeofEACCESorEPERMusually means Windows Security's Controlled folder access. The folder keeps its Documents path, files that match no smart folder cannot be moved there until it can be created, and the app shows a warning naming the folder. Every launch tries again and logs this line again while it still fails.[GPU] Process exited(error; count them) and[GPU] Repeated GPU failures detected(two variants, warn and error): the graphics driver or GPU process is failing.[GPU] GPU process exited before the window was shown; showing it now(warn, withreasonanduptimeS) means the window was shown early because of such an exit; expect it to stay blank until the renderer paints.- A file named
.gpu-fallbackin%APPDATA%\StratoSort Stackis written after the third GPU process exit in one session, each exit within an hour of the one before (an hour with no exit restarts the count). While it is less than 3 days old (counted from when it was last written), every launch renders in software: drawing is slower but avoids the failing driver, and the AI engine is not affected. A software-rendered session never deletes the file. Once it is older than that, launches use hardware acceleration again, and the first one whose window is visible 30 s after it was created, with no GPU process exit in that time, deletes it; three more such exits write it again and restart the 3 days. To retry hardware acceleration sooner, quit the app and delete the file. Earlier builds deleted it at the next launch, so a failing driver produced alternating slow and fast launches. When the file exists, one of these lines appears about 30 s after[STARTUP] Creating window before heavyweight service startup:[GPU] Software rendering fallback still active(info, withflagAgeHandretryHardwareInH),[GPU] Keeping the GPU fallback flag: the GPU process exited this session(warn, withgpuExitsThisSession),[GPU] Keeping the GPU fallback flag until a run with a visible window(info), or[GPU] Hardware acceleration ran stably; GPU fallback flag cleared(info). [LlamaService] Llama backend attempt exceeded slow threshold(warn, withbackend,durationMsandthresholdMs): one backend attempt took longer than 10 s.[LlamaService] [node-llama-cpp](warn): node-llama-cpp's own console output, forwarded into the log while a backend is being tried. A line containingis not compatible with the current systemandfalling back to usingmeans a prebuilt GPU binary was rejected on this PC.
In PowerShell this does all of step 2 at once (one line; paste it as is):
$log = Get-ChildItem "$env:APPDATA\StratoSort Stack\logs\stratosort-*.log" | Sort-Object LastWriteTime -Descending | Select-Object -First 1; Select-String -Path $log.FullName -Pattern 'File logging enabled','\[perf\]','Loaded custom folders','Uncategorized','Creating window before heavyweight','AppProtocol\] served','did-finish-load fired','ready-to-show not received','Window creation timeout','Force-showing window','window ready and focused','GPU status after first show','First-paint gate released','Phase 1: Starting AI services','LlamaService\] Initializing','System GPU detected','Llama backend','node-llama-cpp','\[GPU\]','Coordinated startup','degraded mode','SHUTDOWN\] Relaunch','Not relaunching','Cleanup completed in','SECOND-INSTANCE\] Launch arrived' | ForEach-Object { try { $o = $_.Line | ConvertFrom-Json; $extra = foreach ($k in 'uptimeS','reason','asset','ms','name','durationMs','backend','requested','actual','cachedBackend','previous','changed','shownVia','budgetMs','documentsPath','path','timeoutMs','code','flagAgeH','gpuExitsThisSession','waitedMs') { if ($null -ne $o.$k) { '{0}={1}' -f $k, $o.$k } }; '{0} {1,-5} {2} {3}' -f $o.time, $o.level, $o.msg, ($extra -join ' ') } catch { $_.Line } }To run it on the launch before (for example the one that was shutting down when the slow launch was clicked), change
-First 1to-Skip 1 -First 1. -
What the gaps mean:
-
Gap A (double-click to the file-name time): everything that happened before the app could log.
uptimeSon[LOGGING] File logging enabledis the in-process share of it, so gap A minusuptimeSis what happened before the app process existed: Windows Security scanning the exe and its files, SmartScreen, or the end of a previous instance's shutdown. Expect it to be large on the installed build or a freshly extracted zip only on the first launch after installing or extracting, or while SmartScreen checks the file, and a few seconds otherwise. When the log of the launch before has[SHUTDOWN] Relaunching after shutdown(withreasonandwaitedMs) near its end, the click arrived during that shutdown and gap A includes the rest of it; the same file then also has[SHUTDOWN] Relaunch requested; the app will start again after shutdownand[SECOND-INSTANCE] Launch arrived during shutdown; relaunching after exitat the time of the click, and[SHUTDOWN] Cleanup completed ingives the cleanup time.[SHUTDOWN] Not relaunching: a downloaded update installs on this quit(warn) in its place means the update installer ran instead and the app had to be started by hand. -
Gap B (
[LOGGING] File logging enabledto[STARTUP] Creating window before heavyweight service startup): pre-window housekeeping (crash-journal recovery, loading the folder list, checking or creatingDocuments\Uncategorized, settings). Expect well under 5 s. EachUncategorizedfolder operation is capped at 3 s, so a slow Documents folder shows up as one of the[STORAGE]slow-folder warnings above rather than as a long gap. The difference between the two[perf]durationMsvalues (time-to-first-windowminustime-to-app-ready) is this phase in milliseconds, counted from app ready instead of from the first log line. -
Gap C (
[STARTUP] Creating window before heavyweight service startuptoStratoSort window ready and focused, or to theready-to-show not received within budgetwarning): the hidden-window phase, and the one that matters most. On the current build it is expected to stay well under the 4 s fallback.[AppProtocol] servedwithmsin the thousands forindex.htmlorstyles.cssmeans the main thread was starved; something synchronous was running and the renderer was not the problem.featureStatusvalues containingsoftwareon[WINDOW] GPU status after first show, or any[GPU] Process exitedline, point at the graphics driver. Any[LlamaService]line whose time falls inside gap C means AI bring-up ran before the first paint, which the first-paint gate is meant to prevent; report it together with thereasonon[STARTUP] First-paint gate released. -
Gap D (
[LlamaService] Initializing...to[LlamaService] Llama backend selectedor[LlamaService] Falling back to CPU backend): AI bring-up, which is the GPU backend ladder. Each[LlamaService] Llama backend init failedline is one candidate that was test-loaded and rejected, and itsdurationMsis what it cost; theattemptedlist on the final line repeats those numbers for every candidate. Expect a handful of seconds. A failure withbackendcudaand anerrornamingNoBinaryFoundError, or a forwarded[node-llama-cpp]line sayingis not compatible with the current system, means a CUDA binary was tried that this PC cannot run. This phase happens behind the visible splash, so it lengthens the time until the app is usable, not the time until the window appears.The app remembers the GPU backend the ladder settled on in
%APPDATA%\StratoSort Stack\gpu-backend-cache.jsonand tries that backend first on later launches, so on a machine whose setup has not changed expect no[LlamaService] Llama backend init failedlines once the record exists. On Windows node-llama-cpp still test-loads the chosen binary in a child process, so the record saves the cost of candidates that fail, not of the one that works. The record is not used on the very first launch (there is none yet), after an app update, when the detected GPU name, type or driver version changes, when the GPU backends node-llama-cpp finds runtimes for change (for example after a CUDA toolkit is installed), or once it is 14 days old; the full ladder then runs and a GPU result is saved again. WhileSTRATOSORT_LLM_GPU_BACKEND,STRATOSORT_FORCE_SOFTWARE_GPU,ELECTRON_FORCE_SOFTWAREor--safe-modechooses the backend, the record is neither read nor changed. A CPU result is never saved. Deleting the file while the app is closed makes the next launch run the full ladder. Why a record was not used is logged as[LlamaBackendCache] Ignoring cached backend recordwithreason(missing,unreadable,corrupt,invalid,fingerprint-mismatch,supported-backends-changedorexpired) at debug level, which packaged builds do not write by default.
-
-
Several
StratoSort Stack.exeprocesses are normal. In Task Manager, Details tab, add the Command line column (right-click a column header, Select columns). During a launch expect: oneStratoSort Stack.exewithout--type, one with--type=gpu-process, one--type=renderer, one or two--type=utility, one--type=crashpad-handler, and for the first few seconds of AI bring-up short-livedStratoSort Stack.exerows with--type=utility(node-llama-cpp testing a GPU binary in a child process) alongsidepowershell.exe,wmic.exeornvidia-smi.exe(GPU detection; their console windows are hidden). Five to eight entries is the expected picture. Worth reporting: aStratoSortStack-X.X.X-win-x64.exerow (the self-extracting portable from v5.0.0 or earlier, still unpacking), aStratoSort Stack.exewithout--typethat was already there before the click (a previous instance still shutting down; see cause 3), orAntimalware Service Executableholding most of the CPU or disk. -
Control runs. If the installed app is slow every time, close it, wait a minute, and launch it from PowerShell twice, once with each variable. Both settings last only for that PowerShell window, and both make the app ignore
gpu-backend-cache.jsonfor that run. Compare the time until the window appears and the time until the splash finishes.$env:STRATOSORT_FORCE_SOFTWARE_GPU = '1'; & "$env:LOCALAPPDATA\Programs\StratoSort Stack\StratoSort Stack.exe"
$env:STRATOSORT_LLM_GPU_BACKEND = 'cpu'; & "$env:LOCALAPPDATA\Programs\StratoSort Stack\StratoSort Stack.exe"
The first variable turns on software rendering and also runs the AI engine on the CPU; the second runs only the AI engine on the CPU. If the first run shows the window clearly sooner than the second, it is the graphics driver; see GPU Configuration in
CONFIG.md. If both runs finish the splash much sooner than a normal launch, it is the AI GPU backend ladder; theSTRATOSORT_LLM_GPU_BACKENDrow in CONFIG.md lists the accepted values (an explicit value also bypasses node-llama-cpp's supported-backend filter). The probe that node-llama-cpp runs when its GPU addons load is described under Electron quits at startup in a headless VM or container later in this guide. For a copy extracted from the zip, replace the path with theStratoSort Stack.exein the folder it was extracted to. -
What to send. Zip the whole
logsfolder (right-click, Send to, Compressed folder) and attach it with: which file you launched (installer shortcut, a folder extracted from the zip and its path, or an old portable exe) and whether you re-ran the installer or re-extracted the zip before timing, the gap A to D numbers, the Task Manager observations, your graphics card name (Task Manager, Performance, GPU) and whether the system drive is an HDD or an SSD.
Cause. electron-builder.json is missing one of the required fuses, OR the packaged binary's
actual fuse bits don't match the declaration.
Fix. Run npm run verify:electron-fuses-config for the config-side complaint, or
npx @electron/fuses read --app <path-to-built-binary> for the binary side.
Known issue. Packaged macOS builds intentionally skip Electron's single-instance lock on macOS
13.x and older to avoid a launch-time crash. Documented in RELEASING.md § "Older
macOS startup workaround". Tradeoff: duplicate launches allowed instead of focus-existing.
Cause. You added a channel to src/shared/constants.js but didn't regenerate the preload's
allowlist.
Fix. npm run generate:channels:update. Commit the regenerated file. CI's
generate:channels:check will fail otherwise.
Cause. New input-accepting handler without a Zod schema.
Fix. Add a schema to src/main/ipc/validationSchemas.js. Re-run
npm run verify:ipc-handler-schemas until it's silent. Zero-arg window-chrome channels can go in
SCHEMA_OPTIONAL_CHANNELS instead, but only if they really take no input.
Cause. Default 200 req/s per channel. Stress tests trip this.
Fix. Don't disable the limiter. Either chunk the work, or call from a single batch endpoint that
does the loop inside main. If you genuinely need a higher limit, the cap is
PERF_LIMITS.MAX_IPC_REQUESTS_PER_SECOND (200) in src/shared/performanceConstants.js, enforced by
src/preload/ipcRateLimiter.js.
Cause. Returning a huge object (e.g. all embeddings) from one IPC call.
Fix. Page or stream. For embeddings specifically, return a handle/cursor and let the renderer
pull pages, or use a push event for streaming chunks (see chatStreamChunkSchema in
src/shared/ipcEventSchemas.js).
Cause. ModelMemoryManager detected VRAM exhaustion. DegradationManager paused GPU-heavy ops
and downgraded to CPU-only.
Fix. Close other GPU consumers. Or restart the app to clear the degraded flag (also dismissible
via the system menu — that path uses the concurrency-limited system:dismiss-degraded-flag
channel).
Cause. The search index (OramaVectorService) or the analysis history could not save because
the disk is full (ENOSPC, EDQUOT or SQLite's SQLITE_FULL, see isDiskFullError() in
src/shared/errorClassifier.js). Each store holds the storage.full flag in DegradedStateTracker
under its own source (vector-store, analysis-history), and the banner names every store still
holding it. While the flag is up, the smart-folder watcher holds its queue and the Downloads watcher
holds new downloads, each checking again once a minute; the watcher status line reads "paused, disk
full · N files waiting".
Fix. Free disk space. The search index keeps retrying its save once a minute, and each store releases its hold on its next successful save; the flag clears when no store holds it, and held work resumes on its own. Dismissing the banner only hides it; it does not lift the hold. Held downloads live in memory, so quitting while the disk is full drops them (the smart-folder watcher's queue is durable).
Cause. @fugood/whisper.node 1.0.18+ requires an ArrayBuffer (not Buffer) for PCM input.
Fix. Use pcmToArrayBuffer(pcm) in WhisperService rather than passing a Buffer directly. The
helper avoids Buffer-pool aliasing by slicing into a fresh ArrayBuffer.
Cause. Embedding model changed but the persisted vector DB is from a previous model with a different embedding dimension.
Fix. Rebuild the vectors with the current model: Settings → AI Configuration (Advanced mode) →
Embeddings maintenance → Rebuild all embeddings (keeps analysis; re-embeds everything). As a
last resort, quit the app and delete the vector DB directory (userData/vector-db/ by default,
including its *.sidecar.json files), then rebuild.
Cause. Embeddings normally run in the main process (the default). Common stall causes: the
embedding model failed to load, or the queue is under backpressure. The optional
STRATOSORT_ENABLE_EMBEDDING_WORKER=true worker mode (off by default) can also stall if its worker
thread crashes.
Fix. Check the env knobs in CONFIG.md.
STRATOSORT_ANALYSIS_EMBEDDING_QUEUE_WAIT and STRATOSORT_ORGANIZE_EMBEDDING_QUEUE_WAIT are
boolean strings (default off); set them to true only to restore the old per-file/saturated-queue
waits.
Cause. node-llama-cpp ships prebuilt Vulkan and CUDA addons that probe the GPU driver when
they load. In a VM or container without GPU drivers that probe crashes the child process, and
ErrorHandler treats the crash as critical and calls app.quit().
Fix. Rename the GPU-specific addons so node-llama-cpp falls back to its CPU-only binary, then
launch with software rendering:
mv node_modules/@node-llama-cpp/linux-x64-vulkan/bins/linux-x64-vulkan/llama-addon.node \
node_modules/@node-llama-cpp/linux-x64-vulkan/bins/linux-x64-vulkan/llama-addon.node.bak
mv node_modules/@node-llama-cpp/linux-x64-cuda/bins/linux-x64-cuda/llama-addon.node \
node_modules/@node-llama-cpp/linux-x64-cuda/bins/linux-x64-cuda/llama-addon.node.bak
NODE_ENV=development STRATOSORT_FORCE_SOFTWARE_GPU=1 \
electron . --enable-logging --no-sandbox --disable-gpuInference then runs on the CPU-only @node-llama-cpp/linux-x64 addon (slow but functional).
node scripts/restore-gpu-binaries.js puts the GPU addons back. Two related notes for such hosts:
large text models (the default 3B model included) can hit SIGILL inside Electron's runtime on some
virtualized CPUs, so prefer a model under roughly 500 MB there; and models must sit in the userData
models directory (~/.config/StratoSort Stack/models/ on Linux, with the space), which is where
LlamaService looks, not the lowercase legacy path.
Turn on Settings → Diagnostics → Show live activity (Advanced mode) or press Ctrl/Cmd+Shift+L
(any mode). The Raw tab shows every record the main-process logger writes at the current level,
already sanitized (debug lines only appear when the level is debug, as in npm run dev). The
Activity tab is a plain-language view built by src/main/services/liveLogActivity.js. When a
source log message changes, update its rule there and its row in
test/main/services/liveLogActivity.test.js, or the event only shows in Raw.
Three log lines feed that view and are written at info in every build:
[OramaVectorService] Persisted databaseswhen a search index save wrote at least one collection (a save with nothing to write stays atdebug). Saves are already spaced 5 s to 2 min apart.[FILE-OPS] Move completedand[FILE-OPS] Move skipped (duplicate), one per file in a batch organize (src/main/ipc/files/batchOrganizeHandler.js). They used to be development-only (ENABLE_BATCH_TRACE_LOGS, now removed). Theirsourceanddestinationare file names only (path.basename), never folders or file content: POSIX path redaction follows folder names with spaces only under the well-known roots or in a top-level folder (see below), so a full path elsewhere could still leak a folder such asMedical Records.
The feed (src/main/services/liveLogFeed.js) listens to the logger only while a window is
subscribed and ignores records logged while it is sending a batch, so a failing send cannot feed
itself. The panel's position, size, minimized state and tab live in localStorage under
stratosort_live_activity_panel; delete that key in DevTools to reset the panel's layout. The panel
starts empty: the feed keeps up to 500 records only while some window is subscribed and clears them
when the last one unsubscribes (closing the panel, or a reload, which detaches the window). That
backlog only reaches a second window subscribing while another is open. Toggling showLiveActivity
takes no settings backup (BACKUP_EXEMPT_KEYS in src/main/services/SettingsService.js).
sanitizeLogData() in src/shared/logger.js reduces every absolute path in a string to
[REDACTED_PATH]<separator>name.ext, for the log file and the panel alike: drive paths written with
\, / (C:/Users/...) or JSON-escaped \\ separators, UNC paths (\\server\share\...) and
POSIX paths. That includes a second path in the same line: before, move C:\a\x.pdf to D:\b\x.pdf
left the second path raw. Windows file names keep their spaces.
A home folder on its own (C:\Users\<name>, /Users/<name>, /home/<name>) becomes a bare
[REDACTED_PATH]: its last segment is the OS account name, so it is not kept as a basename. This
also hides C:\Users\Public. A Windows path whose separator switches between \ and /
(C:\Users\jdoe/Documents/x.pdf, C:/Users/jdoe\Docs\x.pdf) is redacted as one path, so the user
folder in front of the switch is no longer left raw. Object keys that contain a separator or a
control character go through the same rules as values, and a key that reduces to the same text as an
earlier one gets a #2 (then #3, ...) suffix, so both values are kept.
A POSIX path keeps spaces inside its folder names only when it starts at a well-known root
(/Users, /home, /Volumes, /private, /var, /tmp, /mnt, /media, /run/media,
/run/user, /opt, /Library, /Applications, /System, /Network, /root, /srv, /net) or
at ~/, so /Users/me/My Drive/passport.pdf is written as [REDACTED_PATH]/passport.pdf, and
'/Users/a/x.pdf' -> '/Users/a/Finance Docs/x.pdf' as two separate tokens. The macOS roots also
match in lower case (/users, /volumes, /library, /applications, /system, /network),
because the app's file ids lower-case the path on darwin (normalizePathForIndex), and a rooted
path may follow :, so the id file:/users/jane/mobile documents/scan.pdf is written as
file:[REDACTED_PATH]/scan.pdf. Words in a folder name are joined by a space, a no-break space
(U+00A0) or a narrow no-break space (U+202F). Free text cannot say where a path ends, so the rest is
a compromise:
- A POSIX path under any other root is fully redacted when its top-level folder has a space
(
/Shared Drives/Team X/x.pdfbecomes[REDACTED_PATH]/x.pdf). Otherwise it, and any path glued to a word (as in a URL), is still cut at its first whitespace:/data/My Files/x.pdfbecomes[REDACTED_PATH]/My Files/x.pdf. - The file name is captured only up to its first whitespace; the rest stays as plain text
(
[REDACTED_PATH]/2024 return.pdf). - A folder name with two spaces in a row, or a word after a space that contains
",\,:,;,=,<,>,|,*,?or a backtick, or is only opening punctuation, ends the folder early, which can leave the rest of the path visible. These rules keep two paths in one line apart. ,is allowed inside a folder name (Smith, John); a second path after,still splits.- A word that looks like a file name (
.+ a letter + up to 7 letters or digits:x.pdf,scan.JPG; notv1.2or1.2.3, and not the web endings.com,.org,.net,.io,.edu,.gov, soAmazon.com Ordersstays one folder) followed by a space ends the path at that word, soMoved /Users/a/x.pdf to Finance/TaxesbecomesMoved [REDACTED_PATH]/x.pdf to Finance/Taxes. The cost: a folder name with such a word before a space ends protection there (/Users/a/notes.txt and more/x.pdfbecomes[REDACTED_PATH]/notes.txt and more/x.pdf). A relative path after a path whose last word does not look like a file name is still read as part of it and hidden. That includes a3/12-style count right after a path that ends at a folder:Scanned /Users/a/My Docs 3/12becomesScanned [REDACTED_PATH]/12. - JSON text keeps its shape: a
"that closes a string ends the path.JSON.stringifydoes not escape/, so\/-escaped paths are not handled.file://URLs keep their scheme, encoded (%20) or not.
The comment above POSIX_PATH_PATTERN in src/shared/logger.js holds the exact rules.
With STRATOSORT_REDACT_PATHS=1 (npm run dev:demo) the panel also replaces those names with "a
file" (redactActivityText / redactRawText in
src/renderer/components/diagnostics/liveActivityFormat.js). That pass is a heuristic with known
gaps: it also hides some code-like names and domains (simple-main.js, example.com); it can leave
the part of a file name before its last space visible; a name inside a web URL, or one ending in a
host-like extension (.com, .co, .io), can still show; and the context column is never
redacted.
Cause. The system:live-log:subscribe invoke failed or timed out: a preload built before the
bridge existed, or the handler in src/main/ipc/system.js was not registered. Subscribe and
unsubscribe time out after 5 s (src/shared/ipcInvokeTimeout.js) instead of the 330 s default,
because a new subscription waits for the previous unsubscribe to settle.
Fix. Run npm run generate:channels:check and npm run verify:ipc-handlers, then restart
npm run dev so preload and main are rebuilt together.
The feed sends at most 200 entries (and 256,000 characters of text) every 250 ms. During a burst the oldest entries of that window are left out of the panel, never out of the log file; a batch the window failed to receive is counted the same way. Use Open folder for the full log.
Known case. test/unit/pathHandling.test.js is flaky in the full suite (pre-existing
test-ordering issue). If it's a different test, you've likely got shared-state pollution.
Fix. Look for module-level mutation, singleton initialization, or stubs that don't get cleaned
in afterEach. Reset the module registry between tests if you must (jest.resetModules()), but
treat it as a code smell to investigate.
Cause. The filter that mutes these in tests lives in test/test-globals.js, not
test-setup.js. If your test config doesn't include test-globals, warnings leak.
Fix. Check the Jest project config you're running. The main test/jest.config.js includes
globals; the perf/stress/integration configs may not.
Cause. Open handle (unclosed timer, listener, server, db).
Fix. npm test already passes --detectOpenHandles. Read the output; it points at the culprit.
Add cleanup in afterEach or afterAll.
Cause. Lint-staged runs prettier + eslint on staged files. If you git add a file that fails
one of them, the hook reverts your stash and fails the commit.
Fix. Check the actual error in the output. Run npm run format and npm run lint:fix to
auto-fix what's auto-fixable, then re-stage and re-commit. Don't use --no-verify.
Cause. Tests wrote to a path that isn't gitignored.
Fix. Either gitignore the path (if it's truly temp) or fix the test to clean up. Don't commit the noise.
- Check the issue isn't already in
CHANGELOG.md"Unreleased" as a known broken thing. - Check
CLAUDE.md"Resolved Gaps" — if your symptom matches a fixed gap, you might be on an old branch. git log --oneline -20to see what landed recently.- Open an issue with logs from
%APPDATA%\StratoSort Stack\logs\(Windows),~/Library/Application Support/StratoSort Stack/logs/(macOS) or~/.config/StratoSort Stack/logs/(Linux).