# Changelog ## v2.62 (2026-11-06) The Gate world chooser now wraps into readable rows with large world lists, fixing collapsed names on desktop. This layout fix only needs a container update and page reload. See [release notes](docs/release-notes-2.62.md) for upgrade steps and validation limits. This release adds public Remote Access through Tailscale Funnel or Cloudflare, independent login/player themes, a dedicated Server Settings page, personal mod configuration with Client 2.0.18, and Linux overlay controls. Companion opens its dialog only after clicking CONNECT. World updates accept empty mod selections and report failures correctly; catalogue syncs recover interrupted runs without trusting reused process IDs. Pull/recreate the container, update modded worlds, and relaunch Valheim to receive the Companion fix. Hugin's Vibes turns default to 300 tool rounds and 60 minutes (was 100 and 15), and accept up to 10,000 rounds and 24 hours. A saved limit equal to an earlier default or preset moves to the new default; a limit the operator entered is kept. Send no longer stays disabled, with the job indicator spinning, after a turn ends: the page had locked the composer from a state poll taken while the turn was still running. Long Vibes conversations no longer open slowly or go blank. Replaying a session read a scroll position after every event, forcing a full layout each time (2,935 layouts and 4.6 of 5.7 seconds for a 3,845-event session); the pane was also emptied before the transcript was requested, and the whole conversation was fetched and rebuilt after every turn, build, package and publish. History is now replayed without measuring, swapped in one step, and left in place when a turn or job ends. A Vibe's card in the library kept its spinning ring and "turn…" after the turn had ended, until another job finished or the page was reloaded: the project list was fetched when a turn started and never again. The cards now follow the project's own answer and every state poll. Hugin Setup fetches the current model list from the configured endpoint, with a Refresh action and the time of the last successful fetch, instead of reusing a cached list for six hours; a failed refresh keeps the saved selection. Each provider has Limits for context and response size, compaction, timeouts, concurrent requests and queueing, enforced for both Hugin chat and Hugin's Vibes. Docker `:2.62` and `:latest` carry this release. Docker Scout lists one HIGH finding in the bundled Tailscale 1.104.5 binaries (CVE-2026-116591, a zstd decoder panic in `klauspost/compress` 1.20.0); no Tailscale release carries the fix yet. It is assessed as not reachable by an adversary in this image, because Tailscale decodes zstd only from its own coordination server and from assets built into the binary. See `docs/security/REMOTE-ACCESS-SCANNER.md`; this is a reachability assessment, not a patched library. ## v2.61 (2026-11-03) Security release for the player portal (port 8080); see `docs/RELEASE-NOTES-2.61.md`. Reported by a community member on Discord. The Steam sign-in callback is now verified with Steam (OpenID `check_authentication`) before a session is created. Until now the portal took the Steam ID straight out of the callback URL, so anyone could sign in as any player and see that player's accessible worlds, any operator-published password, and their Steam profile name. Valheim's own access list still gated joining the game; this was information disclosure, not game access. The unused `steamID` query fallback in `api.php?mode=getMyWorldsStatus` is removed (it served any player's world list and launch links with no session at all). The `/stateful/` download location serves only `/.zip` and `/-config.zip` instead of the whole `/opt/stateful/games` tree, which exposed access lists, save files and configs to anyone who knew a path. Every query on the public side binds its parameters; world names in API requests are allowlisted; Steam persona names and world names are escaped before display; the public server block sends `X-Content-Type-Options`, `X-Frame-Options` and `Referrer-Policy`; `server_tokens` is off; the session cookie is `Secure` when the request arrived over TLS; the login page serves its local jQuery 3.6.0 instead of jQuery 2.1.3 from a CDN. No client or Companion change: the two payload URLs the client requests are byte-for-byte unchanged, and neither the client nor the Companion uses the Steam session. ## v2.60 (2026-11-02) Optional `PHVALHEIM_GAME_PORT_START` and `PHVALHEIM_GAME_PORT_END` make the container the source of the game UDP range. Setup and Server Settings show the managed range; new worlds reserve complete port pairs within it and report exhaustion. Existing worlds outside the range are flagged without renumbering. Saved Base Port and legacy Docker/Unraid behavior remain in effect when the variables are unset. No Unraid template change is required. Vibes now separates Tool rounds, Turn time, and Model response limits. Hosted and local model requests (including compaction and compatibility retries) obey the remaining turn budget; Stop interrupts silent model requests. Interrupted responses never run partial tool calls. Stopped turns explain their limit and how to continue from saved files, and do not start an automatic build or commit. New defaults allow 100 rounds with 15-minute turn and response limits; saved choices are preserved. A Turn limits shortcut, minute-based fields, and editable presets simplify setup. Running tools keep their own bounded timeouts; turn time is checked between tools. Per-mod config delivery is independent of installation: Server defaults on and Client off, including upgraded worlds. Existing operator settings remain saved. Untouched settings default to Overridable; player values survive full mod and config-only updates with Client 2.0.17. Editing a value clears Overridable and saving a shared setting enables Config Client. Operators can recheck Overridable to supply a suggested default. Server-only edits and resets do not enable Client. Clearing Overridable reapplies that value before each launch. Server-only entries never enter the client policy. Bulk controls, tooltips, and client-generated config import support the operator workflow. Imports discover editable settings without publishing personal values. Client 2.0.17 is required for worlds rebuilt with the new policy; older launchers are blocked before their destructive extraction. Some older clients report the rejection as world not found. Install the matching client before testing. New client installs are staged and roll back on failure. Config-only downloads carry the same policy as the full mod archive. ## v2.59 ### Database Browser saves (#92) Editing a trophy or another field no longer fails because an unrelated nullable timestamp was submitted as an empty string. The browser reads the table schema and saves blank nullable date, numeric and JSON fields as SQL NULL. Numeric zero, empty text and populated dates remain valid; invalid dates and required fields still receive normal database validation. This fixes the manual-edit error, not an independently reproduced trophy-reporting failure. ### Field Guide links The dashboard Help section, player pages and Vibes workbench now link to the [PhValheim Field Guide](https://brianmiller.github.io/phvalheim-server/). Server Settings documentation and backup help also point to the new guides. On both player pages, Hugin’s icon opens [phvalheim.com](https://phvalheim.com). The guide, GitHub and Discord links use matching, aligned rounded-square buttons. ### SCM branch compatibility The first Push to GitHub or GitLab preserves the project's current branch and pushes its tags. Imported repositories using `master` or another branch previously failed because this action assumed `main`. Fetch, fast-forward Pull and Push branch retain their divergence protections. ### Catalogue filter responsiveness World mod pickers now paint catalogue buttons from the saved source filter. Previously all buttons looked enabled, even when the world had excluded a catalogue, so the first click could look ineffective. Source toggles now filter cached DataTables rows instead of rebuilding every mod row, preserve the operator's search and sorting, show the actual pressed state and announce which catalogues are visible. Selected mods remain visible. Both Edit World and New World use the fix; the last-source guard explains how to enable another catalogue before hiding it. ### Connection recovery and workbench improvements - Companion 1.0.6 polls a read-only backend endpoint while at the menu. Launch links carry a world-scoped, expiring capability; refresh never returns a password. Late crossplay codes, server mode and port changes update the dialog without restarting the game. Retry and expiry feedback is visible. A world update and client sync are required to receive the new DLL. - The sidebar uses the same Hugin as Ask Hugin. Vibes, Forge and Notes can be collapsed; preferences persist. The searchable model picker accepts arbitrary local-provider model IDs and updates the model pill. Phone layouts have scrollable tabs and reachable controls. - Chat preserves scroll-back with a Latest activity button, shows expandable tool calls and results, and animates Hugin during work. It reports estimated context with output headroom, provider token totals and compaction events. Reasoning activity is indicated when the adapter receives it; private reasoning text is not exposed. Unreported usage is labelled as unknown. - Compaction now checks between tool rounds, counts tool arguments, bounds summarization requests, preserves the latest request and removes whole tool call/result groups. Failed summarization retains labelled excerpts. The harness supports the shared self-hosted and frontier provider adapters; Anthropic streamed input/output usage is merged correctly. - Package has persistent progress/results and ZIP downloads under Disk. Thunderstore and Hexium accept the same package layout. Local publishing toggles to Unpublish for the current version. Direct hosted publishing uses separate masked tokens, teams and categories, chunk progress, failure cleanup and a recorded link to the published version. It never retries publication automatically after an ambiguous response. A real credentialed upload remains an operator test. - + Import clones GitHub or the configured GitLab host, including private repositories using the matching token. Imported code is not automatically built. History exposes the branch, changed files, remotes, ahead/behind and last remote check; Fetch, fast-forward Pull and ordinary Push operate on the current branch. Tokens are not stored in repository configuration and hooks are disabled. Existing upstream plugin GUIDs must be preserved. ### New: Hugin's Vibes A workbench for making your own Valheim mods, first under **Tools** in the admin sidebar. The operator describes a mod in plain language; Hugin writes the C#, compiles it inside the container, reads the compiler's diagnostics and fixes them, keeps every mod (a *Vibe*) in its own git repository with a remembered conversation and notes, and publishes versions to a **Hugin's Vibes** catalogue that sits beside Thunderstore and Hexium in every world's mod list. A published mod reaches a world through the ordinary mod list and world update; nothing in Vibes starts, stops or alters a world. How it is built, in short (the full design is `docs/HUGINS-VIBES-DESIGN.md`): - **Opt-in, separate download.** The image stays on its 2.58 CVE diet: no git, no .NET, no node. The toolchain is a **Build Pak** release asset (its own repository and release cadence) that the first-launch dialog downloads into `/opt/stateful/vibes/` on the data volume after showing its size and the free space. Nothing is downloaded, and nothing changes, if the page is never opened. - **No game files are redistributed.** Valheim's assemblies are harvested from one of the server's own worlds (`game/valheim_server_Data/Managed`) and publicized locally. - **One provider layer.** The agent loop (the "Forge loop") is built on `aiChat()` from 2.45: the same providers, keys, model-id rule and tool-capability negotiation as Hugin. pi was considered and not embedded (design section 9). - **The local catalogue reuses the 2.43 tables.** `mods.source = 'vibes'`, versions with `file://` download URLs on the data volume; the engine's install loop copies instead of fetching for that scheme (the only engine seam). `modSync.py` prunes per source and never touches it. - **Jobs, not requests.** Every long action is an `hv_jobs` row run by a detached PHP CLI process as the `phvalheim` user; the page streams its events over SSE and survives a reload. - **Deletable.** Settings → Danger zone removes the pak, with keep-switches for the mods made, the catalogue worlds use, and uploaded assets. Schema: `dbUpdate_2.59.sh` — `settings.vibesInstalled`, `vibesBuildpakVersion`, `vibesSettings` (one JSON document), `vibesNoticeShown`; tables `hv_projects`, `hv_sessions`, `hv_jobs`. Verify markers v59aa onward. ### Fixed: Hugin dropped every zero out of a streamed reply (issue #94) Reported as "`247.9hrs` was ~1 day" and screenshots of `226-1-24 13:4:2` where the log said `2026-10-24 13:40:20`. The OpenAI-compatible adapter guarded each streamed fragment with `!empty($delta['content'])`, and PHP's `empty("0")` is true, so a chunk that was exactly the single character `0` was dropped from the accumulated reply and from the live stream. A model that tokenises digits one at a time (the reporter's quantised Qwen over an OpenAI-compatible server) therefore lost every zero, in quoted log lines and in Hugin's own prose; models that stream longer chunks hid the bug. The guard is now `isset(...) && !== ''`. The Anthropic and Gemini adapters and the SSE relay were already strict. `dev_tools/test-stream-zero-delta.sh` plays a fake provider that streams the reply one character at a time, zeros included, and fails five ways against the old adapter (its control streams a zero-free reply through the same path). Markers v59bc/v59bd. ### Fixed: Hugin's backup tool read a directory that never existed "list all backups" answered 0 backups / 0 MB for every world while the Backups tab listed dozens; Hugin believed the tool, was contradicted, and went scraping `worldBackups.log` for ids. `get_backup_status` globbed `/opt/stateful/backups//`, which has never been the layout (archives are flat `valheimworld_-.tar*`), and never read the `backups` table the engine writes and the tab reads. It now reads that table through the tab's own reader: count, total size, newest/oldest, per-type counts, orphans, and the 25 newest with their ids. The system prompt now states that **the database is the system of record** for everything PhValheim manages and that log files are for diagnosing behaviour, never for counting PhValheim's own records. `dev_tools/test-hugin-backups-from-db.sh` plants two rows and reads them back through the real tool (the pre-fixture run is the control). Markers v59be/v59bf. ## v2.58 ### Security: the Docker Hub vulnerability list Docker Hub listed 2,408 findings against 2.57 (17 critical, 491 high, 829 medium, 1,070 low). Read package by package, 2,360 of them were in things the product never runs: - `linux-libc-dev` (2,290 findings, every critical): the kernel's userspace headers, pulled in by `libpulse-dev` on the crossplay line. Valheim's PlayFab library links four RUNTIME libraries (`libpulse.so.0`, `libpulse-simple.so.0`, `libpulse-mainloop-glib.so.0`, `libatomic.so.1`); the image now installs `libpulse0 libpulse-mainloop-glib0 libatomic1` and the build fails if any of the four stops resolving. - `software-properties-common` and its Python stack (`python3-cryptography`, PyJWT, httplib2, oauthlib, PackageKit, polkit…): installed only to run `add-apt-repository multiverse`, which is a no-op on `ubuntu:jammy` because multiverse is already enabled. Replaced by a build-time check. - A 132 MB composer tree (`google/apiclient` with guzzle, phpseclib, php-jwt) that the public pages loaded and never used. Deleted, with the two `require` lines. - The GitHub CLI (`gh`, and `git` with it) and `inetutils-ping`: nothing runs them. The build now pulls a current base image (`--pull`; the cached build had kept a months-old `ubuntu:jammy`) and runs Docker Scout on the pushed image: a critical or high finding fails the verify (`SCOUT_MAX_CH` accepts a documented count). Result on this image: **0 critical, 0 high, 34 medium, 14 low, none fixable** (Ubuntu 22.04 base packages with no fix in jammy's public pockets); 1.25 GB → 958 MB; 355 → 266 packages. Nothing operators see changes. Verify markers v58aa–v58al. The full read of the list, and the Ubuntu 24.04 option for the remaining 48, are in `docs/SECURITY-PLAN-2.58-dockerhub-cves.md`. ### Fixed: the catalogue sync bar sat at 80% for the whole of the real work A forced sync (the panel's per-catalogue link) spends 90% of its wall time rebuilding the shared dependency graph -- 40 of 45 seconds on a 290k-edge catalogue -- and the engine reported that phase once, at its start ("resolving deps", 80%), then nothing until the run finished. The bar jumped to 80 and froze; the log pane showed no line for forty seconds. `modSync.py` now carries the run's `phase_pct` in the same `mysql` invocation as each INSERT batch (80..98; `finish()` still owns 100) and logs "N of M edge(s) written" every few seconds. Measured: 16-17 distinct percentages during the phase, never backwards. Guarded by `dev_tools/test-modsync-progress.sh`, which runs a real forced Hexium sync and samples the run row. The sync is not faster yet: the button's `--force` still means a full rebuild even when nothing changed (an incremental boot sync does the same phase in 0.5s); making `--force` mean "re-fetch" rather than "rebuild everything" is a 2.59 item. Markers v58ar-v58as. ### Changed: a running world's row is no taller than a stopped one Measured on the dashboard at 1500px: a stopped modded row was 60px, a running one 82px, and a running one with an update waiting 105px, because PLAYERS and UPDATE stacked as third and fourth items under MEM and HEALTH in the Resources cell, so the table reflowed on every start and stop. A plain 2x2 regrid does not fit the 218px column (one MEM item is 146px wide). Instead the two items that are not resources moved: the player count rides in the Status pill ("Running · 3", with the same approximate-and-from-the-log title), and an available update is a badge on the Settings button -- the control whose Updates tab the operator opens next, and the one button visible in every world state (Update is hidden on a running world). Resources keeps MEM and HEALTH. A running modded row with an update waiting now measures 59px against the stopped row's 60. Three render sites agree -- the PHP online row, the JS row template, and `updateWorldRow()`, which rewrites the pill and the button on every 5-second poll (a count the PHP rendered that the poll then wiped would look right for exactly five seconds). Guarded by `dev_tools/test-admin-row-consolidation.js`: engine stopped, the fixture world set running with a count and an update, measured after a poll at three widths against a stopped modded control, then the stimulus is changed in the database and the row must follow on the next poll without a reload. Markers v58at-v58ba. ### Fixed: the update badge outlived the update, and said nothing about which mod `update_available_game` / `update_available_mods` are written by one thing: `updateChecker.py`, which cron runs every six hours and only for running worlds. A world the operator updates by hand is stopped, so its badge stayed until the world next ran and happened to be due a check. The engine's update block now runs the checker for that one world as soon as the update ends (backgrounded as the cron user, like the boot catalogue sync, so the restart is not delayed). The checker also records the stale mods by name in a new `worlds.update_mods_list` ("name installed -> available", one per line); the badge's hover text and the Updates tab show them. Found while doing this: `getWorldsData()` in `admin/index.php` never copied the player and update fields into its row literal, despite the comment above it saying they travel with the row -- the server-rendered PLAYERS/UPDATE items (and 2.58's pill count and badge) were empty on every page load until the first poll filled them in. Fixed, and `test-admin-row-consolidation.js` now reads the served HTML before any JavaScript runs. Guarded live by `dev_tools/test-update-badge-after-update.sh`: plants a named fake mod and a badge on the fixture world, runs a REAL engine update, and requires the checker to have rewritten the list from disk and the badge to be gone. Migration `dbUpdate_2.58.sh`. Markers v58bb-v58bc, v58bh-v58bj. ### Changed: the player count is REAL -- the Companion reports it, nothing is inferred "The active player count should be REAL data, not inferred from the logs" (the maintainer, 2026-10-23). The PhValheim Companion (dual-role, shipped in the image, installed on every modded world) gains `PlayerTelemetry`: on a DEDICATED SERVER only, every 5 s, it writes `ZNet.GetPlayerList()` -- the roster the server broadcasts to its peers -- to `/game/BepInEx/data/PhValheim.Companion/player_stats.json` (`player_count`, `players[]` with name and character id, `version`), atomically. `playerMonitor` reads that file for each running world: fresh (mtime within `PHV_PLAYER_STATS_MAX_AGE`, 60 s) and numeric is an observation with source `companion`; stale, missing or malformed is UNKNOWN (`player_count_at` NULL), never a confident zero. The log parser (PlayFab "now N player(s)", "Connections N" plus socket arithmetic) is deleted; the join code is still read from the log, which is the only place Valheim prints it. A vanilla world runs no BepInEx and so reports no count. The dashboard shows the count only while a world is `running` -- it had shown a stale one under an "Updating" pill. `settings.playerCountsEnabled` is RETIRED (`dropColumn` in `dbUpdate_2.58.sh`; nothing reads it; the Settings section, the API field and playerMonitor's gate are gone) -- a real count needs no switch. Companion 1.0.5 (its publicizer-trap test lists `ZNet.GetPlayerList` and `PlayerInfo.m_name` / `m_characterID`, all public in the real server assembly). Guarded live by `dev_tools/test-world-player-telemetry.sh` (really starts the fixture world, updating it first if it does not yet run the image's Companion, and requires the file, the row, the pill, and the clear on stop), `test-playerMonitor.sh` (18 cases on the file rules) and `test-player-counts-setting.sh`. Every place the UI still described the count as "read from the world log", "best-effort" or "approximate" (both pill titles, the per-world Show-players option, the Automatic Updates footnote and Quiet For tip, the Server Settings section -- which also lost its BETA badge and its stale "off by default" -- and the public card) now credits the Companion and the two-minute refresh. The row test asserts the served title; its fixture no longer plants the retired source value `log`. Markers v58bl-v58bp, v58bt, v58bz-v58ca. ### Fixed: Hugin crashed on every log-reading tool (issue #93) "Agent seems to return no data for any command that tries to read log files" -- 2.56 and 2.57. `aiConverse()` ran `strlen($result)` on every tool result, and three tools added in 2.56 (`last_operation`, `world_activity`, `server_activity`) return PHP arrays: "TypeError: strlen(): Argument #1 must be of type string, array given", and the stream died before the model saw a word. `aiRunTool()` is now a wrapper around `aiRunToolRaw()` that turns any non-string result into pretty-printed JSON at the one seam every tool passes through, so the next tool written to return an array cannot reopen it. Guarded live by `dev_tools/test-hugin-tool-results.sh`, which runs every read-only tool inside the container and requires a string back (and proves the raw function still returns an array, so the wrapper is doing the work). Marker v58cb. ### Fixed: the Logs badge never cleared The sidebar count of warnings and errors "not yet looked at" stayed up however often the Logs page was opened. The page did post its acknowledgement; `phvEventsAck()` ran `UPDATE settings SET logsSeenEventId = GREATEST(logsSeenEventId, ?)` with the id bound by PDO as a string, and MySQL's `GREATEST` compares as strings when any argument is one: `GREATEST(669, '6429')` is `'669'`. The watermark climbed while ids had three digits and then froze at 669 for good (production, 2026-10-24: watermark 669, newest event 6429). The acknowledgement is per event now (`phv_events.acked`, `dbUpdate_2.58.sh`, backfilled from the old watermark): the Logs page acks what it shows on load and whenever it is brought to the front (a background tab used to show everything and ack nothing), and the world log view acks that world's events only -- a world-scoped ack the single watermark could never express. The watermark is still written, with the id `CAST` so the comparison is numeric. `dev_tools/test-events-ack.sh` plants a three-digit watermark and a four-digit event and requires the badge to clear; its control shows MySQL's string comparison. Markers v58cc-v58ce, v58cn. ### New: a running world can be updated, through a modal with a live log The row's Update button was greyed out while a world ran, although the engine's update block has stopped, updated and restarted a running world since 2.55 (`wasRunning`). It is a door now, for a running or a stopped world, and opens a modal that says what will happen in three steps (stop: everyone is disconnected; update: Valheim and the mods, pinned mods untouched, client package rebuilt; start again), carries a warning with the Companion's live count when players are on the world, and -- on proceeding -- shows the engine's own event stream for the world (`getEvents` since the newest id at the moment of the click) until the operation record (`getOperations`) says the update closed, then watches the row until the world is running again. Closing the modal never stops anything: the command is the engine's. Delete goes through a modal too: what goes, that backups are kept, and the world's name typed back before the button works; the browser `confirm()` is gone. Guarded by `dev_tools/test-update-modal.js` (really starts the fixture world, updates it through the modal and waits for it to come back) and `test-delete-modal.js` (the name gate, and the proceed path captured without deleting anything). Markers v58cf-v58ch. ### Changed: automatic updates lose their BETA badge; vanilla worlds are told to use a schedule The badge and the red warning in both places (Server Settings and the per-world Updates tab) described the scraped count. The idle decision rests on the Companion's roster now. What remains true is that a VANILLA world runs no Companion and can never be seen as quiet: the Updates tab's Players row says so for a vanilla world (`getWorldAutoUpdateSettings()` now carries `vanilla`) and tells the operator to give it a maintenance window with "If players never leave: update anyway". The pill's tooltip now leads with "N players online" and the number carries a player glyph, so the "· 0" after "Running" says what it is. Markers v58ci-v58ck. ### Fixed: "update available: 3.5.8 -> \"3.5.8\"" A production catalogue carried `micolho/CraftFromContainers` with `latest_version` `"3.5.8"` -- quotes included, from the feed at the time -- while the installed `mod_versions` row read `3.5.8`. `updateChecker.py` compared the strings, flagged an update that did not exist, and the badge never cleared; the package was later delisted, so no sync would ever rewrite the row. `modSync.py` now strips surrounding quotes and whitespace from every version string it parses (`clean_version()`), the checker compares normalised values, and `dbUpdate_2.58.sh` repairs stored rows (`mods.latest_version`; `mod_versions.version` with `UPDATE IGNORE`, since that column is unique per mod). Markers v58bq-v58bs. ### Fixed: a no-password world's supervisor program could not start it `createSupervisorWorldConfig()` wrote `startWorld.sh $worldName $worldPassword $worldPort`, unquoted. `startWorld.sh` has read the real password from the database since 2.53 (the argument was dead) and "no password" is a supported state since 2.55, so for such a world the empty argument vanished, the port slid into its place and the script refused with "Missing arguments". Existing worlds never noticed because their program was written once, at creation, with a password; the dev volume hit it the moment the engine learned to regenerate a missing program. The program is now `startWorld.sh "name" "port"` (the password no longer lands in a file under `conf.d`), `startWorld.sh` accepts that and the legacy three-argument shape, and the engine's start block regenerates a missing program from the row instead of marking the world broken with an empty log to point at. Guarded by `dev_tools/test-startworld-args.sh`. Markers v58bw-v58by. ### Fixed: the mod-sync log pane (2.56) The per-catalogue sync log pane vanished for the whole of every sync and reappeared, complete, when the run finished: the panel's live render never emitted the pane element. Two more defects behind it: every status repaint rendered the pane empty until an un-awaited fetch returned (a blink every two seconds while a sync ran), and overlapping polls appended the same lines twice (a 53-line run rendered as 83). The pane is now emitted by both renders, re-rendered from the lines it already holds before it is polled, and polled by one request per source at a time. Measured in a real browser: 0 lines rendered during a 40-second run → tracks the API line for line. Markers v58am–v58aq. ### The container test bucket is a gate `dev_tools/run-oracles.sh --container` ran every file bare and had 34 failures that nobody owned for three releases ("same as last release" stood in for "passes"). Every one was triaged: one product bug (the pane above), nine test bugs or stale tests, 24 the harness could not drive, one inherently manual. `dev_tools/oracle-container-env.sh` now seeds the fixtures the browser tests read, passes each test the arguments its header documents, runs in-container PHP and in-image bash where they must run, boots the Hugin suites from the image under test (they had defaulted to `:rc`, validating the released image), and reports a test whose precondition the host cannot provide as UNRUNNABLE, which fails the bucket. `requires: manual` marks the one that needs a pre-2.53 checkout. Result: **68 passed, 0 failed, 0 unrunnable**, end to end, with standalone 62/62 and cross-repo 4/4 unchanged. The runner also exports `NODE_PATH` for Playwright; without it 27 browser tests had read as product failures. ## v2.57 ### Security: PHP2Shell (CVE-2026-109618, CVE-2026-109619) Every image up to 2.56 shipped `php8.1-fpm 8.1.2-1ubuntu2.26`, which carries a pre-auth remote code execution bug in PHP's multipart parser (public exploit, exploited in the wild). The flaw is in PHP itself and is reachable on the public UI before any PhValheim code runs. The image now carries Ubuntu's fixed `8.1.2-1ubuntu2.28`; the build has a late, date-keyed `apt-get upgrade` layer (the cached build had never re-run the one at the top, which is how 2.56 shipped a package that jammy-security had already fixed) and refuses to produce an image with an older interpreter; and the public server block (8080) returns 403 to any `multipart/form-data` body, because nothing on the public side ever used one. Verify markers `v57aa`-`v57ac`. See `docs/SECURITY-php2shell-2026-10-21.md`. ### A restarted crossplay world no longer flashes its previous session's join code On a restart the dashboard showed a code at once, then "code waiting", then the real code. Supervisor appends to the world log and nothing truncates it at a start, so for the seconds before Valheim's own "start.unity" line the log still ended with the old session's start and code, and the reader's "last code after the last session start" rule served that dead code. The log alone cannot tell "still on that session" from "relaunched, not reported yet"; the engine can. `getWorldJoinCode()` now reads the engine's session mark (the `log_offset` the 2.56 event log already records just before `supervisorctl start`) and, when the mark is usable, scopes the search to the bytes after it: a code there is this session's, none yet is "waiting". A mark is unusable when the log has been rotated since (`.log.1` newer than the mark, or the offset past the end of the file), and then the 2.56 history rule answers exactly as before, so a mark can never reproduce the "waiting for 35 hours" shape. `dev_tools/test-joincode-survives-rotation.php` grows five scenarios and three mutation controls (42). Markers `v57ad`, `v57ae`. ## v2.56 ### An event log that knows which world it is about Everything PhValheim did went into one shared text file as an untyped line, and the only per-world view was Valheim's own stdout. 2.56 records every action as a row in `phv_events` (source, level, world, operation, message) grouped by `phv_operations` (one per engine command, with an outcome), written from bash by `phvlog LEVEL "msg"` — which also prints the classic stdout line — with the world and operation AMBIENT via `PHV_WORLD` / `PHV_OP` exported by the main loop. Valheim's stdout stays a file; the engine records its byte offset at each start as a session event, which is what "this boot" means in the viewer. `admin/world_logs.php` shows Activity / Valheim / Both with begin/end markers per operation; `admin/logs.php` is the server-wide stream with filters and every log file on disk; Hugin gained `last_operation`, `world_activity` and `server_activity`. An operation closes with a worded summary (`phvOpSummary KIND MODE`) — the first cut closed with the world's bare final mode, so "update … stopped" read like an update that had stopped. Retention 30 days / 100k rows. Found while converting the viewers: `readLog.php` served any path the web server could read. It now accepts only names that pass `phvLogFileAllowed()` (regex plus realpath inside the log directory). ### Server Health `includes/health.php`: one list of checks, each `{id, name, state ok|warn|fail|unknown, detail, action}`, with `unknown` its own state that never reads as OK. The rules are pure functions and every input is injectable, so `dev_tools/test-server-health.php` pins them with mutation controls. Probes are real: the Steam key check is an actual API call (only the HTTP code read, cached 6 h per key), the data volume check is a real file write, and mod sync staleness allows for cron's hourly tick against the configured interval. The dashboard strip shows warn/fail only; the sidebar item lists everything. The old "Critical Configuration Missing" banner is the first of these checks, and the backup-retention warning moved off the players' page. ### The hourly catalogue sync was not running Making the dashboard's per-catalogue "sync" link an AJAX action — it was a GET that redirected, so every click reloaded the page — and then making a browser test actually click it found that the sync never started. `syncModCatalogue()` ran `modSync.py` as `phvalheim` via `su`, but its `>> modSync.log` redirect sat outside the `su`, so root created the log on every fresh install; cron's hourly sync and the forced sync, both `phvalheim`, then failed on "Permission denied" opening it before the script ever ran, silently. The redirect runs inside the `su` now, the engine chowns an existing root-owned file at boot, and the API launcher falls back to `/dev/null` rather than not running. `dev_tools/test-modsync-log-owner.sh` pins it with a fake-`su` control. ### The join code a healthy world cannot show The crossplay join code was read from the world's log on every poll; a rotation carried it away, and the dashboard said "waiting for its join code" for a world players were joining on. `worlds.join_code` remembers it (written by `playerMonitor`, read by `getWorldJoinCode()`), with one rule over the world's history: the last code after the last session start, NULL if a start is visible with no code after it, the remembered code if no start is visible. Forgetting is keyed on the log showing a new session, not on engine start, because supervisor's autorestart relaunches a crashed world without the engine. The same rotation made `playerMonitor` write a fresh `player_count=0` that auto-update accepted as "idle"; an unreadable count is now NULL. ### Config attribution for pre-2.55 worlds, and manual matching `mod_plugin_guids` was only learned on a full install, so worlds set up before 2.55 never learned which config each mod writes, and forks (`valheimplusgrantaphertemporary` vs `valheimplus`) could not be rescued by name. `pluginGuids.py --all --learn` then `modConfigs.py --reattribute --all` run on every boot. When attribution still cannot decide, the operator can: `mod_plugin_guids` gained `learned` and `manual` flags (two flags, not one origin, so Undo clears a manual claim without deleting a learned fact), and an unambiguous manual claim wins in `resolve_guid_owners()`. ### Smaller - Client download menu falls back to GitHub's "latest release" page when the API is rate limited; the Client Download URL setting is retired. - Dashboard: compact header strip, one Actions cell per world row (Launch Start Stop | Mods Update Settings | Logs Delete), Mod Catalogues as one full-width row per catalogue, sidebar grouped Main / Server / Tools. The log viewers load the admin stylesheet instead of a private palette (they had the browser's default light scrollbars). - `dev_tools/buildRcDetached.sh` defaults to `:dev`; `:rc` requires `TAG=rc` and `EXTRA_TAGS` is refused from a `:dev` build — a 2.56 work-in-progress reached `:rc` once and was rolled back to the 2.55 digest. - The repository has CI: `.github/workflows/oracles.yml` runs the standalone oracle suite. ## v2.55 ### "Mod rebuild failed" five seconds into a rebuild that never ran An operator pressed Settings → Updates on a world. The log said: ``` 21:44:03 [NOTICE] Auto-update 'Midgard': phase=mods 21:44:03 [NOTICE] World 'Midgard' successfully stopped. 21:44:08 [ERROR] Auto-update: mod rebuild failed for 'Midgard' ``` Five seconds, on a job that takes minutes. Nothing had failed — the rebuild was never requested, and the "failure" was a flag left over from an unrelated incident hours earlier. Two independent defects, either survivable alone. **The race.** `stopWorldAndWait` returned as soon as the *process* died. But the process dying is not the end of the engine's stop: its stop branch loops `sleep 10; worldProcessRunning` and writes `mode='stopped'` only after a sleep in which the process was already gone. So the engine keeps running for up to ten seconds past the kill, and its **last act is a write to the very column the applier uses to hand work back to it**. The applier returned ~5s in, ran the game update (10s of steamcmd), set `mode='update'` for the mods phase — and the engine, finally waking, wrote `mode='stopped'` straight over it. Both writes landed in the same second, visible as the two 21:44:03 lines above. Now the stop is not complete until the engine *says* it is: both `mode='stopped'` and the process gone. **The stale verdict.** `waitForEngineUpdate` broke on the first mode that was not `update`/`updating` — which includes the mode the world was already in. With the request erased, it saw a terminal mode on its first poll: *finished* and *never started* were the same observation. It then judged the run by `worlds.status`, and **nothing in the engine, `0-functions.sh` or `updateApplier` ever clears that field** — grep every writer and they only ever set it. The world had carried `status='failed'` since an earlier incident, read straight from the database eight minutes *before* the update that then "failed". So any world that had ever failed a rebuild reported failure on every subsequent update, including ones that worked. Fixed by requiring the rebuild to have been *observed running* before a terminal mode counts, naming the overwritten-request case explicitly instead of calling it a failure, and clearing `status` / `update_state` / `update_last_result` before the first phase so the check at the end measures this run rather than remembering the worst previous one. **A regression inside that fix, caught on `:rc` before any tagged release.** The `clearPriorVerdict` call landed on the line *after* `update_state='updating'` and set `update_state='running'` — a value **nothing reads**. Counted across the admin UI, it tests for exactly two values (`pending`, `updating`); the backend could write five. `running` had zero readers. The cost was all three things an operator reported seeing: the Updates tab polls only while `update_check_state === 'checking' || update_state === 'updating'`, so it stopped on the first tick (no live phase); `renderUpdateStatus` has no `running` branch, so an update in progress fell through to the up-to-date rendering; and re-opening the tab re-read the same unknown value, which looked like the status being cleared. It also disarmed `reconcileStrandedUpdateState`, which finds interrupted updates by looking for exactly `updating`. The clear now runs *before* the declaration and does not touch `update_state` at all — that column is the run's live signal, and the stale-verdict fields it has business resetting are `status` and `update_last_result`. Part 2b of the race suite pins all of it, including a negative on `update_state='running'` anywhere in the file. The original ordering assertion did not catch this because it compared the clear against the first *phase*, which stayed correct throughout. The thing worth asserting was the clear against the *declaration*. `dev_tools/test-update-handoff-race.sh` (13) runs the race for real: a stub engine that kills the process early and writes the mode late, against the extracted `stopWorldAndWait`. Its control is the pre-fix shape, which must *lose* the write — without that, part 1 would pass with the fix removed. Against `HEAD` the suite fails 8, including the behavioural case reproducing `mode=stopped` exactly as the live log shows it. ### A restore reported success and then undid itself An operator restored a 10-03 backup of their world to repair a building they had broken that evening. Every step of the restore reported success. The damage was still there. The restore had worked. Something put the newer world back afterwards — and that something was the restore's own last step. `worldRestore` decided whether to stop the world by running `supervisorctl status`. It cannot run it. `adminAPI.php` launches the restore as the `phvalheim` user, and `supervisord.conf` is `0660 root:root` behind a `0700 root:root` socket, so the call dies with *could not read config file* and a **non-zero exit** — which `[ $? -eq 0 ]` read as "the world is not running". The stop was skipped entirely and the backup was extracted underneath a live Valheim. Then the restore set `mode='update'` to trigger a rebuild. The engine runs as root, so *its* `supervisorctl` works: it stopped the world properly. Valheim saves on a clean shutdown. It wrote its in-memory world — hours newer than the backup — over the files that had just been restored. The proof it never stopped anything is an absence: `Stopping world process...` does not appear once in `worldBackups.log` for that restore. Fixed by stopping through `worlds.mode`, which the engine performs as root, and confirming with the **process table**, which any uid can read. An un-stoppable world is now **fatal** — a restore that refuses is recoverable, and one that half-works is not. The closing `supervisorctl start` was equally inert, and reported either "started successfully" or "queued (engine will start when ready)". Neither was ever true: nothing was queued, and the engine's update branch ends on `mode='stopped'` by design, so it could not have been handed a start either. An operator told the world started and finding it down assumes the restore failed. It now says the world stays stopped until the rebuild finishes. Behavioural proof in `dev_tools/test-restore-stops-the-world.sh` (11): it starts a real decoy process whose command line the real `pgrep` matches, and asserts the restore refuses to proceed while that process is alive. Against `HEAD~` the two data-loss assertions fail, which is the only reason to believe the other nine. ### "error retrieving current directory" in the log, forever, after a world was deleted An operator reported these two lines, repeatedly, with no idea what produced them: ``` shell-init: error retrieving current directory: getcwd: cannot access parent directories chdir: error retrieving current directory: getcwd: cannot access parent directories ``` `packageClient()` ended with a bare `cd "$stage"` and nothing to put it back, and `packageClientConfig()` did the same. Those were the engine's **only two** `cd` sites and there were **zero** ways back. `packageClient()` runs from the main loop — a bash process that lives for weeks — so after the first package the engine's working directory sat inside whichever world it had packaged last. Delete or re-create that world and the engine's cwd became a deleted inode, after which **every child process it spawned** printed those lines at bash startup: every `$(SQL ...)`, every tool invocation, forever, until the engine restarted. Measured on a live server before touching anything: `/proc//cwd` → `.../worlds/Midgard/client`. It is non-fatal — bash carries on from `/` — which is exactly why it survived. Nothing failed loudly enough to investigate, and the noise lands in the log an operator sends when something *else* is wrong. Both sites now run the `cd` and the `zip` inside a **subshell**, so the engine's own directory never moves. The cd-ability probe is kept **separate** from the zip deliberately: an un-enterable staging tree must stay fatal and named, rather than degrading into a zip exit status that lets the config archive run against a tree that is not there. Both `zip` targets were already absolute, which is what makes the subshell safe, and that is now pinned by a marker so it cannot quietly become relative. `dev_tools/test-engine-cwd-stays-put.sh` is 10 assertions. The one that carries it is **behavioural**: it runs the real `packageClient()` with everything else stubbed and compares `$PWD` across the call. No grep can tell whether a `cd` is scoped. It fails on the previous code with *"packageClient MOVED the engine's cwd"*, and the missing-staging-tree control confirms a failed package does not move it either and is still fatal. ### Clearing stale mod settings in bulk, without destroying the ones still in force The unmatched-settings panel lists two kinds of row that read almost identically and have opposite consequences: | Reason | State | |---|---| | *this version of the mod does not use this setting* | dead — can never apply again | | *the mod has not written this config yet* | **still applied** — matches again on that mod's next load | Every row has a `forget` button, and `reset: true` deletes the saved value outright — the database row **is** the only copy. A dozen overrides are already suspected lost to that button being unconfirmed. So a bulk control here is a single click that can destroy an arbitrary number of live settings, and the design is entirely about which rows it may reach. `safe_to_forget` is now a **flag**, computed in `modconfigs.php` at the point the two cases are actually distinguished, and it is what the selector keys on. The distinction had only ever existed as an English sentence on the row; a bulk delete deciding by matching that sentence would be one rewording away from forgetting live settings. A `local_dll` **downgrades** safe back to not-safe — the panel asserts "no mod uses this any more", and for a file one of the operator's own plugins demonstrably reads, that is the opposite of the truth. The row already said so in words; now the flag agrees, so "select the safe ones" cannot tick a row whose own text reads *"Do not forget it"*. There is deliberately **no "select all"**. The button is *Select the N safe to forget*; the still-applied rows start unticked, are badged **STILL APPLIED**, and can only be reached one at a time. The count of still-applied rows in the current selection is shown *while choosing*, not only at the end, and the confirmation **names** them rather than counting them — a number is not something an operator can check, but a key they recognise is. Both delete paths now confirm before posting. The single-row button never did. Bulk goes through the existing `saveModConfigs`, which already accepted an array of items, so there is no second endpoint to drift from the first. `dev_tools/test-stale-bulk-forget.php` is 23 assertions, and part 1 **executes** the real classification block with stubbed inputs rather than grepping it: the thing that matters is the flag's *polarity*, and `=> false` versus `=> true` differ by four characters, so a source check that merely found the key present would pass on the data-loss version. Six mutations were each caught by exactly one assertion — flipping the polarity, ignoring `local_dll`, turning the selector into a select-all, dropping the confirmation, pre-ticking every row, and reducing the confirmation to a bare count. ### A container restart during an update left the world stuck "updating" forever Reported from Discord. `worlds.mode` carries two different kinds of value and only one of them survives an interruption. **Commands** — `create`, `start`, `stop`, `update`, `delete`, `repackage` — each have a branch in the engine's main loop, so a restart with one pending only means the command runs late. **In-flight states** — `creating`, `updating`, `starting`, `stopping`, `repackaging`, `backup` — are set by the engine on itself while work is running, so the UI can say what is happening and the next 2-second tick cannot re-enter work already going. Nothing in the loop matches them, deliberately, which means they are cleared only by the very code that set them. Kill that code and the world is unreachable: the loop reads a mode it has no branch for and skips the world, every two seconds, for as long as the container lives. Nothing short of editing the database by hand could clear it. `reconcileStrandedWorlds()` runs at boot and lands every in-flight world on the **truth**, taken from the process table — `running` or `stopped`, never on a command. Landing on `start` would boot a world the operator had deliberately stopped; landing on `update` would silently rebuild a world nobody touched, once per boot, forever. `broken` is excluded: it is a terminal state the engine chooses when it wants a human to look, and re-deciding it at every restart would undo that. Three of those states were **writing the world's files** when they stopped, so for `creating`/`updating`/`repackaging` the world is not merely mislabelled — its game tree, mod set or client payload is half-built. Those are flagged `update_interrupted=1`, and `autoStart()` refuses them. That refusal is the load-bearing half: `purgeWorldModsConfigsPatchers()` runs early in an update, so the most likely interruption point leaves a **modded world with no plugins at all**, and autostart would then publish it to players as an effectively vanilla server. The update path already refuses to produce that outcome on its own; it must not arrive by the back door either. A completed update clears the flag — reached only by falling through every failure `continue`, so a rebuild that failed leaves the world un-autostartable, which is the point. Separately: `creating`, `updating` and `broken` were in **neither** label map, and the fallback is the raw column value — so the stuck world above showed a pulsing lowercase `updating` with no capital letter and no explanation. That is literally what the operator was looking at. All three now have labels in both maps (the JS copy is what the 5-second poll uses, so a mode present only in the PHP map renders correctly on load and reverts on the first refresh), and `broken` has its own CSS rule that deliberately does **not** pulse — a pulse means work is happening, and the whole meaning of that state is that nothing is happening until someone acts. `dev_tools/test-stranded-world-recovery.sh` is 42 assertions. Six targeted mutations were each caught by exactly the assertion that should catch them, and every "nothing happened" claim is paired with a world that must have moved in the same run. ### An automatic update restarted a world with players on it Reported from Discord: "players got kicked because phvalheim shutdown the world for an update". Valheim exposes no live player count, so `playerMonitor` scrapes one out of each world's log. On a crossplay world the only signal is PlayFab's `... now N player(s)`, which is emitted **on join and on leave and at no other time**. A player who joins and then plays for two hours therefore leaves exactly one line behind, two hours old, reading `1`. 2.47's `isIdle()` had a second arm: a nonzero count counted as idle once its observation aged past `autoupdate_idle_minutes`. That arm existed for a real failure — a count can stick nonzero after an unclean disconnect, verified on a production world that logged `now 1 player(s)` and then nothing for 39 minutes while empty — but a stale nonzero count has **two** causes the count cannot tell apart: everyone left and the leave was never logged, or someone joined and is still playing. The second is not an edge case, it is what an ordinary session looks like, and with the threshold defaulting to 30 minutes any session longer than half an hour qualified. The arm is gone. A nonzero count is never idle, at any age — this script's own stated rule ("anything it cannot establish counts as a no") applied to the one place that broke it. The cost is real and is the correct trade: a world whose count sticks nonzero will not auto-update on the idle path. It is not stuck, because the operator already has an explicit escape hatch that does not require guessing on their behalf — `autoupdate_max_wait_hours` with `autoupdate_on_timeout='force'`, checked *before* the idle gate. Accepting a disconnection after N hours is a decision an operator can make; having it made for them silently, 30 minutes into someone's session, is not. A held-back world now also records **why** it is waiting, in two distinct messages, because "players are on it" and "this world has not reported a count at all" have different remedies. **Automatic updates are now marked BETA** in both places they can be switched on, with the reason stated plainly, and they remain **off by default** — `settings.autoUpdateMode` and `worlds.autoupdate_mode` are both `DEFAULT 0`, and nothing in the tree sets either to 1 (there is a marker that wants 0 for exactly that). Accurate detection via the server-side Companion — `ZNet.GetConnectedPeers()`, a heartbeat rather than an event — is written up in `docs/BACKLOG.md` and is what would let the badge come off. `dev_tools/test-autoupdate-idle-gate.sh` is 19 assertions. Re-introducing 2.47's arm turns three of them red, including both behavioural ones; the fresh-zero positive control is what stops "not idle" passing because the function refuses everything. ### A running world gave no sign it was not using the mod settings that were saved BepInEx hands a plugin its config at load, so a server-side setting saved while the world is up is stored, will be applied, and is not in effect. The only thing that ever said so was the save summary modal — gone the moment it was closed. Reload the page, return the next day, or have a second admin save a value, and nothing anywhere said this world was running on settings that were no longer the saved ones. The dashboard's own `restart pending` badge sat beside it looking authoritative while comparing only four launch options. `modConfigPending()` compares the saved overrides against `.applied-configs`, written by `materialise()` at the moment those values went onto the world's tree — the same device as `.running-options`, for the same reason: the database holds the saved state and has no column for the applied one. **`date_set` cannot serve as that oracle, which is the whole reason for the snapshot.** The column has no `ON UPDATE` clause and the save path never writes it, so editing an *existing* override leaves the original insert timestamp. A check built on it would report a brand new override correctly and be silently blind to the commonest case there is. Four states, because the fourth is the one worth having: `na` (not running), `unknown` (running with nothing to compare against — a world last started before this release), `clean`, and `pending`. A missing snapshot is **not** `clean`; that conflation is the 0-means-two-things bug this project shipped three times in one release. Only `server` reach counts. A change only players read is waiting on *Apply to players*, not on a restart, and a badge telling an operator to restart for something a restart cannot deliver is worse than no badge. `$reachOf` was a closure inside `modConfigSaveOverrides()`; it is now `modConfigReachOf()`, so the badge and the save modal cannot disagree about the same setting. Deliberately **not** folded into `worldRestartPending()`: that function is one half of a mirror against `startWorld.sh`, and `test-restart-pending-mirror.sh` fails if either side grows a key the other lacks. The labels are merged at the two call sites instead — both of them, since the dashboard renders the badge server-side on load and from the 5-second poll after. `dev_tools/test-config-restart-pending.sh` — 18 assertions. Four mutations were each caught by exactly one of them: reporting a missing snapshot as clean (T2), dropping the reach filter (T6), deleting the reset branch (T8), and moving the snapshot write below `materialise()`'s no-overrides return (T14, the stale-snapshot trap that would make the badge unclearable). Markers `v55dy`–`v55ee`, with `v55ee` wanting **0**. Two notes for whoever edits this next. The fixture is produced by the real `record_applied()` after a hand-written one made every case read `unknown`: the snapshot keys are joined with `0x1F`, and a raw control byte inside a JSON string is invalid JSON, so `json_decode` returned NULL — a fixture the parser silently rejected, which would have proved the opposite of the truth. And `v55eb` uses `grep -F` because the call site contains `$pdo`: a `$` mid-pattern is literal in BRE but an end-of-line anchor under `-P`, and the same marker read 1 under dash and 0 under a bash whose grep defaults to PCRE, on an unchanged file. ### Apply to players left the operator to find the progress themselves The repackage's progress is the world's *Repackaging* status pill, on a different page from the button that starts it, so the modal said "the dashboard shows when it finishes" and left the looking to them. It now hands off: a visible countdown, a "go now" link, and `Stay here` to cancel — the save receipt stays on screen rather than being yanked away. Applied to **both** paths of that button, including the one taken when there is nothing unsaved; they are the same button to the operator and must end in the same place. ### An existing world had a password imposed on it by rebuilding its mods 2.53 generated a password for any modded world that had none. The first cut did it in the migration, at upgrade, which password protected every world at its next restart while its players were still on a client that could not forward one — so the fix moved generation into the world UPDATE path, where it would land with everything else an update changes. That was narrower and still wrong. The create block ends by setting `mode='update'`, so the one call site served new worlds **and** every rebuild of an existing one: a mod-list save, the Rebuild Mods button, Hugin. An operator deliberately running without a password got one anyway, the first time they touched that world's mods, and found out when a player was asked for it. `ensureModdedWorldPassword()` is now `ensureNewWorldPassword()` and is called from the engine's **create** block only. For an existing world, whether it has a password is the operator's decision in the Settings modal, and empty is a supported answer — `startWorld.sh` omits the flag entirely, and Valheim only validates passwords under `-public 1`. The one genuine requirement, a world listed in the server browser, is still enforced where the operator can act on it: `saveWorldOptionsJson()` refuses the save and `startWorld.sh` logs a named ERROR. Two guards rather than one, because the 2.53 bug was a correct function at the wrong call site and nothing inside it could tell: it still only ever fills an **empty** password, and it now also refuses any world with a `world_md5` — one that has been published to players at least once. The policy lives in the function, so a future caller added in the wrong place cannot reintroduce this. Passwords already generated are **left alone**. Nothing records whether a stored password was generated or chosen, so clearing them would be guessing at the operator's intent in the same way that caused this; What's New says so and points at the Settings modal. `dev_tools/test-blankpassword-retirement.sh` is 21 assertions. The two that carry the change are an already-published control (an established world with an empty password must come away with nothing, paired with proof that `world_md5` was actually queried, or its silence means nothing) and a line-number assertion that no generating call exists at or below the update block. Both fail on the pre-fix behaviour; every other assertion in the file passes either way. Markers `v55du`–`v55dx`, with `v55dw` wanting **0**. ### A config file whose owner became knowable later stayed "Unattributed" `mod_config_overrides.mod_id` is attribution and it is written **once**, by `attribute()`, at the moment a row is saved. The exact half of that answer lives in `mod_plugin_guids`, which is populated when a mod is **installed** — so every row the legacy import created on a world whose GUIDs were not yet learned stored `NULL`, and nothing ever revisited it. Those rows were always being applied — the table is keyed on the file, not the mod — but they filed under *Unattributed* in the editor and were absent from their mod's Config badge, which counts the stored column. Measured on VikingOutlaws: `flueno.SmartContainers.cfg`, whose GUID now maps to an installed mod, still read Unattributed. `reattribute_unowned()` asks `attribute()` the same question a save would ask today and takes its answer. It runs inside `materialise()` (so a world heals on its next update) and from `dbUpdate_2.55.sh` on **every** boot — deliberately not behind the one-shot import flag, since a GUID can become knowable at any later install, which makes "has this been done" not a property of the installation. `NULL` → a value only, never a value → a *different* value; the `UPDATE` repeats `AND mod_id IS NULL` so the guard is in the statement, not just in the row list it was handed. And this is **not** "fill in the blanks": `NULL` is a legitimate permanent state for a `custom_plugins/` drop, the loader, and any operator file with no catalogue entry, and `attribute()` returns `None` rather than choosing between two candidates — a wrong owner is worse than none, because it files a setting under a mod that never reads it. Guarded by `dev_tools/test-config-reattribution.sh` (8 checks, all 8 fail on the pre-fix tree). ### A world update emptied the settings list `purgeWorldModsConfigsPatchers()` deletes `BepInEx/config/*` on every update, and the editor renders from the files on disk. A mod writes its config on its first `Config.Bind()`, and `mode='update'` always ends **stopped**, so the moment an update finished the only files left were the handful `materialise()` rebuilt from saved overrides. On VikingOutlaws that was **8 of 29** mods, down from 26, and it stayed that way until someone started the world. Nothing was lost — the overrides are rows in `mod_config_overrides` and they re-apply — but the operator's *reachable* surface collapsed, which is indistinguishable from the feature breaking. `snapshotModConfigs()` now remembers each config file's **text** in `mod_config_shapes` before the purge takes it, and `modConfigEditorPayload()` falls back to that for a file that is absent, marked **from memory** on the card and in the picker. Those entries are fully editable: an edit becomes a per-key override row exactly as it would against a live file. Three things this deliberately does **not** do: - **It never writes the remembered bytes back onto a world's tree.** Restoring the whole file is the pre-2.55 `custom_configs/` behaviour this release exists to undo — BepInEx keeps a key the new version dropped as an orphaned entry forever, and the file's own `# Default value:` lines would be the *old* version's, which is the baseline every modified-from-default badge is measured against. `test-config-shape-memory.sh` asserts this by enumerating everything `modConfigs.py` writes to disk, rather than by grepping for the absence of a word. - **It only remembers a file BepInEx wrote.** `cfg_is_documented()` is the load-bearing distinction: on the second update of a world nobody started in between, the only files on disk are the thin ones `materialise()` produced, and remembering those would replace a rich remembered shape with a bare key list — losing the exact surface this keeps. - **It forgets a removed mod's shape.** A remembered shape outlives the file, so without `forget_unreadable_shapes()` a mod the operator removed would keep its settings on offer forever — the display-side twin of the manufactured-config bug fixed earlier in this release. It reuses `cfg_is_claimed()`, which fails open, and never forgets a file still on disk. The ordering is the whole correctness argument and it is one line: run the snapshot *after* the purge and it succeeds having remembered nothing. No unit test can see that, so marker `v55cz` and the suite both assert it by line number in `container/engine/phvalheim`. The coverage banner now reports three states instead of two — written, remembered, never seen. Folding "remembered" into "written" would claim the world is running settings it has not regenerated yet, which is the same partial-answer-as-a-complete-one shape the banner was added to kill. ### The config editor was unreachable from the one state it was built for The editor's Apply button says *"Rebuilds the client payload for <world>. The world keeps running."* The only link to that page was inside `edit_world.php`, which the dashboard gates behind **Edit Mods** — a button disabled whenever the world is online. So the page promised a running world and could only be opened from a stopped one. Nothing server-side was wrong, which is why nothing caught it: `repackageWorld()` has always accepted `mode IN ('running','stopped')`, and `world_configs.php` itself has no running-state guard at all — only a vanilla one. The feature worked; it just had no door. Each world card now carries its own **Configs** action, enabled for any non-vanilla world that is running or stopped, and disabled mid-operation (where `repackageWorld()` would refuse anyway). The markup comes from a single `modConfigsButtonHtml()` used by all three row branches *and* the 5-second poll updater — three hand-copied ternaries are how this dashboard's gates have gone stale before, and a button that is correct on page load and wrong four seconds later is worse than one that is simply absent. **Edit Mods is deliberately unchanged.** Editing the mod list rebuilds the modpack and must still require a stopped world; `dev_tools/test-config-entry-point.sh` carries that as an explicit control, so "make the page reachable" cannot be satisfied by loosening the wrong gate. That suite ships with a `--self-test` flag that runs it against the previous commit and refuses to pass unless the assertions actually fail on the broken tree. ### Saving now says what changed, and who still has to receive it Saving wrote one line — `3 saved, 1 reset` — and reloaded the page 700ms later. That is exactly where "I saved it and nothing happened" comes from: the operator was never told that a stored value sits in the database until something pushes it, nor which of their changes needed pushing. `modConfigSaveOverrides()` now returns a per-change summary and the page renders it as a modal: every setting touched, **what it was and what it is now**, and who needs it. The previous value required reading the row *before* writing it, which nothing did before — so the old confirmation could only ever report a count. Each change is classified three ways, and the third is not a cop-out: on a real world **15 of 40 override rows have no `mod_id` at all**, because attribution matches a config filename against the world's installed mods and deliberately refuses near-misses. - **`server`** — `server_only`, so it is never written into the client payload; or the mod is not deployed to players' clients, so nothing there reads it. Worth noting the difference: a `deploy_client=0` mod's config *is* still written into the payload (materialise filters on `server_only` alone) — it simply has no plugin on the player's side to read it. Either way no push is needed. - **`players`** — the mod runs on players' clients. - **`unknown`** — the file could not be attributed. The value ships regardless; we just cannot say whether anything client-side reads it. `unknown` is grouped **with** `players` for the push decision, because the two errors are not symmetric: an unnecessary push costs one 80 KB download, while a missed one loses the operator's change with no symptom. `needsPush` is computed server-side so the button and the prose cannot disagree, and the Apply button is hidden entirely when nothing needs pushing — offering a rebuild that changes nothing for anyone is its own kind of lie. The server-side note adapts to `worlds.mode`: a running world is told to restart, a stopped one is told it will pick the change up on its next start and there is nothing to do. Telling someone whose world is already stopped to "restart to apply" is the kind of instruction that makes an operator distrust the rest of the message. Three smaller things fell out of it. Refusals moved from a blocking `alert()` into the summary, where they sit next to the changes that *did* save. A reset that removes nothing is no longer reported as a change. And the 700ms auto-reload is gone — the page now reloads when the summary is closed, because the old timer would have torn the modal down while it was being read; marker `v55bd` asserts it stays gone. Config keys and values come from mod authors, so everything interpolated into the summary is escaped. Guarded by `dev_tools/test-save-summary.php` — 32 assertions against the **live** database inside a transaction that is always rolled back, so it exercises the real joins and collations without altering a stored override. It creates the `deploy_client=0` condition rather than skipping it when a world has no such mod. Mutation-verified: reporting the new value as the old one, always answering `players`, hardcoding `needsPush`, and reporting no-op resets each turn it red. ### Applying a config change no longer costs a full world update Saving in the editor wrote database rows and set no `worlds.mode`, so the engine never woke up. `materialiseModConfigs()` ran on world **start** and world **update** only, and the file players actually download is `.zip`, which only `packageClient()` rebuilds — in the update branch alone. So for a mod that runs on players' clients, a start applied the value to a tree nobody downloads. Measured on a real world (VikingOutlaws): `Show Clock = Off` was saved at 17:29, the last `packageClient()` ran at 17:08, and the value was present in `game/`, present in the client staging tree, and **absent from the payload**. A natural control sat in the same file — `Clock Font Color = 1500FF`, saved *before* that update, and present in the payload. Same mod, same file; the only difference was which side of `packageClient()` each was saved on. A full update was the only way to ship it, and that stops the world, runs steamcmd `validate`, purges `BepInEx/{config,plugins,patchers}` on both trees and re-downloads every mod — 572 MB of plugins reinstalled, and every player disconnected, to move 80 KB of config. **New `worlds.mode = 'repackage'`**, driven by an **Apply to players** button on the Mod Configs page. It runs `materialiseModConfigs` → `ensureBepInExLoaderConfig` → `packageClient` and nothing else: no steamcmd, no purge, no mod re-download, and **no world stop** — `packageClient()` reads the client staging tree while the server process reads `game/`, so nothing contends and nobody is kicked. `worlds.mode` is `TEXT`, not an `ENUM`, so the new value needed no migration. Five things it gets right deliberately, each guarded by `test-client-payload-sync.sh` T8: it always lands on `running`/`stopped` read from the process table, because `repackaging` is not a command and leaving it set would have the 2-second loop revisit that world forever; it never sets `mode='start'`, which would boot a world the operator had deliberately left stopped; it keeps the **previous** `world_md5` when packaging fails, because `setMD5 ""` means "no payload" and would tell every client there is nothing to sync; it does not touch `date_updated`, which means "mods last rebuilt"; and it does **not** call `InstallCustomConfigSecureFiles`, which runs after `packageClient` in the update branch but whose `custom_configs` copy runs *before* `materialiseModConfigs` — calling it here would invert the database-wins-over-directory ordering and let a stale file overwrite the value just saved. ### A config change now costs players 80 KB instead of 573 MB `packageClient()` additionally builds `-config.zip` — `BepInEx/config` and nothing else — and stamps `worlds.config_md5`. Measured on the same world: **80,174 bytes against 577,604,688**, about 7,200× smaller. Of the 573 MB staging tree, 572 MB is `BepInEx/plugins` that a config edit cannot touch and 224 KB is config. Both checksums are written from the same tree state in the same pass, and `api.php?mode=getSyncState` returns both in **one** response. Fetched separately, an operator who repackages between the two calls hands a client a payload checksum from one generation of the tree and a config checksum from the next, with no way for the client to detect it. **`world_md5` is still exactly the md5 of the real `.zip`, and that is load-bearing.** `Syncer.cs` compares it against `getMD5()` of the payload file on the player's own disk. Making it a composite of both archives — the obvious way to make an old client notice a config change — puts every old client in a *permanent* re-download loop: it fetches the zip, hashes what it got, still disagrees with the composite, and tries again on every launch forever. So `config_md5` is strictly additive, a repackage rebuilds **both** archives, and an old client degrades to exactly today's behaviour. `mode=getMD5` is untouched. Guarded by T1, which is first in the file because no assertion about the new client could ever see this. A failed rebuild keeps the last good archive and its checksum: the archive is written to a temp file and moved into place, because `rm -f` then `zip` destroys the good one the moment zip fails and the stored checksum then names a file that is not there — so every client would ask for a 404 instead of falling back. A world with no staging config dir *clears* `config_md5` to `NULL` instead, which means "nothing to compare against"; `''` would read as a legitimate answer the first time anything compared it with `==`. ### Client: three sync paths, and no more hashing 573 MB on every launch `Syncer.cs` ran `getMD5()` over the whole payload **on every single launch** just to answer "what version do I have" — a full read and MD5 of 573 MB, seconds of cold disk every time, to learn something it already knew. It now keeps a `.sync` record of both checksums and hashes the payload in exactly two cases: the record is missing (first run after upgrading), or a download just finished. That second case is not optional. The old client's per-launch re-hash caught a truncated or corrupt download by accident on the next run; writing a record without verifying would turn that accidental self-healing into a permanent lie. A corrupt download is now discarded, the record deleted, and the player's existing install left untouched rather than half-replaced. Three paths: payload differs → full download, verify, extract (as before); only the config differs → fetch the 80 KB archive and **replace** `BepInEx/config` wholesale; both match → do nothing. Replaced, never merged: resetting a setting *removes* a key and can remove a whole file, and a file-by-file copy would leave the stale one behind so the reset never reached the player. This is no more destructive than the full path, which already deletes the entire world directory. A new client against an old server falls back to `mode=getMD5` and simply never takes the config path. An unknown remote config checksum is treated as "differs", never as "matches" — the fail-safe direction costs one 80 KB download; the other loses a config change forever. Also removed from that file: `localWorldVersionFile`, declared and never used — a vestige of this exact idea, whose name the sync record now takes over; `localMissing`, assigned in both branches and never read; and `doorstopExists`, computed, never read, and recomputed, with the `if (!doorstopExists)` guard around the doorstop copy commented out. ### Also fixed: three assertions in `test-mod-destination-picker.sh` that had been red for a while Found by running the sibling suites rather than only the new ones. `destinationCell` gained a third parameter, `neededDeps`, when the derived-dependency badge was added, and the suite still grepped for the two-argument form and still *called* it with two arguments — so the parameter shadowed the global of the same name, the derived branch was unreachable, and three checks were permanently red for a feature that works. 2.55's Config column then appeared to break a fourth (`targets: [0, 5]` became `[0, 5, 6]` on `edit_world.php`, correctly, since the Config cell is also a control); that assertion is now a prefix match, which still catches column 5 becoming sortable — the regression it exists for — while allowing the new column. A control was added: the same uuid with no `neededDeps` entry must *not* render as derived, or a `destinationCell` that badged every unselected mod would pass. ### Fixed before release: every override was inert on a world update The first 2.55 image applied **nothing**. On a live world it logged `0 applied, 78 not applicable`. `materialise` only rewrote keys in files that already existed, and never created one. But `purgeWorldModsConfigsPatchers()` empties `BepInEx/config` on every world update, and almost no mod ships a `config/` inside its zip — AzuClock does not. So at materialise time, during an update, the target file **does not exist yet**: the mod writes it afterwards, on first load, from its own defaults. Every stored setting was skipped and replaced by a default. The refusal was justified by a comment asserting that a pre-placed key would be disregarded by the loader and dropped on the next save. **That assertion was false.** BepInEx's `ConfigFile` parses the file into its entries plus an orphaned-entries table, and `Bind()` adopts a stored value when the key is present — which is exactly how the pre-2.55 `custom_configs/` copy worked, since those files were placed *before* the world had ever booted. `materialise` now creates the file (`render_new_cfg()`) when the mod has not written one, and injects a missing key into an existing file. A key the mod no longer binds is harmless: BepInEx keeps it as an orphaned entry and nothing reads it. **Why the tests missed it.** Every materialise test pre-created the target file — the one state in which the broken version works — and the live test exercised a world *start*, where the previous boot had left a file behind. `test-mod-config-editor.sh` now has T10, which starts from an **empty** directory, the state an update actually hands it. Reverting the fix turns T10 red. Stale detection was re-based on **metadata** rather than key presence: now that missing keys are injected, a presence test would report nothing forever. A key the plugin bound carries `# Setting type:`; an injected orphan never gains it. Gated on the file having documented something, so a just-created file is not reported as broken. ### Fixed: the apply-point was stated wrongly "Restart the world to apply" is only true server-side. A mod that runs on players' clients reads its config from the client payload zip, which only `packageClient()` rebuilds — and that runs on a world **update**, not a restart. The page, the save confirmation and the What's New entry now state both paths. ### Fixed: a long documented default spilled out of the table A grid item defaults to `min-width: auto` and refuses to shrink below its content, so one long default — AzuClock documents a whole HTML template as its `Clock String` default — pushed the row outside its card. `min-width: 0` on the grid children is the actual fix; the value is also clamped to three lines, expands on hover and carries the full text in a `title`. ### New: the mod config editor (issue #84) An operator can edit any mod's settings from the admin UI, and the changes survive a mod update. Entry points are a **Config** button on each selected mod's row in `edit_world.php` and the standalone `world_configs.php`, which is the same page with the mod filter dropped — one renderer, two entry points. ### Per-key overrides, not whole files `purgeWorldModsConfigsPatchers()` deletes `BepInEx/config/*` on **every** world update, so a mod config is derived and never state. The pre-2.55 way to keep an edit was to copy the whole file into `custom_configs/`, which pins the config at the shape the mod had when it was copied: a setting the new version **adds** is lost, one it **removes** lingers forever, and "which values did the operator actually choose?" is unanswerable. 2.55 stores sparse `(world, file, section, key) → value` rows in the new `mod_config_overrides` table and re-applies them onto whatever the new version generates. `dev_tools/test-mod-config-editor.sh` asserts all three outcomes directly. The table is keyed on the **config file**, not on `mod_id`; `mod_id` is nullable attribution. Three live classes of config file have no `world_mods` row to hang an override on — the engine-installed non-catalogue plugins (`ZeroBandwidth-CustomSeed`, `PhValheim-TickMonitor`), any DLL an operator drops into `custom_plugins/`, and the whole config tree `importWorld.sh` copies in. Keying on `mod_id` would have left every one of those uneditable. `cfg_file`, `section` and `ckey` are `COLLATE utf8mb4_0900_as_cs`, same hazard as 2.43's `mods.owner`/`name`: BepInEx keys are case-sensitive, and under the default `ai_ci` the unique key would collapse `Enabled` and `enabled` into one row. ### The form is generated from the config file's own metadata BepInEx writes `# Setting type:`, `# Default value:`, `# Acceptable values:` and `# Acceptable value range:` above every entry, so a typed widget per setting needs no per-mod schema registry. `# Default value:` is also the baseline for every "modified" badge and for the legacy import diff — it travels inside the file, so it needs no catalogue lookup and no network. There is exactly **one** cfg parser, in `engine/tools/modConfigs.py`. The admin UI shells out to its two no-database modes (`--parse-dir`, `--parse-file`) rather than carrying a PHP parser, and hands the world's mods in via `--catalogue-file` rather than reimplementing attribution. php-fpm runs as `phvalheim` and reaches the database as `phvalheim_user`; the root-only modes (`--materialise`, `--import-legacy`, `--discover`) are called by the engine. ### Applied on world START as well as on update Every other config step in the engine lives in the update branch, and `startWorld.sh` does not touch `BepInEx/config` at all. Without a start hook, saving a setting would sit inert until the operator happened to run a full rebuild. `materialiseModConfigs()` is called from both, and runs **after** `installCustomModsConfigsPatchers()` so the database outranks `custom_configs/`, and **before** `packageClient()` so a client-destined value does not ship one update late. `server_only` rows are withheld from the client by **naming the server tree** inside `modConfigs.py`, not by call ordering — 2.53 recorded why an undeclared ordering is not a guarantee. ### The rewrite is surgical Only the value span of a matched line changes; the file stays byte-identical everywhere else, and a key that is not in the installed version is **reported, never injected** — BepInEx rewrites its config from the keys the plugin actually binds, so an injected key would be ignored on load and deleted on the next write while the UI claimed the override was in force. An early version of the rewriter captured the whitespace after the `=` but not before it, so `Weird = 7` came back as `Weird= 99`. Nothing broke — BepInEx reads either form — and the "how many overrides applied" count read 3 both before and after the fix. Only the byte-identity assertion could see it. ### `custom_configs/` and `custom_configs_secure/` are deprecated, not removed They are no longer the operator interface and the UI no longer points anyone at them, but the copy step stays, because it is also the **engine's own** persistence layer across the purge: `createCustomSeedConfig()` writes a world's seed into `custom_configs/` at creation and relies on every later update redistributing it. Removing the copy would have regenerated worlds with the wrong map. `dbUpdate_2.55.sh` runs `modConfigs.py --import-legacy --all` once, gated on `settings.configEditorMigrated` and only marked done on a zero exit. **The import takes only keys that differ from a documented default.** `importWorld.sh:143` copies an imported world's entire `BepInEx/config` tree into `custom_configs/`, so such a world is indistinguishable by directory listing from an operator who hand-copied hundreds of files, when almost all of them are untouched defaults. Importing those would have frozen that world at its import-time defaults permanently. A key with no documented default has no baseline at all and is imported as `origin='legacy-review'` and badged **needs review**, rather than silently kept or silently dropped. A consumed file is **moved** to `custom_configs/.imported-pre-2.55/`. Left in place, its stale non-overridden keys would keep landing underneath the overrides on every update — the same frozen config by another route. Nothing is deleted. `BepInEx.cfg` and `ZeroBandwidth.CustomSeed.cfg` are excluded from the editor and from the import, and are left where they are so the engine keeps distributing them. 2.49 swept the loader's config and silenced the world log and the client's console window together. ### The file browser no longer edits mod configs An edit saved there was reverted on the next world start with nothing logged, which is indistinguishable from a bug. `fileBrowser.php` now refuses `BepInEx/config` and the retired `custom_configs*` paths and names the editor instead. The guard sits before the `savedata` handler, so it covers the POST and not just the render. It cannot *prevent* a hand edit — the data volume is mounted on the operator's own host — so the message says the edit will be ignored rather than claiming it was blocked. ### Three states, not two "No config file yet" is reported explicitly and is not the same answer as "a config at all defaults". Most BepInEx mods do not ship a `.cfg`; the file appears on the first `Config.Bind()`, so a mod that was just added has nothing to edit until the world has booted once with it. A 0/false default doubling as a real answer has shipped here three times. ## v2.54 ### Fixed: the dashboard's Launch button sent `hammertime` as the password 2.53 gave every updated modded world a real password and made the Companion pre-fill it. It updated the launch string in two of the **three** callers of `phvBuildLaunchString()` — `includes/db_gets.php` (the public card) and `admin/index.php` (the dashboard's server-side render). The third, `getWorldsJson()` in `admin/adminAPI.php`, kept the pre-2.53 line: ```php $password = $vanilla ? ($row['password'] ?: "") : "hammertime"; ``` That endpoint is the dashboard's **5-second poll**. It redraws the world table and rewrites every `launchHref`, so the Launch link was correct on page load and wrong from the first refresh onwards. The client forwarded the payload, the Companion set `FejdStartup.ServerPassword` to the literal, and Valheim rejected the handshake — with **no password prompt shown**, because the Companion had already answered it. The operator saw a wrong-password error on a world they were a citizen of, and clearing the world's password "fixed" it by making both sides empty. `db_gets.php:240` had predicted this failure in a comment, for the caller next to it. No schema change, no world update, no new client. A world whose password was cleared as a workaround can have one set again in Settings → Options. ### The verify marker that let it through `cpd`/`cpe` read *"the ternary is gone from BOTH launch string builders"* and grepped two named files. Both read `0` on the build that shipped the bug, because neither looked at the third caller — and `CLAUDE.md` enumerated the same two files. A count-the-known-sites check cannot see a site nobody counted. Replaced by `v54a`, which greps the whole served tree (excluding `vendor/`) for either the ternary or the literal passed into the builder, so a fourth caller cannot be added without tripping it. `v54b`/`v54c` assert positively that the two admin callers read the real column, since deleting the line would satisfy the negative while sending an empty password — the same failure with a different cause. All three were checked against the broken original before shipping: `v54a` reads 1 and `v54b` reads 0 on 2.53's code. ## v2.53 ### Fixed: the download menu could offer an unreleased client `getGitReleases()` was named for releases but read git **tags**: ``` git ls-remote --refs --tags $repo | cut -d/ -f3- | sort -V -r | head -N ``` A GitHub pre-release creates a tag, and the client build commits its artifacts to `master`, so a tag plus a committed file was enough to hand every player an unreleased build. The 2.0.14 pre-release was being offered on a live server while 2.0.13 was still the published release. Nothing in the chain ever asked whether a version was published — the flag was not ignored, it was never consulted. It now reads the releases API and excludes `draft` and `prerelease`. Three states are kept distinct: a list of published versions, an **empty** list (a real answer — nothing is published yet), and a failure. A failure never renders as "none" and never falls back to tags, because falling back to tags is the bug. On a failed lookup a stale cache is served if one exists; otherwise the menu says no published release is available instead of rendering blank. The answer is cached for an hour, which is not optional: unauthenticated GitHub allows 60 requests an hour and this runs on every render of the player page. Guarded by `dev_tools/test-client-release-source.php` (20 checks) and five in-image markers (`cqo`–`cqs`). Two things that test found, both kept as comments: - only the API response was being sorted, not the cache read — and the cache is what callers hit almost every time, so a patch to an old version published after a newer release would have gone out as "the latest client". Every return path now goes through one sorter. - the pre-release filter was inlined in the HTTP function, so it could not be driven without a network and the only coverage was a grep for the word `prerelease` — a check that passes whether or not the flag is honoured. Split out as `phvPublishedVersionsFromApi()` and driven with the recorded API response. Mutation-checked: deleting the `prerelease` check fails 3 assertions, the `draft` check 2, the sort 1. ### Fixed before release: crossplay no longer blocks listing in the server browser A pre-release of 2.53 refused `listed` together with `crossplay` — on both write paths and at the form, where the switch greyed out with a note claiming a crossplay world has no address to advertise. That was never measured. Crossplay worlds have been listed successfully on real servers since 2.40, so the block removed a working feature, and the counterexample was sitting in the database the whole time: a world already saved with `crossplay=1 listed=1`, which the new rule declared impossible and which was written off as an anomaly instead of read as a refutation. A password remains listing's only requirement; Valheim genuinely refuses to start `-public 1` without one. Both layers of the removed block are now pinned out of existence by build markers (`cpf`, `cpfb`), and `dev_tools/test-crossplay-any-world.sh` asserts the three settings compose. That test had itself been passing for the wrong reason — it still carried the pre-2.53 "listing is forced off on a modded world" assertions, which held only because the refusal meant nothing was saved. ### The in-game dialog is in PhValheim's colours, and its button works The Companion's dialog is PhValheim's voice inside Valheim, so it now uses PhValheim's palette rather than Valheim's. Every colour is read from `:root` in `phvalheimStyles.css` and lives in exactly one place in the mod (`Theme.cs`); `dev_tools/test-client-manifest.sh` re-reads the stylesheet and fails the build if the two drift, so re-theming the web UI cannot leave the in-game dialog behind. A control for the retired parchment colours is part of that check, and it earned its place: it caught two sites the first theming pass missed. The panel keeps Valheim's own art. An attempt to repaint it was reverted before release: it identified the panel's background as the largest `Image` under the popup, which is in fact a full-screen overlay, and rendered as a full-screen box with a border and no text. The mod now logs the popup's real Image tree instead — paths, sizes, sprites and sibling order — so a future reskin can target the background by name rather than by guessing at sizes. The notice is reachable again from a **Connect: ** entry on the main menu — the prefix in magenta, the world name in PhValheim's cyan. **Fixed: that entry never appeared, the plain button that appeared instead was dead, and once it did appear it started the game.** Three separate faults in the same small feature. The predicate deciding whether to build the entry contained a term that was always false once the dialog had been shown, so it was never built; an IMGUI fallback drew in its place, and IMGUI buttons do not receive clicks in Valheim; and the entry is cloned from a live menu button whose handler is wired in the Unity Inspector, which `RemoveAllListeners()` does not remove — so the clone also did whatever the button it was copied from did. Each of the three had a test asserting the right code was being called, and each of those assertions was true while the bug was live. The lesson taken into the test suite is that a call list proves a call happens, not that a branch runs or that the call has the effect assumed — so the decision is now a pure function driven by a truth table, and the handler check is anchored on the call that actually disables a persistent listener. The predicate deciding whether to build the button included a term that was always false once the dialog had been shown, so the real button was never created and an IMGUI fallback drew in its place — and IMGUI buttons do not receive clicks in Valheim. The decision is now a pure function driven by a truth table, because the previous test could only prove the code was *called*, not that the branch was *reachable*. **The notice can also be brought back without a button.** Close it, leave the main menu and return, and it is offered again. This exists because the reopen button has failed on a real client in three forms — an IMGUI button that drew and never received a click, and twice a cloned native button that was never created — and every one of those depends on an input path, a canvas or a reflected field that cannot be verified from a build host. Returning to the main menu depends only on the menu's own active state, which is the same read that already decides whether the notice may appear at all. The cloned button is still attempted, and now names in the log which gate refused when it cannot be made. Also fixed, both caught by `dev_tools/test-dialog-layout.sh` rather than by shipping them: the launch-help notice ended with a dangling blank line that cost a real rendered line in a panel that only has six, and a long failure message wrapped onto a second line because the cap the layout test's own fixture was named after had never actually been written. ### The Companion ships with the server The PhValheim Companion is no longer published to Thunderstore or Hexium. It ships inside the image and is installed by `installSystemPlugins()`, the same path that already carried `PhValheim-TickMonitor` and `ZeroBandwidth-CustomSeed`. It is PhValheim's own infrastructure — it posts to the PhValheim backend and reads PhValheim config, so it has no audience outside this server — and bundling it makes the server and the Companion one artifact that cannot be version-skewed against each other. That skew was the only reason the catalogue-capability machinery existed: `companionConnectMinVersion`, `companionModIdentity`, `versionAtLeast()` with its `sort -V` prerelease carve-out, and a SQL probe of `mod_versions` are all gone, replaced by one build flag. **QuickConnect is retired in this release.** `companionProvidesConnect` is `1`: the bundled Companion does the joining now, and QuickConnect comes off a world the next time it is updated. The flag is why this is safe to flip rather than delete: a required mod missing from the catalogue only produces a `[WARN]` and the world is built *without* it, so retiring QuickConnect before the Companion could connect would have produced modded worlds with no way to join them and a warning in a log nobody reads. `dev_tools/test-companion-bundled.sh` fails if the flag disagrees with the Companion's actual connect support, in either direction — which is what makes the flag a gate and not a comment. The Companion came out of `requiredMods`, and the migration deletes the `world_mods` rows every existing world still holds for it — otherwise an upgrader would install the Thunderstore copy on top of the bundled one, two DLLs with the same BepInEx GUID in one `plugins/` folder. The mod dropped its Newtonsoft dependency (one `JsonConvert.SerializeObject` call on an object with two string fields) and now builds as a single self-contained 10,752-byte DLL. Bundled, a Newtonsoft reference would have meant shipping a second copy of that assembly beside whatever another mod bundled. ### Per-mod install destinations: Server and/or Client Every mod on a world now carries `deploy_server` and `deploy_client` flags (`world_mods`, both `NOT NULL DEFAULT 1`). A dependency inherits the **union** of its parents' destinations — erring toward installing is the only rule that cannot starve a mod of a dependency, and a dependency missing from a side where its parent runs is a BepInEx load failure that never names the dependency. This required splitting the server's live tree from the client payload. Until now `packageClient()` zipped `game/BepInEx` wholesale, so the two were the same directory — which is why 2.49's loss of one `BepInEx.cfg` broke the world log and the client console together. Mods now install into `game/` and/or a new `client/` staging tree, and the payload is built from the staging tree. The mod picker gained an **Installs on** column: a Server and a Client switch per selected mod, in both `new_world.php` and `edit_world.php`. Both are on for anything selected, so nothing changes for an existing world — both flags default to 1, and the install plan for a world at those defaults is byte-identical to the one the previous `worldMods.py` produced, verified by diffing against `git HEAD` across a 229-mod closure. A dependency the operator did not tick shows the word *derived* rather than a computed pair: the picker's `reverseDepMap` is one level deep, so a pair displayed there would be wrong for anything further down a chain. `walk_closure()` walks the closure transitively and is the only thing that decides. Turning both switches off unticks the mod instead of storing one that installs nowhere. Also: the derived `client/` tree is excluded from backups (it is rebuilt on every world update, and including it roughly doubled a modded world's archive every 30 minutes), and `packageClient()` now returns `zip`'s exit status rather than the `rm` that followed it, so a failed package no longer reports success. ### Retiring QuickConnect, derived rather than declared The crossplay work above leaves QuickConnect unable to do its job: its config file is `world:host:port:password` and a PlayFab world has no `host:port`. The PhValheim Companion — already a required mod on every modded world — takes joining over, and QuickConnect is retired. **The retirement is derived at world-build time, not hardcoded.** This is the whole design, and it is forced by how `requiredMods` behaves: `mergeRequiredTsMods()` resolves each entry against the **mod catalogue**, and a required mod that is not there produces a `[WARN]` and then builds the world *without* it. Deleting QuickConnect from that list would therefore, on any server whose catalogue has not yet seen a connect-capable Companion, produce modded worlds **with no join path at all** — and a warning as the only evidence. That is not a thing to be careful about; it is a thing to make impossible. So `companionSupportsConnect()` asks the catalogue, every time, whether a Companion at or above `companionConnectMinVersion` (1.1.0) is actually resolvable: - **capable** → Companion only; no QuickConnect, no `quick_connect_servers.cfg` - **absent or older** → QuickConnect exactly as before, cfg written as before, plus one NOTICE naming which path the world got and what is holding up the other This makes the server safe to ship **before** the mod is published, makes the cutover automatic when it is, and degrades an unsynced catalogue to the old working path rather than to a world nobody can join. It is deliberately **not** gated on `phvalheimVersion`: the server's version says nothing about what is in the catalogue, and the catalogue is what worlds install from. `versionAtLeast()` uses `sort -V`, because `1.10.0` is alphabetically *less* than `1.9.0`. Prereleases are then handled explicitly, because `sort -V` alone ranks `1.1.0-rc1` **above** `1.1.0` — so a bare version compare would have let a release candidate silently become every world's only join path. A prerelease of exactly the minimum is rejected; one of a later version is accepted. Both writers of `quick_connect_servers.cfg` consult the same verdict — `phvalheim` and `importWorld.sh` — so an imported world cannot end up the one way to get a cfg nothing reads. `createQuickConnectConfig()` itself stays an unconditional writer: `test-gamedns-quickconnect.sh` lifts it and calls it directly, so gating it internally would have quietly neutered that test rather than failing it. The engine's stale-`gameDNS` repair block was expected to become dead code here and **does not**. `worldHost` still feeds the fallback `createQuickConnectConfig()` call and the `external_endpoint` the admin UI displays, so it stays exactly as it is. ### Telling operators before it happens A one-shot `connectNoticeShown` dialog explains, on first login after upgrading, that joining has moved, that **each existing modded world must be updated once**, that **updating a world stops it**, and that nothing breaks by waiting. It copies the `huginNoticeShown` pattern across the same five sites, and `?? 1` is load-bearing in both the read and the markup: an undefined variable is `null`, PHP evaluates `null == 0` as true, and the gate tests `== 0` — so a missing default shows the dialog on every page load forever. It is seeded from the **modded** world count rather than the total. 2.40 and 2.42 use the total to answer "has this server run an older version"; this asks "does this server own anything the change affects", which has a different answer on a vanilla-only server. Fresh installs and vanilla-only servers are seeded quiet. Getting this backwards is how 2.31 and 2.35 shipped the setup wizard to the wrong audience twice. ### Crossplay on modded worlds `-crossplay` was restricted to vanilla worlds, and the restriction was enforced in **five** places: the argv gate in `startWorld.sh`, `saveWorldOptions` and `createWorld` in `adminAPI.php`, and the two admin forms. All five are removed. The restriction was never a Valheim limitation. It was a **client** one, and on re-examination it was not even that. The reasoning had been: crossplay makes Valheim open a PlayFab server, which has no `host:port`; the PhValheim client reaches a modded world through the QuickConnect mod, whose config file is `world:host:port:password`; therefore a modded crossplay world starts fine and cannot be joined. Every step of that is still true. What it misses is that **connecting was never the client's job on a modded world.** `Launcher.cs`'s modded path passes no connect argument on any platform — Windows gets `-applaunch 892970 --doorstop-*`, Linux execs `valheim.x86_64` directly, macOS the same with `DYLD_*`. The client installs the mod payload and injects BepInEx; joining has always been a separate in-game step that happened to be served by QuickConnect. So the client works **unmodified** on a modded crossplay world: it installs the mods, Valheim comes up modded, and the player joins from Valheim's *Join by code* box instead of QuickConnect's server list. Client 2.0.13 needs no change and gets none — it has no crossplay or join-code code at all. QuickConnect's entry for a crossplay world points at a `host:port` that cannot answer. It is inert rather than harmful, and both UIs say not to use it. **The launch link therefore survives on a modded crossplay world, which is the opposite of the vanilla case.** `getVanillaJoinInfo()` returns `href => NULL` for crossplay because there is genuinely nothing to launch; the new `getModdedJoinInfo()` beside it always returns the `phvalheim://` link, and additionally returns the join code when the world is on PlayFab. Both admin call sites now share it — the modded branch used to be an inline literal that ignored crossplay entirely, which was correct only while crossplay could not be set on a modded world. Passing `-joincode` was considered and rejected for the second time: `FejdStartup` registers `AutoJoinServer()`, which resolves the code and calls `JoinServer()` without ever calling `SelectCharacter()`, so the player lands as **"Odev (Developer)"** on a character they never made. There is no argument that stops at character selection. ### The half of the fix that was nearly missed `effectiveCrossplay` was computed **inside** the `if isVanilla` branch that writes `.running-options`. Removing only the argv gate would have handed a modded world `-crossplay` and recorded `crossplay=0` — and since everything describing a *live* world reads that file, every UI would have drawn a direct-connect link and no join code for a PlayFab server. That is the same one-card-two-sources-of-truth bug the file was introduced to fix, with the flags reversed. `listed` and the password hash stay inside the branch, because a modded world is still started `-public 0` with no `-password`. `api.php` now emits a `connection` block for modded worlds too, and the public page's 5-second poll derives `isPlayFab` without the `world.vanilla` gate. Without both, a modded world's join code was correct on page load and frozen thereafter — the code is reissued on every restart. ### The disclaimers are part of the feature Enabling crossplay **removes direct IP connection entirely**, for every player: there is no address to connect to, everyone joins by code, and the forwarded UDP port stops being used. Stated in both option descriptions and on the card. The one that can ruin a world gets its own callout, shown only when a world is modded *and* crossplay is on: **console players cannot load mods.** Xbox, PlayStation and Switch players can join, but BepInEx does not run on those platforms, so they play unmodded against a modded server. Server-side mods are fine; anything adding items, creatures or recipes, or changing the network protocol, can make the world unplayable for them or drop them on join. The advice is to use mods sparingly, and that server-side networking mods are a good fit. The world log repeats it, so it survives the dialog being dismissed. ### Tests `test-crossplay-vanilla-only.sh` asserted exactly what this release removes and is replaced by `test-crossplay-any-world.sh`, every case paired with a control — an implementation that stores `crossplay=1` for everything passes half of them, and so does one that still forces `0`. `test-startWorld-args.sh` gains the inverted argv assertions plus `.running-options` coverage, and `test-crossplay-join-modal.js` gains the modded case, whose point is that the link must *still be launchable*. Every new marker and assertion was checked against the pre-2.53 tree to confirm it fails there. Four did not on the first attempt: three build markers and one test regex used a single `.` to stand for a quote in `[ "$isCrossplay"` and `'phvalheim://?' . $launchString`, where two characters sit before the name. They matched neither tree, so they could not fail. ### Access control, decoupled from world type `password`, `listed` and `crossplay` now apply to any world. A modded world can be password protected and published in Valheim's server browser, and the CITIZENS allowlist still applies on top — Valheim enforces `permittedlist.txt` server-side regardless of what the client runs, so the two compose rather than one replacing the other. What unblocked it was the Companion, not a server change. A modded world's password had nowhere to go: nothing on the client side could answer Valheim's password prompt, so the player would be asked for something the UI had never shown them. `ConnectFlow` pre-fills `FejdStartup.ServerPassword` from field 2 of the launch payload — which has carried the password since the format existed — so Launch joins without a prompt. **No payload change**, and every client/server pair stays compatible: a 2.0.13 client forwards the field untouched. `startWorld.sh` loses the `isVanilla` gate around `-public`/`-password`, and `effectiveListed` and `effectivePasswordHash` follow crossplay out of that branch. Left inside, a modded world would have recorded `listed=0` and an empty hash, and the restart-pending check — which reads `passwordhash` — would compare a real password against `""` and answer "nothing changed". A badge no operator action could clear. ### `serverblankpassword` was never doing anything Decompiled from the un-publicized assembly: `FejdStartup.ParseServerArguments` calls `IsPublicPasswordValid` **only when `-public` is set**, and answers a failure with `Application.Quit()`. `startWorld.sh` has always started a modded world `-public 0`, so the validation that mod patches out has never run on one. That makes its removal safe for a world that still has no password, and it is now actively wrong to keep: a world that *can* be published should not carry a mod suppressing the requirement publishing depends on. It is out of `requiredMods`, which leaves the list empty — the Companion left it in the same release. `mergeRequiredTsMods()` only ever INSERTs, so the conf change does nothing to existing worlds; a one-time block in `dbUpdate_2.53.sh`, modelled on the QuickConnect retirement above, deletes the rows and generates a 16-character password for every modded world that had none. One-time behind `settings.blankPasswordRetired`, for the QuickConnect reason: nothing in the schema distinguishes "PhValheim inserted this" from "the operator picked it". **The password is generated when a world is UPDATED, not when PhValheim is upgraded**, by `ensureModdedWorldPassword()` in the update path. The first cut put it in the migration, and that was wrong in the way that hurts: a world is password protected at its next *restart*, while it is still running QuickConnect and its players are still on a client that cannot forward a password. Everyone is locked out of a world the operator has not touched, and it contradicts what the rest of 2.53 promises — nothing changes until you update a world. Brian hit it upgrading 2.52 → 2.53. Deleting the mod *row* at upgrade is not the same hazard and stays there: a row only decides what the next rebuild installs, so a world that merely restarts keeps the plugin files it already has. Launch-path players never see the password; anyone joining by address, and console players on a crossplay world, need it — so the modded world card grew the same masked password row the vanilla card has, and the modded card now gets a PASSWORD pill. A world that already has a password keeps it, and the function only ever fills an empty one. Two things `-public` also taught us, both recorded as markers rather than comments: it **defaults to 1 when absent**, so losing the explicit argument would list every world *and* switch on password validation for all of them. ### The mirror that goes stale, a second time `savedWorldOptions()` in `db_gets.php` exists to mirror `startWorld.sh`'s gating, because the restart-pending badge compares what the server was *handed* (`.running-options`) against what the operator has *saved* (the database). Decoupling access control moved `startWorld.sh` and left the mirror behind, so for every modded world the saved side computed `passwordhash => ''` while the running side correctly carried a real hash. The badge reported "password" on every poll, and **no restart could clear it** — restarting only re-confirms the running side. Three of four live worlds on `:rc`, immediately after the upgrade generated their passwords. This is the second time in 2.53 that this file lagged `startWorld.sh` in exactly this way; crossplay was the first, and the comment left behind by that fix *claimed* `startWorld.sh` still gated listing and password — which had stopped being true in the same commit that read it. The mirror now has no gates at all, which is what both sides agree on. `test-restart-pending-mirror.sh` is the test that was missing. Every earlier test checked one side; this one runs the real `startWorld.sh` to produce a real `.running-options`, feeds it to the real PHP comparison with a database row saying the same thing, and asserts the verdict is "nothing pending" — so it fails if either side grows a gate the other does not have, without needing to know what the gate is. Against the broken tree it fails 4, including the latent `listed` case that had not bitten yet. It carries four controls that a genuinely changed setting is still reported, because a mirror returning a constant — or a `runningWorldOptions()` whose path resolved nowhere — would pass every case otherwise. ### Two password rules Valheim enforces and we did not `IsPublicPasswordValid` rejects a password contained in the world name **or in the seed name**. `validateWorldPassword()` had the first and not the second, so a password containing the seed passed the form and made a listed world `Application.Quit()` — a clean exit, so supervisor restart-loops it with the reason buried in the world log. Live for vanilla worlds before this release. The function now takes the seed; an empty one means Valheim has not written the `.fwl` yet, so the rule is skipped and re-applied on the next save. A `?` is refused too, and that one is ours. The launch payload is `?`-delimited and **positional**, with the password at field 2, so a `?` shifts `gameDNS`, `port`, `vanilla`, `crossplay` and `joinCode` by one for every parser. Nothing errors — each hands the wrong value to the wrong name. It was inert only while modded worlds sent the literal `hammertime`; sending real passwords makes it live. Listing is refused with crossplay on, at the form rather than as a warning: `-public` lists Steam servers, and a crossplay world is a PlayFab server with no address to list, so the listing reaches nobody and Valheim reports nothing. ### Tests `test-password-rules.php` drives the real `validateWorldPassword()` out of `adminAPI.php` and covers all four rules. Checked by mutation: dropping the seed rule fails 3, dropping the `?` rule fails 3. It also carries a control that the function can say *yes*, without which a validator rejecting everything would pass every rejection case. `test-blankpassword-retirement.sh` executes the retirement block itself with `sql()` stubbed, and asserts on the statements it emits. This block writes passwords to live worlds and runs exactly once, so there is no second chance and no way to tell afterwards whether a world was skipped; nothing else in the suite touches it, because migrations only run inside a container against a real MariaDB. Checked by mutation: generating 8 characters instead of 16 fails 2, removing the one-time guard fails 1, and one password shared across every world fails 1 — that last mutant needed a second attempt, because the first used a 15-character constant that the length guard rejected before the uniqueness assertion could see it. `test-startWorld-args.sh` had an assertion demanding the opposite of this change — it pinned `listed=0` and an empty hash for a modded world. Replaced with the new expectation plus a control that a modded world with neither set still records neither, so the pair cannot both pass against something that hardcodes `listed=1`. `test-companion-bundled.sh` used `serverblankpassword` as its proof that `requiredMods` was not empty. With the list now legitimately empty, that control is dead: it reads `legacyConnectMods` the same way instead, so an empty `requiredMods` is a real answer rather than a grep that matched nothing. It also asserts `serverblankpassword` is gone. The build markers are anchored on code, not prose. The first drafts of two of them matched comments — `-public 0` and `hammertime` both still appear in this release, in the comments saying why they are gone — so they would have passed on a tree where the behaviour was reverted and only the explanation survived. ### The password is generated at world UPDATE, not at upgrade The first cut generated every modded world's password inside `dbUpdate_2.53.sh`, so it happened the moment the container came up. That breaks a server mid-flight: a world still running QuickConnect, with players on clients older than 2.0.14, acquires a password that nothing on the player's side can answer, and it acquires it before the operator has done anything or seen a single notice. The review document had argued for update-time and the implementation did upgrade-time anyway; Brian caught it on a live server. Generation moved out of the migration into `ensureModdedWorldPassword()`, called from the engine's update branch after `mergeRequiredTsMods`. The migration still deletes the retired mod rows, which is safe because those rows only take effect at a world's next rebuild. The rule for the whole release is now uniform: **nothing changes about a world until you update it.** ### The notices, and two things they got wrong `clientUpdateNoticeState` is a **tri-state** — 0 not triggered, 1 pending, 2 dismissed — because "has not happened yet" and "the operator dismissed it" are different answers and a boolean cannot hold both. Collapsing them fails in one of two directions: the dialog appears on a server that has updated nothing, or it returns after every world update forever. `test-client-update-notice.sh` asserts both directions, and evaluates the real gate expression in PHP rather than grepping for it. Two wording defects shipped before the final build. The connect notice described QuickConnect as being retired "once a Companion that can do the job is available in your mod catalogue" — there is no such lookup; the Companion is bundled with the server. And the client-update dialog opened with "You have updated a world", which is false on any server with `autoupdate_mode` set: auto-update runs the same path unattended, so the dialog arrives having been triggered by nobody. Both are now agent-neutral, and the test carries a negative assertion against the "you did it" phrasing. `dev_tools/resetNotices.sh` re-arms these one-shot flags for testing. Each notice declares its own armed value, because arming the tri-state means writing 1 — writing 0 would say "nothing has happened yet" and the dialog would not appear. ### The client manifest, and an in-game notice for a client that cannot join Brian found the hole by playing the part: an updated 2.53 world, a 2.0.13 client, and no Companion dialog at all. Valheim started to a plain main menu with nothing on screen tying the silence to PhValheim. `FejdStartupPatch` returned early on `!LaunchPayload.Present`, which was right when the payload was the only reason the dialog existed — no `--phvalheim-launch` meant the game had not been started by PhValheim, and a single-player deserved no interruption. From 2.53 that same state also covers a player whose app is too old to pass the argument, and for them the world now has a password and no QuickConnect entry, so the silence is the difference between joining and not. The Companion is the only component that can still be fixed for an already-shipped client: it travels inside the world payload, so an old client receives a new one on its next world update without being updated itself. `writeClientManifest()` puts a `phvalheim-world.cfg` beside the dll in the client staging tree — world, host, port, crossplay, `clientMinVersion` and the client download URL — and `ClientManifest` reads it back. Written before the zip, or it would ship in the *next* payload and describe the world as it was one update ago. **No password in it, deliberately.** argv lives for one process; this file lands on every player's disk and stays there. The notice says where to read the password instead. **It cannot know whose fault it is, so it does not say.** "Manifest present, no payload" has two causes and nothing in the game process can separate them: an app older than the handoff, or any app at all plus a player launching Valheim from Steam on an install PhValheim set up — the client installs into `steamapps/common/Valheim`, so BepInEx loads the Companion either way. An "your app is out of date" banner is false for the second player, and telling someone something untrue about their own machine is how a helpful notice becomes a bug report. The body states the requirement — "start it from the PhValheim app, version 2.0.14 or newer" — which is true of both. A `ShowLaunchHelp` config entry turns it off for good, because no amount of cleverness in here can separate the two and the single-player should not have to care. `dev_tools/renderDialog` grew launch-help cases, and earned its keep immediately: the first draft of the body explained both causes in prose and rendered **fifteen** lines against a panel budget of eight. Without the harness that would have shipped as a screenshot of text running off the bottom of the panel — the third time this release that a dialog's real geometry disagreed with how the markup read. It also caught a non-oracle assertion of my own: `stripped.Contains(world)` passes vacuously when the world name is empty, which is exactly the state the parser refuses, so a mutant that accepted a nameless manifest reported four `ok`s. **Two things the smaller panel broke, both mine.** The header ended up half outside the box. `HeaderLiftScreen` and its two siblings were being divided by the *active* scale alongside the fonts, and a position does not scale like a size: `60/1.5` is **40** local units against `60/2.0`'s 30, so the smaller panel got the *bigger* shove and the title was pushed out of the top. These are offsets in the panel's own local space, which is identical at every scale, so the correct local value is a constant. They are now `HeaderLiftLocal`/`BodyLiftLocal`/`ButtonPullLocal`, and `renderDialog` calls each at both scales and requires the same answer — with a control that the two scales genuinely differ, without which the whole check would pass vacuously. And the reopen button stopped working for the no-payload player. `OnGUI` called `Show()` directly and set `_shown = true`, which has no retry in it: `UnifiedPopup` silently drops a push it is not ready to accept, and with `_shown` already true `Update()` never tried again — one click and the way back was gone for good. It now clears `_shown` and lets `Update()` show it on a frame when `IsReadyToShow()` says yes, which is the path that puts the notice up in the first place and the only one proven to work. Asserted as a negative: `OnGUI` must not call `Show`. **The notice is a `WarningPopup` in a smaller panel.** Removing the second button left the first one off centre, because it was still the *right* button of a pair — and pulled further off by `ButtonPull`, which exists only to close the gap a scaled-down pair leaves. The fix was not another screen-space nudge: `UnifiedPopup.ShowWarning` activates `buttonCenter`, labels it from `UnifiedPopup.okText` and centres it itself — read out of its IL rather than assumed — so the notice uses Valheim's own single-button popup and needs no geometry of its own. The left-button hiding is gone with it, and so is the risk of leaving a vanilla dialog a button short. `PanelScale` is 2.0 because the connect dialog carries eight lines plus a scrolling mod list; the notice carries five and no list, so at 2.0 it was a vast box around a short sentence. It now lays out at `HelpPanelScale` 1.5, with every styling method reading a runtime `_activeScale` instead of the constant so the two dialogs share one copy of the arithmetic. The body budget has to move with the panel — the inner height scales while the text stays a fixed screen size — so `HelpBodyLineBudget` is 7, and `renderDialog` now asserts the *relation* between the three numbers rather than trusting them to be edited together. That check exists because the mutation found the gap: setting the help scale back to 2.0 produced **zero** failures, since the budget was a constant the harness took on faith. The restore checks got tighter for the same reason. `RestorePopupSkin calls SetPrivateField` passed a mutant with the `okText` restore deleted — it could not tell *which* field was being put back, and the method restores `yesText` and `noText` too. Anchored on `_savedOkText`, which nothing else reads, it fails. **The "Get the app" button is gone, and so is the URL that fed it.** It opened `settings.phvalheimClientURL`, which is a single text field whose default has pointed at `phvalheim-client-installer.exe` since `dbUpdate_2.31.sh` — so on Linux or macOS the button handed the player the wrong installer, and Brian did not recognise the file it offered him. Choosing the right artefact per platform is not something the server can do from one URL, so the button went and `clientUrl` left the manifest with it: a field nothing reads is an orphan, and an orphan here would invite the button back. The notice's left button is now hidden rather than given a second job — and the restore is asserted separately from the hide, because `UnifiedPopup` is a shared singleton and a left button left inactive would vanish from every later yes/no dialog in the game, vanilla's included. Dropping that restore fails `test-dialog-reachability.sh`. **It then shipped unreachable, and every cheap check passed.** Three gates decide whether the notice appears: `FejdStartupPatch.SetupGui` attaches the component, `ConnectDialog.Update` decides whether to call `Show()`, and `Show()` picks which dialog to build. Gates 1 and 3 were updated. Gate 2 still read `if (!LaunchPayload.Present) return;` — four lines below a comment block describing the very feature it blocked — so the Companion loaded, found its manifest, and returned early forever. Brian updated a world, launched it on a 2.0.13 client, and got exactly the silence the feature exists to end. Nothing available at build time could see it. The dll contained every new string; the manifest was written and was inside the payload zip; eight verify markers were green. All of them ask *is the code present?* and none can ask *is it on a path that runs?* A source grep cannot answer it either, which is why `dev_tools/test-dialog-reachability.sh` reads the **IL** of the built assembly instead: a method that does not `call ClientManifest.get_Present` is not deciding anything about the manifest, whatever the source looks like. It asserts all three gates, plus three controls that the two modes have not been dissolved into each other (`OnConnect` must *not* consult the manifest; the help dialog must *not* read the payload, which in that mode is null). `apiProbe` gained an `APIPROBE_ASSEMBLY` override so it can dump IL from our own assembly rather than only the game's. The dll that shipped in the first `:rc` is the control: it fails the new test on exactly the one real defect, and passes the other eleven checks. `dev_tools/test-client-manifest.sh` runs that reachability test against the dll **this repo ships**, not the Companion's build output — those are the same file only if someone remembered to copy it, and that copy is precisely the step that fails silently. A missing Companion tree is reported as a failure rather than skipped. `dev_tools/test-client-manifest.sh` checks the server half, including that the call is not chained into the zip's control flow — a payload lost over a missing explanatory file would be worse than the silence it replaces. Mutation-checked in four directions: writing the manifest after the zip, adding a password line, hardcoding the version instead of reading the config, and shipping the previous Companion dll each fail it, and the dll mutation fails it three ways. ### The modded card's password row was unstyled Five of the password-row CSS rules were scoped to `.catbox-vanilla`. A modded world's card is a plain `.catbox`, so it matched none of them: the markup was correct and identical, and it rendered with no spacing and no show/hide or copy affordances. The second time this scoping has bitten in one release. The rules are de-scoped and the dimmed variant now keys on `.card_dimmed`; `test-password-row-styling.js` measures computed style on a rendered page rather than asserting on the stylesheet text. ## v2.52 ### The mod catalogue stopped refreshing after the first boot `modSync.py` is run by **two different uids**: root at container boot, via the engine's `syncModCatalogue()`; and `phvalheim` from `cron.d/modSync` hourly and from the admin UI's per-catalogue forced sync, which `exec()`s out of PHP-FPM. `take_global_lock()` opened its two lock files with `open(path, "w")`, and `"w"` needs write permission in order to truncate. The boot sync runs first and always, so `/tmp/phvalheim-modsync.run.lock` was created `root:root 0644`. `/tmp` is sticky, so `phvalheim` could neither truncate that file nor unlink it, and every later sync died with `PermissionError: [Errno 13]`. The forced link surfaced a traceback; **cron failed silently**, hourly, into `modSync.log`. The catalogue still refreshed at every container restart — which is why it looked almost current rather than broken. Introduced by `09b2aff3`, the fix for the 668-lost-dependency-edges incident, and live in **every published release from 2.47 to 2.51 inclusive**. `open_lock()` replaces both call sites. `flock(2)` honours `LOCK_EX` on a **read-only** descriptor, and a lock file's contents are never read, so write permission was never actually needed — truncation was the only thing asking for it. The already-affected servers self-heal on upgrade with no cleanup step: the root-owned `0644` file left behind is world-readable, so `phvalheim` locks it as-is. **`O_CREAT` is passed only when the file is genuinely absent, and that detail is load-bearing.** The first pass used `os.open(path, O_RDONLY | O_CREAT)` unconditionally and the new cross-user test went red in the *reverse* direction — root refused on a `phvalheim`-owned lock. That is Linux's sticky-directory hardening (`fs.protected_regular`, default-on since ~2019): `may_create_in_sticky()` rejects an `O_CREAT` open of an existing file in a world-writable sticky directory unless the file's owner matches the caller or the **directory's** owner, and `CAP_DAC_OVERRIDE` does not bypass it. `/tmp` is owned by root, which is exactly why the originally-reported direction happened to work and the reverse one did not — and 2.52 makes every lock `phvalheim`-owned. A plain `O_RDONLY` is not subject to the check at all. ### One uid for all three triggers `0-functions.sh` now launches the boot sync as `setsid su phvalheim -s /bin/sh -c '…'`, so the engine stops being the odd one out. This also closes a second, independent cross-uid bug in the same file: `already_running()` reaps stale `mod_sync_runs` rows with `os.kill(pid, 0)` and maps `PermissionError` to `alive = True` — a correct conservative default that only became reachable because of the uid split. A row left `running` by a root boot sync whose pid had since been recycled returned `EPERM` to `phvalheim`, which read as "a sync is alive" and skipped the run. `HOME` is `/opt` and is **not** writable by `phvalheim`; `modSync.py` needs no `HOME`, and cron has run it as this user with this same `HOME` all along, so parity is proven rather than hoped for. Not `su -`: a login shell resolves to the same unwritable `/opt`. The sync stays backgrounded, keeps `--trigger boot` (the interval is enforced for `trigger=cron` only), and still never passes `--force`. ### The same shape, swept out of four other tools This was a class, not an instance — every fixed-path `/tmp` state file written by a tool that can run as either uid. `pushAnalytics.sh` wrote `/tmp/phvalheim_analytics_payload.json` and `/tmp/phvalheim_analytics.tmp` at fixed paths, and runs as root from the engine and as `phvalheim` from cron and from the analytics toggle. Its `rm -f` cleaned both on the happy path, so it only wedged when a root run died before reaching it — a hung or killed `curl`. Both are now `mktemp`, on the `EXIT INT TERM` trap that already covered the other three scratch files. `updateApplier`'s `exec 9>`, and the `echo $$ >` pidfiles in `worldBackup` and `worldRestore`, all move to the same read-only `flock` idiom. Only `phvalheim` invokes these today, so the uid split is defensive here — but the pidfile scheme had its own failure modes that were not: a recycled pid reads as "still running" forever, and `kill -0` across uids returns `EPERM`, which read the same way. `worldBackup` loses its `trap rm -f … EXIT`, because unlinking a file another run is about to open yields two holders on two inodes, which is not a lock; and it now closes fd 9 in the backgrounded `gzip`/`zstd` so a compressor can never outlive the script holding it. `worldRestore`'s `jsonError()` no longer removes the lock file either — on the "another restore is already in progress" path it had been deleting the **running** restore's lock, leaving the next caller free to start a second concurrent restore. ### Tests `dev_tools/test-modsync-lock.py` passed throughout all five broken releases and could not have failed: every case runs as one uid in one process, so a cross-uid permission difference is invisible to it. Its docstring now says so, and says where the cross-user cases belong. `dev_tools/test-modsync-lock-crossuser.sh` is the new oracle — docker-based, because the whole bug is two uids. Root-creates-then-`phvalheim`-takes (the reported direction), `phvalheim`-creates-then-root-takes (the direction that caught the `O_CREAT` mistake), an exclusion control proving the lock is still genuinely a lock, and boot-path uid parity. Both mutations were checked: reverting `open_lock()` turns cases 1 and 2 red, reverting the `su` turns case 4 red. Marker `fo`, from 2.43, was anchored on the literal string `setsid /opt/stateless/engine/tools/modSync.py`. Inserting the `su` split that string in half, so the grep matched nothing, the pipe counted nothing, and `fo` read `0` — its own want value. It would have gone on passing while asserting nothing at all about `--force`. Re-anchored on the launch itself. No DB migration, no schema change. ## v2.51 ### A Flatpak download for the client The Linux entry in the public page's client download popover offered three packages — the universal `.tar.gz`, a `.deb` and a `.rpm`. phvalheim-client has shipped a fourth since its 2.0.13 release, `phvalheim-client--x86_64.flatpak`, and nothing linked to it. That is the package that matters on an immutable distribution. On SteamOS and Bazzite there is nowhere to install a `.deb` or an `.rpm` at all, so the only route was the raw tarball. The Flatpak also carries its own runtime, which covers the `Couldn't find a valid ICU package` failure a minimal install hits — the `.deb` and `.rpm` declare no dependencies, and a self-contained .NET build still needs the system libicu. `includes/clientDownloadButton.php` gains a fourth `` in the Linux branch, and `images/flatpak.svg` is a new 32×32 asset drawn to sit in the same row as `win11.png`, `ubuntu.png` and `fedora.png` under the existing `brightness(75%)` treatment. The first release candidate shipped that asset **undrawable**. Its header comment ended with a doubled hyphen, which XML forbids inside a comment, so the file was present, the right size, owned correctly — and refused by every browser, leaving a blank gap in the popover. The existence marker passed the whole time; it could not have failed. `ws` now parses the file the way a browser would, and `wt`/`wu` sweep every SVG in the image against a count they derive themselves, so the pair cannot rot as artwork comes and goes. **The link is gated on the client version.** `$clientVersionsToRender` is `1`, so in practice only the newest tag is ever rendered and that tag has a Flatpak — but it is an operator setting, and raising it is the entire point of it. Every client tag before 2.0.13 has a `.msi`, a `.tar.gz`, a `.deb` and a `.rpm` in `builds/` and no `.flatpak`, so an ungated link would 404 for each of them. `PHVALHEIM_CLIENT_FIRST_FLATPAK` is the floor and `version_compare()` is the gate; older tags render exactly the three packages they did before. ### The Flatpak icon opens instructions, not a download The other three packages are self-explanatory — double-click the `.deb`, extract the tarball. A `.flatpak` bundle is not: it needs `flatpak install --user ./`, and on a bare window manager (Hyprland, Sway, i3) it needs a second one-off command putting Flatpak's exports directory on `XDG_DATA_DIRS`, without which **clicking a world's launch link does nothing at all, silently**. Handing someone the file alone reproduces that failure. So the Flatpak icon opens `#flatpakInstallModal` — four numbered steps, each with a brief explanation and a copy button, and the download button in the footer. `href` and `target` stay real, so ctrl-click and *Save Link As* still download directly; only the plain click is intercepted, via `return openFlatpakInstall(this)`. **The commands live in one place.** `FLATPAK_CMDS` in JS is the only copy; the `` blocks are empty in the markup and filled by `textContent` when the modal opens, and the copy buttons read the same object. The macOS modal keeps two copies — a shortened one on screen, a hidden full one for the clipboard — which are free to drift apart. This one cannot. `openFlatpakInstall()` is handed the anchor and reads the download URL off it, deriving the filename in the install command from the same string it puts on the download button. The modal is never told a version, so it cannot contradict the link it was opened from. Two things this depends on, both already true and both load-bearing: the popover is built with `sanitize: false` (Bootstrap's default allowList strips `onclick`, which would make the icon a plain download again), and `bootstrap.Modal.getOrCreateInstance()` is already used elsewhere on the page. The modal markup sits at page top level beside `#macInstallModal`, not inside the popover's table. ### Labels and spacing All four Linux icons said "Download". They now say what they are — Universal, Ubuntu, Fedora, Flatpak — and Windows says Windows. `td.client_download_cell` adds 9px either side. No engine, database or API change. Nothing on an existing player's machine changes. ## v2.50 ### A failed Valheim update was reported as a success, and that disabled the retries Reported from a world log that read, in order: ``` Error! App '896660' state is 0x6 after update job. [NOTICE : phvalheim] Valheim server installed successfully for 'Brotality' ``` `InstallAndUpdateValheim()` decided whether steamcmd had worked like this: ```sh # Check if valheim_server.x86_64 was installed if [ -f ".../game/valheim_server.x86_64" ]; then steamcmdSuccess=true echo "... Valheim server installed successfully for '$worldName'" fi ``` `StateFlags` `0x6` is `StateFullyInstalled|StateUpdateRequired` — Steam has the files on disk and still considers the app to need an update. The server binary is therefore present in exactly the failure this check exists to catch, so it returned the same answer whether the update had completed or not. A non-oracle: it could never go red. **Second-order damage.** `steamcmdSuccess=true` is also the loop condition. Setting it on a failed run broke out of the retry loop on attempt 1, so the five retries never ran for the one fault they were written for. The operator got a single failed attempt, labelled a success. **The fix.** Two new functions in `0-functions.sh`: - `valheimAppStateFlags()` reads `StateFlags` out of `game/steamapps/appmanifest_896660.acf` — the manifest steamcmd writes for itself, and the same file `updateChecker.py` already reads the installed buildid from. Not a new dependency; an existing one asked a second question. - `valheimInstallVerdict()` returns **three** states: verified (0), did not complete (1), installed-but-unverifiable (2). The third is not folded into either of the others — a missing manifest is unknown, and refusing to run a world over it would be a worse bug than the one being fixed. `StateFlags` is a bitmask, so "is it 6" is the wrong test. Success requires `0x4` set and every not-done bit clear (`0x1|0x2|0x8|0x20|0x80|0x100|0x200|0x400|0x800` = 4011). The first cut of this patch checked only bits `0x4` and `0x2`; `dev_tools/test-steamcmd-install-verdict.sh` caught that state 12 (update queued) and state 36 (files missing) were still verifying as clean. `0x10 UpdateOptional` is deliberately outside the mask — an optional update on offer says nothing about whether this install finished, and failing on it would stop healthy worlds. A run that fails all five attempts now also logs `df -h` for the worlds volume. A partial steamcmd update leaves state `0x6` and no other clue, and the usual cause is simply a full disk. **Tests.** `dev_tools/test-steamcmd-install-verdict.sh` drives the shipped functions against fixture manifests (states 4, 6, 12, 36, 1, 20, no-manifest, no-binary). Mutation-checked: reverting `valheimInstallVerdict` to the bare existence test turns 5 of the 10 cases red. ### World creation was gated on a chown exit status, and deleted the world when it failed Found while investigating an unrelated report. `phvalheim` decided whether a new world had deployed like this: ```sh chown -R phvalheim: $worldsDirectoryRoot/$worldName RESULT=$? if [ $RESULT = 0 ]; then # ...created... else deleteWorldModRows "$worldName" SQL "DELETE FROM worlds WHERE name='$worldName'" rm -rf /opt/stateful/games/valheim/worlds/$worldName fi ``` `chown -R` answers "could I change ownership of every file I walked". That is not "did this world deploy", and the two come apart in both directions: **one** unchownable file — NFS `root_squash`, an immutable bit, a file vanishing mid-walk — destroyed a world whose deployment had gone fine, while an incomplete but chownable tree passed as created. This is the third appearance of the same bad oracle. `InstallAndUpdateValheim` carries a comment describing it exactly, from when it turned a successful update into "update failed"; there it printed a wrong message. Here it deleted the world. The branch also handles **clones**, whose directory arrives already holding a copied save. The `chown` was additionally redundant: `worldDirPrep()` ends with that identical command and runs immediately above on this path. It existed only to set `RESULT`. **Two changes.** `worldDirIsPrepared()` asserts the postcondition — the six directories `worldDirPrep` is contracted to produce — and names any that are missing. And a failed deployment is now **marked `mode='broken'` and otherwise left alone**. `broken` is the state this engine already uses at three other sites, none of which delete anything; the create branch was the outlier. A deleted row is indistinguishable from a world that never existed, so the operator watched their world vanish with the only explanation in the engine log. Removing the `rm -rf` also deletes a second, partial implementation of "remove a world" — it skipped the orphan-PID kill and `deleteSupervisorWorldConfig` that the real delete path does. Two implementations of one operation drift; the UI's Delete already does it correctly. **Tests.** `dev_tools/test-world-deploy-verdict.sh`, 13 assertions. The oracle case is a complete tree containing a file that cannot be chowned: the old code destroyed that world, and it is a perfectly good deployment. Mutation-checked against restored chown-gating. Three of that test's first-run failures were **its own probes**, not the code: two markers matched the new comments, which quote `rm -rf` and `RESULT=$?` verbatim while explaining the bug, and the fixture for "missing `game`" recreated `game` via `mkdir -p` of the savedir beneath it. Both the test and the build markers now read the engine with comments stripped. ### Escalating self-repair, and the reason it is not a reinstall Restoring the retries exposed the next problem: five attempts ran the *identical* command against *identical* state, so they could only produce the identical failure. The retries were honest but useless. `healSteamcmdState()` now escalates. Level 2 resets the steamcmd bootstrap and repairs ownership and permissions on the game tree; level 3 additionally discards a partial transfer; level 4 additionally drops the manifest, forcing a full re-verify. Each step logs what it did. Permission repair is at level 2 deliberately — it is the cheapest real fault to fix, it is non-destructive, and `docs/RELEASING.md` already records steamcmd failing for want of a writable `HOME` as a trap this project has hit before. **The constraint that shaped the whole function.** `startWorld.sh` passes ``` -savedir /opt/stateful/games/valheim/worlds/$worldName/game/.config/unity3d/IronGate/Valheim ``` **The world save lives inside the game directory.** So does `BepInEx`. The obvious implementation of self-healing — wipe the game dir and let steamcmd reinstall — would have deleted every world save on every server that hit a failed update. Everything the repair touches is therefore confined to `game/steamapps` plus the two steamcmd bootstrap dirs, and the function carries a comment saying so in the imperative. **Tests.** `dev_tools/test-steamcmd-self-heal.sh`, 32 assertions. The survival cases are the real subject: saves, world db, `permittedlist.txt`, BepInEx plugins, the loader config and installed game content are asserted intact at *every* level, plus an empty-world-name guard. Mutation-checked: replacing the repair with `rm -rf "$game"` turns 22 cases red, the first six being the data-loss ones. The build gate additionally asserts the repair function never so much as names `unity3d`, `BepInEx` or `savedir`, and pins its `rm` count at 5 so a sixth cannot be added without someone re-reading the path list. ## v2.49 ### The world log stopped naming loaded plugins, and the client's BepInEx window stopped appearing Two symptoms, one deleted file. `BepInEx/config/BepInEx.cfg` is the **loader's** config. The loader is engine-installed on every modded world (2.44+) and is deliberately not a mod — but its config was being treated as one. `purgeWorldModsConfigsPatchers()` clears mod configs on every world rebuild so a removed mod cannot leave a stale one behind, and it did this: ```sh rm -rf $worldsDirectoryRoot/$worldName/game/BepInEx/config/* ``` That runs at `phvalheim:457`, three lines after `InstallAndUpdateBepInEx()` installs the pack at `:454`. So the pack's cfg was laid down and immediately deleted, and nothing restored it before the world booted or before the client payload was built. With no cfg, BepInEx regenerates one from its **stock defaults, where `[Logging.Console] Enabled = false`**. One setting, two visible consequences: | | how it breaks | |---|---| | World log | BepInEx's console logger writes to **stdout**, and supervisor captures a world's stdout into `valheimworld_.log`. Console off ⇒ the world log never sees BepInEx, so no `Loading [Plugin x.y]` lines. | | Client window | `packageClient()` zips `./BepInEx` wholesale. No cfg on the server ⇒ no cfg in the payload ⇒ the client's console window never opens. | Mods were loading correctly throughout. Only the reporting of it was gone — which is why this looked like two unrelated regressions rather than one. **Fixes** - `purgeWorldModsConfigsPatchers()` clears mod configs with a scoped `find ... ! -name 'BepInEx.cfg' -delete`. Mod configs and their subdirectories go exactly as before; the loader's own config stays. - `InstallAndUpdateBepInEx()` stashes the pack's `BepInEx.cfg` to `game/bepinex_default.cfg` before the unpacked pack directory is removed. It cannot rely on `rsync -purval` to deliver it: `-u` skips any file the world already has with a newer mtime, and BepInEx rewrites its cfg on every boot. - New `ensureBepInExLoaderConfig()` restores the cfg when missing (from the stash, else a minimal one) and asserts `[Logging.Console] Enabled = true`, scoped to that section — `[Logging.Disk]` has an `Enabled` key too. Called from `phvalheim` after `installCustomModsConfigsPatchers()` and before `packageClient()`, so it is the last word before the payload is built. It is idempotent and skips vanilla worlds entirely. Already-affected worlds repair themselves on the next rebuild. ### Changing Game DNS never reached quick_connect_servers.cfg Open for years. `worlds.external_endpoint` was stamped from `gameDNS` when a world was **created** and never touched again — the column had **two INSERTs and zero UPDATE statements in the entire tree**. The engine read that frozen copy into `$worldHost` and handed it to `createQuickConnectConfig()`, so editing Game DNS in Server Settings changed nothing a player would ever see through QuickConnect. What made it so hard to pin down: the **Steam launch string reads `gameDNS` live** (`admin/index.php:120`, `adminAPI.php:914`) while **QuickConnect read the frozen column**. After a DNS change one join path worked and the other didn't. Reproduced live before changing anything: ``` BEFORE settings.gameDNS=valheim.example.com midgard endpoint=valheim.example.com (admin changes Game DNS) AFTER settings.gameDNS=newdns.example.org midgard endpoint=valheim.example.com engine would feed createQuickConnectConfig: worldHost=valheim.example.com ``` **Fixes** - `phvalheim` takes `worldHost` from the **live `$gameDNS`**, falling back to the stored column only when `gameDNS` is unset (setup wizard unfinished) — so it can never write an empty host. - The update path now runs `UPDATE worlds SET external_endpoint='$worldHost'` immediately before writing the cfg, so the setting, the file and the admin UI display cannot drift apart again. This is what makes "update your worlds" a real remedy rather than advice. - **`importWorld.sh` never assigned `$worldHost` at all** — it expanded to nothing, so every imported world got a `quick_connect_servers.cfg` with an **empty hostname** and a QuickConnect entry that could not resolve. It now uses the same `gameDNS` the INSERT already stores. **A second read of `gameDNS` that was not live.** The first fix above read `$gameDNS`, which the engine sets **once at startup**: ```sh export gameDNS=$(SQL "SELECT gameDNS FROM settings") # line 84, engine boot only ``` The engine is a long-running process — weeks between restarts — so that variable holds whatever Game DNS was when the container last booted. Worse, the main loop opens with `source /etc/environment`, and that file is written once at boot from `printenv`, so it actively **re-imposes** the stale value on every pass. A world updated right after a DNS change still got the old hostname written into its cfg, with every other part of the fix working correctly. `gameDNS` is now re-read from the database on every loop pass, **after** the environment source — placed before it, the refresh is silently undone. It stays exported because `importWorld.sh` and the other spawned scripts read it too. **The notice.** The cfg is only rewritten when a world is updated, so changing the setting alone still isn't enough. Saving a *changed* Game DNS now raises a blocking dialog saying every world needs updating before players get the new address. It fires only on an actual change, and it blocks the page reload — a status line would have been wiped a second later by the reload, which is part of why this went unnoticed for so long. ### Tests `dev_tools/test-gamedns-quickconnect.sh` — models the engine's update path and pins its assertions to the engine source, including a NEGATIVE that the frozen read survives at exactly one site (the fallback). Three cases fail against the pre-fix code. ### Related, and worth knowing `denikson/BepInExPack_Valheim` **5.4.2350** (2026-09-09, BepInEx core 5.4.23.5) carries upstream fixes for this same area on Unity 6 — Valheim 1.0 runs `v6000.0.61f1`, and its stripped Unity log callbacks used to take the chainloader down: ``` * v5: Don't kill the chainloader when Unity log callbacks are stripped (#1392) * Fold the two Unity 6 log writer probes into one * Fix logging issues in UnityLogListener.cs for Unity 6 ``` `InstallAndUpdateBepInEx()` compares `bepinex_version.txt` against the feed's latest, so a world still on 5.4.2333 picks 5.4.2350 up at its next update. No code change was needed for that, and it is not what caused either symptom. ### Tests `dev_tools/test-bepinex-loader-config.sh` — seven cases, all of which fail against the pre-2.49 code: the purge keeping the cfg while still clearing mod configs, restore-from-stash, the no-stash fallback, the section-scoped console flip (asserting `[Logging.Disk]` is untouched), appending a missing section, idempotency, and leaving vanilla worlds without a BepInEx tree. ## v2.48 ### Restoring a backup generated a fresh world (issue #89) Every world backup taken since 2.38 restored into the wrong directory, so the server found no save at its `-savedir` and generated a new world. The restore reported success. `worldRestore` supports two archive layouts, and picked between them like this: ```sh tar tf "$backupFilePath" | grep -q "worlds_local/" && isOldFormat=1 ``` **Both layouts contain `worlds_local/`.** They differ only in where it sits, because the two generations of `worldBackup` archive from different directories: | | archives from | `worlds_local/` appears at | |---|---|---| | pre-2.38 | `$worldDir/game/.config/unity3d/IronGate/Valheim` | `./worlds_local/` — archive root | | 2.38+ | `$worldDir` | `./game/.config/unity3d/IronGate/Valheim/worlds_local/` | Unanchored, that `grep` matched every modern archive too. So every restore took the legacy branch and unpacked the whole world tree into `$worldDir/game/.config/unity3d/IronGate/Valheim/`, leaving the real save at ``` /game/.config/unity3d/IronGate/Valheim/game/.config/unity3d/IronGate/Valheim/worlds_local// ``` one full world tree below where Valheim looks. The `-savedir` `worlds_local` was empty, so Valheim did what it does with an empty save directory: generated a new world. The 2.38+ branch was unreachable code — it had never run in any release. The probe is now anchored to the archive root, which is the actual distinction: ```sh grep -qE '^\./worlds_local/|^worlds_local/' ``` It is a function, `archiveListingIsLegacy`, so the regression test exercises the shipping code rather than a copy of it. ### Recovering worlds already damaged (step 5b) Fixing the probe stops new damage but cannot help a world already restored by 2.38–2.47: that world directory is nested, and since automatic backups run every 30 minutes, **every backup taken since is nested too**. Unpacking one of those correctly still leaves the save buried and still boots a fresh world, so an affected operator had no route back through the UI. A world directory can never legitimately contain `.../IronGate/Valheim/game/.config/unity3d/IronGate/Valheim` — a real Valheim save directory holds `worlds_local/`, `cache/` and the access lists, never another `game/` tree. That doubled path is an unambiguous signature of the old bug, so restore now lifts the buried tree back to the world root. Each pass peels one level and the loop is bounded, so a world damaged by two successive bad restores (nested three deep) also recovers. No data was ever deleted: the save was inside the archive the whole time, and the pre-restore safety backup taken before every restore still holds the state from the moment it happened. ### Verification Verified on the shipped image, not only in the harness. On a fresh 2.48 container, for a vanilla world and a modded one (BepInEx + NoMovementPenalty), each generating its **own** Valheim save: - backup **and** restore driven through the real admin HTTP API (`nginx` → `php-fpm` → `adminAPI.php` → `startDetachedJob`), with the job polled the way the UI polls it; - the restored save byte-identical by `sha256`, and **still byte-identical after the live engine finished the post-restore `mode='update'` rebuild** — the rebuild does not clobber it; - BepInEx and the selected mod reinstalled by that rebuild; - Valheim then **loaded** the restored world (`ZNet.LoadWorld`) with its seed preserved, where the pre-fix code generated a new one (`LDDQYb6tzP` → `JQrJyFl97b`); - all three archive formats — `.tar`, `.tar.gz`, `.tar.zst` — restore byte-identically, the last of which exercises the separate `eval` branch; - `backupDir` on its own mount whose `st_dev` matches its parent's, which is the condition that broke backup detection in 2.42; - and the reporter's whole chain: healthy backup → the **real pre-fix code** buries it → the 30-minute automatic backup captures the nesting → 2.48 restores that nested archive and returns every original byte. Two log lines are *not* evidence of loading and were discarded as oracles: `Loading: Generating locations` appears on loaded worlds too, and a freshly generated world loads `0 zdos`. The seed in `_main.N.fwl2` is the discriminator, because generation always changes it. Guarded by `dev_tools/test-restore-format-detection.sh`, which extracts both the probe and the repair loop out of `worldRestore` itself. Re-introducing the unanchored `grep` fails 6 of its checks; deleting the repair fails another. ## v2.47 ### Player counts Valheim gives a dedicated server no reliable live player count, and three of the four obvious ways to get one do not work here: - **Socket enumeration** — the server serves every peer from one unconnected UDP socket, so there is nothing per-peer to enumerate. - **conntrack** — `/proc/net/nf_conntrack` is absent (netlink only), the `conntrack` CLI ships in neither the host nor the image, and a *bridged* container's conntrack table does not contain the host's DNAT entries. Reading them needs host netns or `NET_ADMIN`, which cannot be required of an image other people run on Unraid, K8s and plain Docker. - **The TickMonitor plugin** — already computes a correct count via `ZNet.GetNrOfPlayers()` and already writes it to `tick_stats.json`, but it is a BepInEx plugin and vanilla worlds have no BepInEx to load it. What does work splits by the world's `crossplay` flag, and the split is not cosmetic. A crossplay world logs an absolute count on every join and leave (`… now N player(s)`). A non-crossplay world logs `Connections N` every ten minutes, with `Got connection SteamID` / `Closing socket` filling the gaps. `Connections N` reads **0 on a crossplay world with a player connected** — verified against a real session — so using it everywhere would have reported every crossplay world as permanently empty and restarted servers out from under players. Two traps are guarded in code and pinned by tests: - `Closing socket` is logged **twice** per departure, the copies differing only in the run of spaces after the timestamp. Measured on a real log: 24 lines, 12 departures. Stripping leading whitespace does nothing — the difference is mid-line. - `player_count_at` stores the **log line's** timestamp, never the scan time. A nonzero count can stick after everyone leaves (observed: 39 minutes). A scan-time column would refresh every two minutes, never look stale, and make auto-update wait forever on an empty world. Counts appear on the admin world rows always, and on the public page per world by opt-in. Both say *approximate*, and nothing anywhere claims a world is "empty". ### Automatic game and mod updates (#87) Off by default; upgrading changes no behaviour until it is switched on. `updateChecker.py` records what is available and never applies anything. The published Valheim buildid is fetched **once per run** with `app_info_print` and compared against each world's own `appmanifest_896660.acf`, so N worlds cost one steamcmd call rather than N downloads. Mod updates come from comparing `world_mods.installed_version_id` — what the installer actually put on disk — against the catalogue's current `latest_version`. **Pinned mods are excluded entirely**: not counted, not reported, never updated. A cold check costs ~31 seconds, essentially all of it steamcmd signing in; `app_info_update` accounts for none of it. The published buildid is the same for every world, so it is cached in `settings.publishedBuildid` for 15 minutes — cold 32.4s, cached 0.40s, measured. steamcmd also needs an explicit `HOME`: it runs as the `phvalheim` user, whose inherited home is not writable, and without one it dies before printing anything. `updateApplier` decides only *when*. Every gate must say yes and anything unestablished counts as no: a world with no player observation at all is never considered idle. A backup is taken first by default, and a failed backup abandons the update rather than proceeding without a way back. Stopped worlds are untouched — they update on next start, as before. Per-world overrides mirror the backup system exactly, including that a global "on for all worlds" does not overrule a world explicitly set to off. ### Recording what is actually installed Update detection first hung off `worlds.modsViewer`. That was wrong, and wrong in a way that looked right: `modsViewer` is the **display cache** behind the admin UI's mod dropdown, and every version in it comes from `effective_version()` — the live catalogue. Comparing it against the catalogue compared a number with itself, so it could only ever answer "up to date". It gave correct answers purely because both of its writers sit immediately after a mod install; anything that refreshed it at some other moment would have silently rewritten every "installed" version to whatever was newest and blinded every world, permanently. So the fact is recorded rather than derived: ```sql world_mods.installed_version_id -- mod_versions.id; immutable, so a catalogue resync world_mods.installed_at -- cannot rewrite history underneath us ``` Written by exactly one thing — `worldMods.py --record-installed`, called from `downloadAndInstallTsModsForWorld()` with the ids of the mods that actually landed. `--plan` gained a ninth column (`mod_id`, **appended**, so the four scripts that read fields 1–5 with awk are untouched) to carry those ids out to the installer. The two columns carry **three** states, and all three are load-bearing: | `installed_at` | `installed_version_id` | meaning | | --- | --- | --- | | NULL | NULL | never recorded → **unknown** | | set | NULL | known **not** installed — a duplicate plugin `by_plugin()` collapsed away | | set | set | comparable | Collapsing the middle case into the first is the same can't-tell-the-difference bug pointing the other way: after a clean rebuild, a world with one collapsed duplicate would sit on "waiting for data" forever, and every modded world has at least one such row. A mod whose install **failed** is left untouched — its previous copy is still in `BepInEx/plugins`, so its previous recorded version is still true. **No backfill.** Nothing on the box knows which version of a plugin is sitting in a world's `BepInEx/plugins` — the extracted folders carry no `manifest.json` — so any value written would be a guess wearing the costume of a fact. NULL is the true answer, the UI says *waiting for data*, and a world's next mod rebuild records the real versions. ### Nothing claims "up to date" without checking Three separate gaps all rendered as the same reassuring green, because a `0`/false default silently doubles as a real answer: 1. steamcmd could not run, so no published build → a world thousands of builds behind read as current. 2. A world's mod versions were never recorded → the loop skipped every entry and the count came out 0. **28 of 35 worlds on one real server.** 3. The world had never been checked at all — both columns `DEFAULT 0`. **26 of 35.** Each now has its own state in the schema (`update_check_error`, `update_mods_error`, a gate on `update_checked_at`) rather than being reconstructed in the UI. A pending state reads as muted *waiting for data*, not a red *could not check* — nothing is broken. Also fixed: the Updates tab drew **two Mods rows**. A leftover unconditional block sat after the never-checked gate, so a never-checked world showed a muted "waiting for data" and a green "up to date" one line apart — two contradictory answers to the same question, in the same panel. ### Rebuild Mods A per-world button in the Updates tab, beside the *waiting for data* message. Worlds built before version recording have nothing to compare, and no amount of checking will change that; reinstalling their mods is what records it. Per-world and manual on purpose — a rebuild stops the world, and a world whose mod list no longer resolves is left stopped by design, so doing this to two dozen worlds unattended could take a server down overnight. Worlds also fix themselves the next time their mod list changes. ### Tests `dev_tools/test-playerMonitor.sh` (9), `test-updateApplier.sh` (16), `test-updateChecker.py` (19), `test-record-installed.py` (18) — 62 in total. Each case is one where a plausible wrong implementation gives a different answer than the right one, and the new ones are mutation-checked: collapsing either of the three installed-states, suppressing a confirmed update because some other mod is unrecorded, and re-reading the display cache each fail the suite. Verified against a real database as well as in unit tests — a synthetic 36-mod dependency closure built from the live catalogue, covering a simulated failed install, a rewound version, a pin, and a recorded-but-not-installed row. ## v2.46 ### What Hugin is told about passwords Reported in Discord: Hugin said a server was not using a password and was gated by its access control list, and the operator did not believe that was their setup. Hugin was right. `startWorld.sh` reads the password column but consumes it only inside the `isVanilla = 1` branch — a modded world is started with `-public 0` and no `-password` at all, and entry is gated by `permittedlist.txt` alone. The admin UI still accepts, stores and displays a password for a modded world, which is why the answer was surprising rather than wrong. Driving the real tool loop against a live provider turned up three defects in what the model is handed, all in `includes/aicontext.php`: **`password_public` is not a password.** It is a `TINYINT` controlling whether the password is shown on the public world card. It was being redacted as a credential, and because both `"0"` and `"1"` are `!== ''`, it reported `(set — redacted)` *either way*. That destroys the boolean and invents a second credential — which a live model duly described to an operator as "a separate password used for the public/spectator view". It is now passed through as `show_password_on_public_card`, an int. **A NULL password skipped redaction entirely.** The guard was `isset()`, which is false for NULL — the column's default — so the commonest case went out as a bare `"password": null` while an empty string became `"(not set)"`. Now `array_key_exists()`, so both read alike. **Nothing said a password is vanilla-only.** `has_password` and `password_in_effect` are now on both `list_worlds` and `get_world`; the second is false on a modded world whatever the first says. `list_worlds` previously carried access-control state and no password state at all, so a question about how the server was secured could only be answered from half the data. The vanilla/modded password rule also moved into `DOMAIN FACTS`. It had lived only in `OPERATING PROCEDURES`, which `aiSystemPrompt()` omits when the model cannot act — so a read-only Hugin was never told it. Guarded by `dev_tools/test-ai-password-context.sh`: 17 assertions on the JSON the tools actually return, not on the source. 14 of them go red against 2.45. ### The Hugin panel, measured against a small model Driven against the real DeepSeek v4 Flash provider on the production box rather than reasoned about, because the complaint was "the formatting isn't very pretty" and the causes turned out not to be the model. **The renderer was the problem, not the model.** `aiMd()` had no table support at all, so a side-by-side comparison — which a small model reaches for constantly — arrived as rows of literal `|` characters. Nor did it handle `---`, `>` quotes, indented sub-bullets, lists numbered from anything but 1, or a code fence the model opened and never closed (every truncated answer). Every heading level rendered identically. All of that now renders, with column alignment, and `dev_tools/test-ai-markdown.js` asserts on the HTML using fixtures pasted from real replies — 29 assertions, 20 of which go red against 2.45. The three escaping assertions in there are load-bearing: `aiMd()` is the only thing between model output and `innerHTML`. **Small models narrate their investigation into the answer.** A health summary opened with three to five paragraphs of "let me check…", "now I have enough…" before the first real sentence. Three changes, in order of how much each can cost: - the client now discards any prose that arrived *before* a tool call. A tool call is proof the model was still investigating, and the trace strip already records what it looked at. - the system prompt says not to narrate. Helps; does not stop it. - `aiStripNarration()` removes leading process talk from the final round, which has no tool call after it to key off. Deliberately conservative — it only fires on leading, structure-free, first-person process talk, and returns the original if everything looks like narration, so the worst case is 2.45's output rather than an empty bubble. The second pass (cut to the first heading) additionally requires **two or more** narration paragraphs, which is what keeps a normal lead-paragraph-then-heading answer intact. `dev_tools/test-ai-narration.php` — 19 assertions, and the nine KEEP cases are the real specification, since this function deletes text the operator asked for. `done` now takes the server's content even when it is *shorter* than what streamed. It was taken only if longer, as a guard against a dropped delta — which would have thrown the strip away and kept the narration. **The working strip is pinned to the bottom.** It was the first child of a growing bubble, so on any answer longer than the panel the raven, the phrase and the timer scrolled off the top exactly when the wait was longest. Now `position: sticky`, which works because `.ai-message.assistant` is a column flexbox, and it leaves with its own bubble. ### Hugin was reading the wrong column for "is this world running" Reported from the panel: Hugin insisted a world the operator was standing in was stopped, and explained its live log as history. `worlds.status` is not a running indicator. On the production box: | status | mode | count | |---|---|---| | `Down` | `stopped` | 31 | | `Down` | `running` | 2 | | `failed` | `stopped` | 2 | `status` is the literal string `Down` for **all 33 worlds**, including the two whose `valheim_server` processes were live at that moment. `worlds.mode` is the column the engine maintains and the one `admin/index.php` renders from — and there the two `running` rows were exactly the two with processes. `aiTruthy($row, 'status')` was used as "is it running" in six places, so it was permanently false: - the prompt injected `0 running, 33 stopped`, plus the line telling the model that every world being stopped is the server's resting state — which is how a live world got described as stopped; - `stop_world` and `restart_world` refused **every** world with "already stopped", so nothing could be turned off through Hugin at all; - `start_world` would have started a world that was already up; - `aidiagnose` downgraded every finding to history and skipped the restart-loop and backup-freshness checks for precisely the worlds that were serving players. All six now go through one predicate, `aiWorldIsRunning()`, which reads `mode`. `status` is still reported, because it carries a signal `mode` does not — a world whose last start attempt failed reads `mode=stopped, status=failed`, and `list_worlds` now says "stopped (last start failed)". `get_world` also stops calling its `mode` field running/stopped while `list_worlds` calls its own field vanilla/modded; both now mean vanilla/modded, with running state in `status` and a `running` boolean. `aiTruthy()` itself was fine and is untouched — it is still correct for the boolean columns (`public`, `vanilla`). Only the running check was pointed at the wrong field. Guarded by `dev_tools/test-ai-world-state.sh`, whose fixture is the production shape — `status='Down'` **with** `mode='running'`. That combination *is* the bug; a fixture that set `status='Running'` for a running world would pass against the broken code and prove nothing, which is how this shipped in 2.45. 13 of its 15 assertions go red against 2.45. **Two things that were simply missing.** The default provider could only be changed by re-running the whole Add-provider wizard over an existing row; there is now a "Make default" button per provider, backed by `aiProviderSetDefault()` — its own one-field endpoint rather than a partial `aiSaveProvider()` call, which would have blanked the label, endpoint and model of the row it was promoting. It refuses an unknown id, because clearing the flag and then failing to set it would leave the registry with no default, which the panel cannot open in. And `.mods-modal-footer` had no CSS rule at all, which is why Back and Next sat hard against the dialog corners. ## v2.45 ### The AI Helper stops holding opinions about which models exist (issue #83) Reported as "Gemini models are retired/deprecated": `models/gemini-2.0-flash` was gone and the helper still asked for it. Bumping the string would have been a fix with a shelf life of weeks. The defect is that a model id was a constant in our source at all. 2.44 carried **three** hardcoded model tables. `getAiProvidersJson()` held one for the picker, `aiHelperDispatch()` held a second for validation, and the validator did this: ```php if (!in_array($model, $allowedModels[$provider])) { $model = $allowedModels[$provider][0]; // operator asked for X, silently got Y } ``` So the failure was not only "our default is stale" but "a *correct* model the operator typed gets replaced by a stale one, with no error". Both tables are gone. Every supported provider publishes its catalogue over HTTP — `GET /models` (OpenAI-compatible), `GET /v1/models` (Anthropic), `GET /v1beta/models` (Gemini), `GET /api/tags` (Ollama) — so we ask, cache for 6h, and send whatever the operator picked **verbatim**. A model that discovery has never heard of is used as entered, with a warning, never a substitution. `dev_tools/test-ai-helper.sh` token-strips the AI sources and fails the build if a model-id shape reappears in live code. Verified by mutation: reintroducing the 2.44 constant, the silent rewrite, the swallowed error text, a weakened path check and a mutating tool are each caught. ### A provider is a row, not a hardcoded case `settings` held exactly four AI columns: one OpenAI key, one Claude key, one Gemini key, and `ollamaUrl` — which had **no key field at all**, so a self-hosted vLLM or LM Studio behind `--api-key` was unusable. Providers now live in `ai_providers`, so an operator can configure any number of them, several of the same kind, each with its own endpoint, credential, extra headers and pinned model. `openai_compatible` covers vLLM, LM Studio, llama.cpp, OpenRouter, Groq, Together, DeepSeek, Mistral and xAI with one adapter. `dbUpdate_2.45.sh` migrates the four columns into rows and deliberately does **not** carry the model across — the only ids 2.44 could have stored are from its own stale tables, `gemini-2.0-flash` among them. Leaving it empty forces live resolution on first use, which fixes #83 for upgrades and not just fresh installs. The legacy columns are kept as a rollback record; `pushAnalytics.sh` was the one live reader left and now reads `ai_providers` instead. A migration that changes no read sites is how the 2.43 world-card mod counts broke, so the test suite greps for stragglers. ### The assistant can look things up instead of being handed one log Context was `tail -200` of a single file pasted into the system prompt. It could not follow a lead, compare two worlds, check whether the thing it was blaming was even configured, or see further back than 200 lines — so the most common real answer, *"the failure is above the window you were given"*, was unreachable by construction. There are now ten read-only tools: list/search/read any log (whole file, not just the tail; `since_last_start` for a world), world config, the resolved mod install plan, catalogue sync state, backups, host health, and the diagnostics below. Log paths resolve through `realpath()` containment inside `/opt/stateful/logs` — `basename()` alone stops traversal but not a planted symlink. Nothing mutates: a wrong answer should waste the operator's time, never their world. Each reply shows which tools it called. ### A health scan that needs no model at all `aidiagnose.php` is pure PHP pattern matching over the logs and database, run before any LLM call. It reports mod load failures, missing dependencies, mods configured but never loaded, the 2.39 permission class, Steam download storms, port conflicts, restart loops, overdue backups, failed syncs, low disk and stopped services — each with the lines that triggered it. Three reasons it exists: the helper is useful with nothing configured; a small local model handed evidence does well where the same model handed 200 raw lines hallucinates; and the expensive model reasons about findings rather than scrollback. It also flags a world whose `permittedlist.txt` is **enforced but empty** — Valheim only enforces that list when it has entries, so an empty one is a wide-open server whose Access tab says otherwise. ### What a real Gemini key found that a mock could not Tested against the live API. Discovery returned 40 models and `gemini-2.0-flash` — the model 2.44 hardcoded and issue #83 reported — is **absent**. The current generation is `gemini-3.8-flash`; the fix the issue itself suggested (`3.6-flash`) would already be one behind. Three defects surfaced that an OpenAI-shaped mock is structurally unable to show: **Tool calling was broken on every current Gemini model.** Gemini 3 attaches a `thoughtSignature` to parts and *requires* it back on `functionCall` parts. The adapter rebuilt each part from name+args, dropping it, so the second round trip died with *"Function call is missing a thought_signature in functionCall parts"*. Plain chat worked, which is why nothing looked wrong. The model turn is now replayed verbatim — Google's own guidance — via an opaque `provider_raw` that `aiConverse` passes through untouched and other adapters ignore. **An empty `args` object became a JSON list.** `json_decode($body, true)` turns `{}` into an empty PHP array, indistinguishable from `[]`, and `json_encode` emits `[]`. Every no-argument tool call replayed as `"args": []` and was rejected: *"Proto field is not repeating, cannot start list."* The replay copy is now decoded as `stdClass`, which round-trips exactly. **The wizard's connection probe asked for 16 output tokens.** On a reasoning model that budget is consumed by thinking before any visible character, so the step passed while rendering `Replied:` and nothing — measured at ~150 thinking tokens for a one-word question. Raised to 512, and an empty-but-successful reply is now reported as a warning explaining why rather than as a blank pass. Also worth knowing: **discovery listing a model does not mean the key can use it.** `gemini-2.5-flash` is still advertised by `/v1beta/models` but returns *"no longer available to new users"* on `generateContent`. The wizard's separate chat round trip is what catches this, at setup time, instead of it becoming a confusing chat error later. ### Three more found by pointing a real model at a real server A live Gemini key against a booted container, asked open questions about the engine log and two broken worlds. **The tool loop gave up while it was winning.** `aiConverse` capped at 6 rounds, and the model investigates in *parallel* — an open "full health check" produced twelve tool calls, two per round, hit the cap, and returned an error blaming the model (*"try a stronger model"*). The work was done; only the answer was missing. The cap is now 10, and on exhausting it the loop makes one final call **with no tools**, forcing an answer from what was already gathered. The system prompt also tells the model to answer as soon as it can support an answer rather than gathering everything that might be relevant. **`get_world_mods` had never worked.** It selected `m.version`; the newest version is denormalised onto `mods` as `latest_version`, so the tool returned *"Column not found: 1054 Unknown column 'm.version'"* every single time. The mock provider only ever called `get_diagnostics`, so nine of the ten tools had no coverage at all. The e2e now executes every tool directly and fails on error-shaped output. **The new dbUpdater error line was itself the bug.** Treating every non-0/1 exit as a failure printed 13 ERROR lines on every boot of a *healthy* server, because the older migrations end with a deliberate `exit 2` meaning "already applied". The AI Helper then read them, believed its own instructions, and reported *"CRITICAL: Engine Database Update Failures"* advising the operator to hand-edit the database. Noise that looks like a fault is a fault. `2` is silent again; `126`/`127` — a script that genuinely cannot run — stay loud, which is the case that mattered. ### A migration that could not run, and said nothing Found by booting the first 2.45 RC rather than by reading it. `dbUpdate_2.45.sh` was committed mode `660`; `dbUpdater.sh` invoked each migration as a bare path, which needs the execute bit, so it exited **126**. That matched neither of the two branches in the loop — `0` and `1` — so nothing was logged, the engine continued as though the schema were current, and the only symptom was the AI Helper reporting no providers configured. The image verified clean: the marker checked that the file *existed*. Three changes, because any one alone leaves the trap set: - `dbUpdater.sh` now runs each migration with `bash "$dbUpdateScript"`, removing the dependency on a file mode that no reviewer sees in a diff. - Any exit code that is not 0 or 1 is now logged as an ERROR naming the script. Silence was the actual defect; a migration that cannot run must never look like one that did. - The build verify tests `test -x` rather than existence, and asserts both of the above. `dev_tools/test-ai-e2e.sh` is new and is what caught it: it boots the image, waits for the engine to migrate *on its own*, then drives the admin API through the provider wizard, live model discovery, the diagnostics scan, the tool-calling loop and the SSE stream against a mock provider served inside the container — no API key, no network egress. Deliberately never runs the migration by hand, since that would hide this exact class of bug. ### Issue #83 grew back inside the wizard that was meant to fix it Found on a live paid Gemini account, on the production upgrade, by setting up a provider the ordinary way. The wizard ran **Test before Model**. A connectivity round trip needs a model, and at that point none had been chosen — so `aiTestProvider()` reached for `$disc['models'][0]['id']`, "whatever the provider listed first". Google's `/v1beta/models` is not ordered by preference: the first of the 40 models returned was `antigravity-preview-05-2026`, an internal preview that rejects `systemInstruction` outright. A perfectly good API key therefore failed the wizard with ✕ Chat round trip — Developer instruction is not enabled for models/antigravity-preview-05-2026 naming a model the operator had never selected and could not see. This is #83's actual defect — *code choosing a model on the operator's behalf* — in a new costume, which is why the existing guards missed it: no model id is hardcoded anywhere. It is **selected**, at runtime, from a list. The guard now forbids indexing into the discovered list at all, and pins the step order; both were proven by mutation. The fix is structural rather than a better guess. Steps are now **Type → Endpoint → Credentials → Model → Test**: discovery runs on entry to the Model step via a new `discoverAiModels` endpoint, the operator picks, and the round trip tests *that* model. Reaching the test step with no model is now a plain "go Back and choose one", not an invented probe. Changing the base URL or the key discards the cached list so a different endpoint cannot be offered another's catalogue. Separately, `aiChatGemini()` now retries once with the system prompt folded into the first user turn when a model refuses `systemInstruction` — tried only *after* the proper field has been refused, never speculatively. Without it the grounding prompt, which is the only reason this helper is worth anything, takes the whole request down on those models. ### The AI Helper was the one subsystem that logged nothing Diagnosing the above needed a screenshot, because the server had nothing to say. Every AI failure — bad key, refused model, discovery error — was returned as JSON to the browser and left no trace. The three POSTs in `php.log` were all **HTTP 200**, since a rejection is a successful request carrying `success:false`. `aiLog()` now appends to `/opt/stateful/logs/ai.log` (picked up by the existing `*.log` rotation, and readable by the helper's own `read_log` tool): discovery results, provider test outcomes, and every upstream chat failure, through a single choke point in `aiChat()` so no adapter can fail quietly. Keys, endpoint credentials and conversation content are never written. ### Ollama is a preset, not a provider kind The dedicated `ollama` kind carried its own ~70-line adapter and its own `/api/tags` discovery branch. Ollama also serves an OpenAI-compatible API at `/v1`, so all of that was duplicating `aiChatOpenAI()` to save the operator typing three characters. It is now one of eleven presets on the OpenAI-compatible type, beside vLLM, LM Studio, llama.cpp, OpenRouter, Groq, Together, DeepSeek, Mistral and xAI — presets only prefill the form, and nothing downstream branches on which one was used. Removing a kind is not a code-only change, because **rows in the database point at it**. Two upgrade paths exist and `dbUpdate_2.45.sh` handles both: - **From 2.44**, `settings.ollamaUrl` is a bare `host:port` (2.44 spoke the native API). The import now appends `/v1` and creates the row as `openai_compatible`. - **From an earlier 2.45 RC**, rows with `kind='ollama'` already exist. A second block, deliberately outside the "registry is empty" guard because this repairs rows a previous revision of this same script created, rewrites the URL and then the kind. It is idempotent by construction — after the kind is rewritten nothing matches — and the URL is fixed first, while the rows are still identifiable. `TRIM(TRAILING '/')` keeps `host:11434/` from becoming `host:11434//v1`. The provider's cached model list is dropped at the same time: it was fetched from `/api/tags` in the native shape, and keeping it would show stale, wrongly-parsed ids until the 6h cache expired. Leaving those rows behind would have been the 2.43 world-card regression in a new costume — code deleted, live readers left pointing at it, failing plausibly rather than loudly. ### UI Replies stream (SSE, `X-Accel-Buffering: no`, with a non-streaming fallback for proxies that will not pass `text/event-stream`) and render as Markdown — escape-first, because 2.44 asked the model for raw HTML and injected it. The "Context" dropdown that chose which log to attach is replaced by a world hint. A five-step **Add AI provider** wizard tests endpoint, credential and model separately, so a failure names which of the three is wrong instead of surfacing as a chat error later. The AI button is no longer hidden until a key exists — that hid the diagnostics from the operator most likely to need them. The wizard overlay sits at `z-index:1060`: it opens from Server Settings, and a stacked overlay left at the base level renders behind its own dim layer and cannot be dismissed. `setup.php` now collects nothing for AI. Four bare key fields cannot express a provider, and a key typed there would have landed in the legacy columns the migration reads *from* — already run by the time the wizard is on screen, so the credential would have sat in a dead column while the helper reported nothing configured. ### Hugin can act, and every act is the server's, not the model's The assistant is named **Hugin** and has twelve actions: `start_world`, `stop_world`, `restart_world`, `update_world`, `delete_world`, `set_world_options`, `set_world_access`, `create_backup`, `restore_backup`, `set_world_backup_policy`, `set_world_mods` and `set_server_settings`. The design rule is **propose → confirm → execute**, and the load-bearing detail is *where the confirmation comes from*. A card built from the model's description of a change is a card that can describe a change other than the one that will happen. So the plan is authored server-side in `ai_proposals` from the **validated** arguments; the browser gets an opaque single-use token and never the plan. It expires in 15 minutes and is re-validated at apply time, so a world that moved on in the meantime stops the apply rather than acting on stale state. The executor owns no SQL. It calls the admin UI's own `*Json()` handlers and captures their output with `ob_start()`/`ob_get_clean()`, which means every guard those handlers already have applies to Hugin for free and cannot drift from what the UI does. `startDetachedJob()`, `startManualBackupJob()` and `startRestoreBackupJob()` were lifted out of the `adminAPI.php` switch so both callers share one implementation. Tiers: `create_backup` and `start_world` execute immediately (neither can lose anything); the rest render a confirm card; `delete_world` and `restore_backup` additionally require the world's name typed. **`saveWorldOptionsJson` is a full replace, not a patch.** Sending only the changed field would have blanked the password, dropped the launch parameters, unlisted the world and set `vanilla=0` — quietly converting a vanilla world to modded. The action now prefills every key from the current row. Refusals are enforced at *propose* time, so the card never shows a `0 → 1` that the launch path would ignore: crossplay or a password on a modded world, a listed vanilla world with no password, an enforced-but-empty access list, and a restore whose backup belongs to a different world. Eight operating procedures were added to the system prompt — diagnose before acting, a mod change is not live until the world is rebuilt, never invent a player ID, `worlds.public` is not `-public`, stopping disconnects players, prefer the narrow tool, proposing is not doing, and if a tool refuses, believe it. ### A model that cannot call tools now answers anyway Tool support is **negotiated from the endpoint's refusal**, never from a model allowlist — the same law that produced the discovery work above. `aiproviders.php` classifies a tool-parameter rejection as the `no_tools` quirk, records it on `ai_providers.tool_capability`, and retries without tools. Hugin then answers plainly and says it could not inspect anything and cannot make changes. Previously such an endpoint errored on every single message. ### A streamed reply could silently delete its own words `json_encode()` returns **`false`** on invalid UTF-8, and a provider may split a multi-byte character across two chunks. The SSE frame then went out as `data: ` with no payload and the browser dropped it — text vanished mid-sentence with no error anywhere. `aiUtf8Carry()` now holds an incomplete trailing sequence until its continuation arrives, and `sse()` falls back to `JSON_INVALID_UTF8_SUBSTITUTE` rather than emitting nothing. ### A modded world's log said crossplay was enabled Nothing in the launch path was wrong: `startWorld.sh` has never passed `-crossplay` to a modded world. The bug was one sentence, which opened `World 'X' has crossplay set but is MODDED` — and the first six words are what an operator scanning a log takes away. It now leads with the outcome (`crossplay is OFF -- it is saved as enabled, but ...`) and names the remedy. Proving it was ours took two greps: every occurrence of `crossplay` in `assembly_valheim.dll` and `Splatform.dll` is a .NET **identifier**, which lives in metadata as UTF-8, not a user string literal, which would be UTF-16. `strings` found nothing while `grep -a` matched — and that difference is the whole answer. Valheim never prints the word. Guarded by `dev_tools/test-crossplay-logline.sh`, which extracts the real block and runs all four vanilla/crossplay combinations. ### Telemetry, and a migration rule that stops version churn `pushAnalytics.sh` gained `ai_chats`, `ai_tool_calls`, `ai_actions_{proposed,applied,rejected,dismissed,expired}`, `ai_tools_used`, `ai_errors` and `ai_capability`, all **counts** over a one-day window. No prompt, reply, world name, mod name, model name, endpoint or key is ever sent. The analytics service stores them in a new `ai_hugin` column, bounded to 64 keys of 64 chars. All 2.45 schema is **appended to `dbUpdate_2.45.sh`** rather than opening a 2.46. Migrations from 2.40 on are object-by-object idempotent and re-run safely on every boot, so a later revision of the same script is the correct place for late schema — `exit 2` gating is legacy (2.7–2.38). `dev_tools/test-migration-append-safe.sh` fails the build if a migration exists for a version newer than the Dockerfile. ### Meeting Hugin A one-shot `huginNoticeShown` dialog introduces the raven on first login after upgrade and points at AI Setup. Its default is `?? 1`, not `?? 0`: an undefined variable is `null`, and **`null == 0` is true in PHP** — so a missing setting would have shown the dialog on every page load forever. Defaulting to "already seen" fails closed. ## v2.44 ### One mod could freeze a world's entire mod list (issue #82) `unzip` exit code **1 means "extracted, with warnings"** — not failure. A mod packaged on Windows stores its entries with backslash separators (`PONEIS/SmartContainers` ships `plugins\SmartContainers.dll`); unzip converts them, warns, and returns 1. `0-functions.sh:422` treated that as fatal, which did far more than log a wrong line: `modInstallFailures` incremented → `downloadAndInstallTsModsForWorld` returned 1 → `phvalheim:403` skipped **both** `packageClient` and `generateModViewerJson` and set the world `stopped`/`failed`. So the operator's mod-list edit was saved to `world_mods` but never reached the client payload or the mod viewer — which reads as "changing my mod list does nothing". Now fails only on 2–10 and 12+, the real format and I/O errors; 11 ("nothing matched") stays exempt. The same flaw in the BepInEx check at line 395 is fixed too — a backslash-packed loader pack would have silently skipped installing the loader. ### The mod loader is no longer a mod `InstallAndUpdateBepInEx()` installs BepInEx on every modded world at engine start, unconditionally and always latest, before any mod. Selecting it, deselecting it or pinning a version never had any effect. But the catalogue carries three loader rows and every mod declares a dependency on one, so 2.43's resolution added a loader row to every modded world — and because Hexium mods resolve to Hexium's copy, the picker hung a yellow "dependency (deselected)" badge on a row nobody could act on. The loader is now excluded from the catalogue, the dependency graph, the closure, the install plan and the viewer; `dbUpdate_2.44.sh` clears the rows already written and names the worlds it changed. ### Fixed - The engine log no longer fills with `UDP_PORT_25000-25100: command not found`. `/etc/environment` is sourced by the main loop every two seconds, and Unraid templates name port variables after the range they map — a hyphen is not a legal shell identifier, so each tick logged a command-not-found. `printenv` is now filtered to valid identifiers. - `generateModViewerJson` took its world from a leaked global instead of `$1`. Correct only because the main loop happened to assign that same global first; one reordering would have written one world's mod list onto another. ## v2.43 ### Mods can come from Hexium as well as Thunderstore A world may draw on either catalogue or both. Search results carry a coloured pill showing each mod's origin (Thunderstore blue, Hexium purple), and buttons above the list show or hide a catalogue. Dependencies resolve **across** sources, so a Hexium mod needing a Thunderstore-only dependency now works. Identity is `(source, owner, name)` — never the source's UUID. Hexium mirrors Thunderstore packages carrying their original `uuid4`, so 600 package UUIDs exist in both catalogues and a UUID can never identify a mod. ### Version pinning Every published version of every mod is stored, not just the newest — each with its own download URL, file size and release date. Pick a version from the dropdown in a mod's row to freeze it there; "Latest (auto)" keeps following new releases. A pinned version is kept in the database even if the source delists it. ### The catalogue sync was rebuilt A full cold build of both catalogues — 11,600+ mods and 91,000+ versions including all history — takes about 30 seconds instead of hours. A routine check that finds nothing changed takes about a second: Thunderstore answers a conditional request with a bodiless `304`, Hexium's body is hashed and compared, and every row carries a content hash so only genuinely changed rows are written. Both catalogues are synced at **every server start** as well as on the configured interval, so a restarted server comes back current rather than waiting up to six hours. Sync & Maintenance shows a live panel per catalogue — phase, packages and versions seen, what was added/changed/removed, timing, and a comparison with the previous run — plus a per-catalogue **live sync log** naming what moved, and a per-mod detail toggle. Server Settings → Mod Catalogues enables/disables each catalogue, sets the interval, and accepts an API key. **Neither catalogue needs one** — both are public. ### Removed The sidebar's **Thunderstore Sync** button, its confirm dialog and stop endpoint; the **Thunderstore Local Sync** and **Thunderstore Chunk Size** settings; the whole pre-2.43 sync (`tsSync*.sh`, `tsPrune.sh`, `tsModDepGetter.sh`, `modLookup.sh`) and the 14 MB `tsmods_seed.sql` GitHub seed. A fresh install now builds the catalogue from the live APIs. ### Fixed - Two mods whose names differed only in capitalisation (`Iron_ModPack` vs `Iron_Modpack`) were treated as one and overwrote each other on every sync. 22 such pairs exist on Thunderstore; all are now stored separately. - Dependency strings containing hyphens in the author or version (`LVH-IT`, `sinai-dev`, `2.0.6-beta.1`) matched the wrong package or none. Resolution is by longest known `owner-name` prefix. - A world drawing on both catalogues installed **two copies of the same mod** — usually BepInEx, which both catalogues publish. Only one was ever installed, but the mod list showed it twice and the count was one too high. One copy per `(owner, name)` is now selected, installed and displayed, and the UI says which copy it kept. - World cards and the mod editor reported **0 mods** for every world; they read the pre-2.43 columns the new catalogue no longer writes. Backup manifests recorded empty mod lists for the same reason. - In the mod picker, ticking a checkbox sent the list back to page 1 — every time. The redraw now holds the current page and scroll position. Checkboxes are smaller. ### Upgrading Existing mod selections migrate automatically on first start. The previous Thunderstore tables are left untouched, so nothing is discarded. If a world had selected a mod since delisted, the engine names that world at startup. ## v2.42 ### "What's New" modal after every upgrade The admin UI now shows a one-shot modal listing what changed, the first time it is opened after an upgrade. Dismissing it records the running version; it stays gone until the next upgrade. Skipping a release does not skip its notes — upgrading 2.42 → 2.44 shows both. Fresh installs do not see it (there is no "before" to describe), and it queues behind the setup wizard and the settings-migration notice rather than stacking on them. Release notes live in `container/nginx/www/includes/whatsnew.php`, one entry per version. **Every release must add one**: `dev_tools/check-whatsnew.sh` fails if the version in the Dockerfile has no entry, because a missing entry is invisible at runtime — the modal just silently shows nothing. The stored state is a version string rather than a "shown" boolean deliberately. Every script in `dbUpdates/` runs on every boot, so a boolean would need re-arming each upgrade and an unconditional `UPDATE` would re-raise the modal after every restart. Comparing stored version against running version is self-arming and needs no migration for 2.43+. ### Automatic backups stayed disabled on Unraid despite a dedicated backup volume The admin UI reported `✓ dedicated volume` and manual backups worked, but `backups.log` repeated every scheduled run: ``` [WARN : phvalheim] Backup path (/opt/stateful/backups) is on the same volume as /opt/stateful — no dedicated backup volume mounted. Automatic backups disabled. ``` The UI and the scheduler were asking two different questions. `isBackupPathMounted()` (admin UI) asks the **mount table** — is `/opt/stateful/backups` a mount point? The scheduler in `worldBackup` instead compared **device identity**, the source column of `df` for the backup path and for `/opt/stateful`. Device identity cannot see a bind mount. On Unraid every `/mnt/user/` is served by one FUSE mount, so `df` reports the source as the literal string `shfs` for *all* of them while each share still reports its own size. A user mapping `/mnt/user/appdata/...` to `/opt/stateful` and an 11T `/mnt/user/backups/...` to `/opt/stateful/backups` got `shfs == shfs` — read as "same volume", so automatic backups disabled themselves at every run while the UI correctly showed two volumes of different sizes. This affected every Unraid install using the standard `/mnt/user` share layout. Both callers now use one shared oracle that reads the mount table (`mountpoint`, falling back to `/proc/self/mountinfo`), so the admin UI and the backup scheduler can no longer reach opposite verdicts. Covered by `dev_tools/test-backup-volume-detection.sh`, which reproduces the failing condition with a real bind mount whose `df` source is identical to its parent's. ## v2.41 — Crossplay join codes, access-list safety, world card rework ### Analytics push no longer fails on larger servers `pushAnalytics.sh` built the worlds array in a shell variable and handed it to `jq` as `--argjson worlds "$worlds_json"`. Linux caps a **single** argv entry at 128 KiB (`MAX_ARG_STRLEN`), separately from the much larger total `ARG_MAX` — so once a server had enough worlds x mods to cross that line, `jq` never ran: ``` pushAnalytics.sh: line 146: /usr/bin/jq: Argument list too long [WARN : phvalheim] Failed to build analytics payload ``` Every push failed from then on, with that one WARN line as the only symptom. Worlds and mods are now accumulated in temp files and passed with `--slurpfile`, which has no such limit (measured in-container: `--argjson` accepts 129,025 bytes and fails at 201,601; the same data via `--slurpfile` is fine at 512 KB). Temp files are removed by an `EXIT` trap. ### The OPEN pill matches the others It was styled muted grey while every other access pill is accent-coloured, so it read as a different kind of thing on the same row and was hard to see against the card. It is a normal pill now; the tooltip still explains that "open" means no access list and no password. Measured across DPR 1/1.25/1.5/2 its text is the best-centred on the row (within 0.25px by both ink-bounding-box and ink-centroid). `access list` and `crossplay` remain 2-5 device px left of centre -- monospace glyph side bearing, not yet addressed. ### Crossplay: Launch! now explains how to join A crossplay world can no longer be launched from the public card, because it never really worked. Valheim's `-joincode` argument is real, so the button looked correct — but the client's handler resolves the code and joins immediately without ever selecting a character. Players arrived in the world as Valheim's built-in `Odev (Developer)` profile and found a character in their list they had not created. Clicking **Launch!** on a crossplay world now opens a short modal with the current join code and three steps: start Valheim, pick your character, use *Join by code*. The code is read at click time, so a world that restarts and is reissued a code never hands out a stale one. Non-crossplay vanilla worlds (`+connect`) and modded worlds (`phvalheim://`) are unchanged. The modal also needed a stacking fix: this page carries a hand-rolled `.modal` rule from before Bootstrap that makes `.modal` itself the dim overlay at `z-index: 1050`. Bootstrap puts its backdrop at 1050 too, so the backdrop painted over the dialog — it looked dimmed and Close could not be clicked. Scoped to `#crossplayJoinModal`, matching what the macOS install modal already does. - **Crossplay is a vanilla-only option again, for now.** Enabling it makes Valheim open a PlayFab server, which is reached by join code and has no host:port — but the PhValheim client reaches a modded world through QuickConnect, which connects by host and port. A modded crossplay world therefore starts normally and simply cannot be joined by the client. The option is hidden for modded worlds and enforced at world start, so a world whose flag was already set stops opening a PlayFab server on its next restart. This will be revisited once the client can launch with a join code. - **A crossplay world now shows its join code instead of a Launch button that cannot work.** Enabling crossplay makes Valheim open a *PlayFab* server rather than a Steam one; the world is reached by join code and cannot be joined by IP at all. The card offered `steam://…+connect :` regardless, which asks for a direct connection the server is not serving — so it failed silently while the in-game browser worked fine. Crossplay cards now show the code with a copy button, and the hint no longer tells players to use *Join IP*. Non-crossplay vanilla worlds keep their Launch button. The code is read from the world log at render time rather than stored: it is reissued on every restart, so a cached one would keep advertising a code that no longer works. - **The admin dashboard's Launch button now respects a crossplay join link too.** The public card was fixed for this, but the admin one still offered `+connect :` for every vanilla world — which a PlayFab-hosted crossplay server never accepts, so it failed silently. Both of the dashboard's launch paths (the PHP render on load, and the poll payload that re-renders it seconds later) now share one helper with the public card. A crossplay world that is up but has not registered its join code yet shows a disabled "starting…" rather than a link with nothing to pass. - **Resource readouts are cleared when a world stops.** Memory and tick-health bars stayed on screen for worlds that were offline or mid-update. Both APIs were already correct — they return only running worlds — but the way they report a stopped world is to *omit* it, and the dashboard only ever iterated what was in the payload, so those worlds were never visited again and kept their last drawn numbers. - **An access list that is enabled but empty is now refused.** Valheim only applies `permittedlist.txt` when it has entries — an empty one is not "nobody may join", it is no restriction at all. A world could therefore sit with *Use Access List* switched on, no players in the list, and be joinable by anyone, while the Access tab showed it as restricted. Saving that combination now fails with an error naming both repairs (add a player, or switch the list off). It is refused rather than silently corrected: "let anyone in" and "let these people in" are one click apart and mean opposite things. - **"Use Access List" can no longer be switched on with nobody on the list.** Valheim enforces `permittedlist.txt` only when it has entries, so an access list that is on but empty produced a wide open server whose Access tab claimed otherwise. Creating a restricted world now requires a first player ID, and saving an empty enforced list is refused — both checked server-side, not only in the browser. Any world that reaches that state another way (a restored backup, a direct database edit) now logs a loud warning at every world start. - **A restricted world now needs a first player before it can be created.** Choosing *Only players on the access list* reveals a Steam ID field and the world will not be created without a valid 17-digit SteamID64, so it is genuinely restricted from the moment it exists rather than restricted-with-an-empty-list. Validated at the endpoint as well as in the form, since the endpoint is reachable directly. - **Access IDs are now shown and stored in the `V_` form everywhere.** Valheim matches only the prefixed form, so a bare 17-digit SteamID64 in an access list matches nothing and the player is refused with a misleading "Banned". Previously the prefix appeared only in the file on disk, while the database, the Access tab and the player page all showed the bare id. Citizens, Admins and Banned now all store and display the canonical form. Pasting a bare SteamID64 still works — it is upgraded automatically — and an already-prefixed id is left alone. - **World cards space their rows consistently.** A card stretches to match the tallest card in its row, and the leftover height was shared across every row — so an online modded card next to a taller vanilla one had its rows spread twice as far apart as identical offline cards beside it. The leftover now collects in a single empty row at the bottom, so row spacing no longer depends on a card's neighbours. The crossplay hint sits at the bottom of the card, where a modded card shows its boss trophies, instead of jammed under the last row, and there is more space under the world name. - **Creating a vanilla world explains the password rules where you break them.** Valheim will not start a world whose password appears anywhere inside its name, and it will not list a world in the server browser without one. Both were only enforced after you pressed Create, so the form spun, bounced, and printed the reason in a box at the far end of the page — next to a warning that opened by talking about custom seed mods. Creating `test123132131` with the password `test123` therefore looked like it was being blocked over seeds. The rules are now checked as you type, against the password field, naming both offending values; the note about seeds has been moved out of the password panel to the seed control that was already explaining it. - **Admin toggle switches are smaller, and there is now only one size of them.** The settings modals overrode the switch to 44×24 while the rest of the admin UI used 36×20, so the loudest thing in a panel of quiet rows was a checkbox. Everything is 32×18 now. The reason the modal ones were enlarged — that the smaller switch was under the minimum size for a pointer target — was a fair point, and it is answered properly instead: the clickable area stays 36×24 while the drawn pill shrinks. - **A vanilla world can run without a password.** The password field is optional now; leave it blank and anyone who can reach the server may join, which is what the card's **OPEN** pill has always meant. The one thing a passwordless world cannot do is appear in the public server browser — Valheim refuses to start a listed server with no password (*"bad password: the password is too short"*) — so the listing toggle is disabled, and says so, while the password is empty. It is also unticked rather than merely greyed, since a disabled-but-ticked box still submits. Both the create form and the world Settings modal enforce it, and the server re-checks on save. - **Every world card says how you get in, and every pill says what it means.** Modded worlds are always gated by the citizens list, and were the one kind of world whose card never mentioned it — they have an Access row now, built by the same code as the vanilla one. The pills read **ACCESS LIST** or **OPEN**, each with a hover explanation written for players rather than server operators. A world whose access list is switched on but empty is shown as **OPEN**, because that is what it is: Valheim ignores an empty list and anyone who can reach the server can join. The tooltip says so, and says what to ask the owner for. - **The "IN SERVER BROWSER" pill is gone.** It answered a question no player has — you are already looking at the world's card, so how it was discovered is the operator's business. - **Access pills are a third smaller, and their text is centred.** They stood 23px against 20px data rows, making the Access row the tallest on the card, and the last letter's tracking pushed every label off-centre inside its pill. - **A running world is described by what it is running, not by what has been saved.** Enabling crossplay on a live world lit the CROSSPLAY pill on the public card immediately, while the Launch button correctly stayed a direct-connect link — one card, two sources of truth, and the pill advertising a crossplay world Valheim was not serving. Settings that only take effect at the next restart no longer change what players see. The world is marked **restart pending** in the admin Worlds table instead, naming which settings are waiting (crossplay, server browser listing, password, world type), and that mark clears the moment the world restarts. A stopped world is still shown with its saved settings — there is nothing running to contradict them. - **The Launch button is right from the moment a world comes up.** Valheim only announces which backend it opened about 30 seconds into starting, and until then the button fell back to the saved crossplay column — which is wrong for exactly the world that has just been restarted into a different mode. It now falls back to what the world was actually started with. - **The join code lines up with the rest of the card.** Its label was one character shorter than every other label, and since the label column sizes itself to its widest entry, the code sat 8px right of every other value. - **An online world card no longer sits wider-spaced than an offline one.** Collapsed table borders were set on the *offline* card rule only, so a live card kept the browser's default 2px border-spacing: every row 2px further apart and the card about 14px taller than an identical offline card beside it. The row heights matched the whole time — it was the space between them that differed, which is why online cards looked like they had gaps. - **World cards are shorter.** A modded card goes from 309px to 248px tall against the same 400px width — a fifth off — so it reads as a card rather than a square; a vanilla one goes from 338px to 275px. Line spacing of 1.5 is the right figure for body text and is what fixed the cramped look, but it was being applied to single-line headings and to fixed tabular rows as well, which cost every card about 25px of pure leading. The world name and the Launch line take a normal heading figure now, and the data rows sit at 1.43 — still inside the range for dense rows, and a whole number of pixels so the rhythm stays exact. Most of what came off was a 50px bottom padding — and that padding turned out to be the only thing keeping the boss trophies on the card at all. The trophy row is a sibling of the card's full-height table, so it was always being laid out past the bottom edge; the padding just hid the overflow. The card stacks its contents properly now, which means nothing hangs off it and the height is whatever is genuinely in it. The spacer row under the Launch line was also malformed HTML — a `` whose tag never closed — and is a real cell now. - **The player page is set in a real terminal font now.** It asked for Lucida Console, which exists only on Windows, so almost everyone got Courier New — or on Linux its clone, Liberation Mono. Those are thin, wide, small-on-the-body faces, and the page packed them at `line-height: normal`, about 1.17, where the readable range is 1.4–1.6. The result read as tiny and cramped whatever size it was set at. JetBrains Mono now ships with the container (no Google Fonts request, so it works on a server with no outbound internet and tells nobody who visited), line spacing is 1.5, card rows are 14px instead of 12px, and labels are muted so the value you actually came for is the brighter half of the row. Row spacing goes from 14px to 21px. See `docs/TYPOGRAPHY.md`. - **Card values line up across every card.** The label column took whatever width was left over, so a world with no MD5 sum and no dates yet pushed its values more than twice as far from the colon as a world with a full hash — identical labels, different gap on every card. The labels now size to themselves, which is the same width everywhere. - **A world restarted into crossplay shows the right join method straight away.** Valheim logs which backend it opened about 30 seconds after starting, and until it did, the card read the *previous* session's line — so a world restarted into crossplay spent that window offering a direct-connect link that could not work. The join code had the same flaw and could hand out the previous session's code, which is already dead. - **Crossplay cards no longer show a Server address.** It is the value you type into Valheim's *Join IP* screen, and a crossplay server does not accept direct IP connections at all. - **Fixed the crossplay hint being cut off at the bottom of vanilla cards.** It was a sibling of the card's full-height table, so it was laid out past the bottom of the card. It is part of the table now and cannot be pushed out. - **World cards are ordered online first, then alphabetically.** The list was ordered by a cron-updated memory column, which is stale for a world that has just started or stopped and meaningless for one that has never run — so the order looked arbitrary, and could disagree with the online/offline state the card itself displayed. (The 5-second refresh updates cards in place and does not reorder, so a world that starts or stops while the page is open keeps its position until reload.) - **Players can find their own player ID.** It now appears under the welcome line on the player page in small magenta, click to copy — the value a server owner has to ask every player for, which previously required a third-party lookup site. - **Opening Settings on a world with an enforced but empty access list now says so.** A modal explains that Valheim ignores an empty permitted list, with a button that goes straight to the Access tab. It tracks the live condition rather than being permanently dismissible, so it disappears when the list is fixed. - **New worlds ask who can join.** The create path never set the access flag at all, so every world inherited the schema default — access list enforced, list empty — and came up open while its Access tab said restricted. The new-world form now has an explicit *Who can join* choice, defaulting to restricted, and the endpoint treats an absent value as restricted so an older client or a replayed request cannot create an open world by omission. - **Worlds already in that state now announce it at every start.** The save-time guard cannot help a world that was created before it, because nothing re-saves one. `syncAccessLists.sh` renders the lists on every world start and is the only code that can see the condition, so it now logs a `WARNING` saying the world is open despite showing as restricted. It does not change anyone's access. - **Fixed: a newly created modded world installed no mods at all.** `unzip -d` creates only the last component of a path and fails when a parent is missing. The BepInEx pack ships `BepInEx/config/` and `BepInEx/core/` but not `plugins/`, so on a fresh world every plugin extraction failed — silently, because the command discarded its output — and the world came up vanilla while every log line read "Installing…". It looked intermittent because a world that started got `plugins/` created by BepInEx itself, so a retry appeared to fix it. The directories are now created first, and a failed plugin extraction is logged instead of ignored. - **A modded world is never published with zero plugins installed.** A failed mod download left the world starting anyway with an empty `BepInEx/plugins`, so a world created with mods selected could come up vanilla. Mod installation failures now leave the world stopped and marked `failed`, with its client payload and md5 untouched, rather than shipping an empty modpack to players. ## v2.40 — Vanilla Servers, Admins, Custom Launch Parameters Release candidate. Held at `:rc` pending the Valheim 1.0 (Deep North) boss trophy prefab name — see "Known gaps" below. ### Features - **Vanilla (zero-mod) worlds** ([#81](https://github.com/brianmiller/phvalheim-server/issues/81)): A world can now be created as vanilla — stock Valheim, no BepInEx, no mods, no client payload. Players join with the ordinary Valheim client, so no PhValheim client install is needed. New per-world settings: **server password** and **list in the public server browser** — these are vanilla-only, since modded worlds are gated by the CITIZENS list exactly as before. - **Crossplay**, on every world: lets Xbox / Microsoft Store players join. This is *not* a vanilla-only setting — it is orthogonal to whether a world runs mods, and lives in every world's **Settings** modal. (It was briefly scoped vanilla-only during development; that was a mistake.) - **Bespoke public UI card for vanilla worlds**: shows the endpoint, a click-to-reveal password, access badges, and a Join button (`steam://run/892970//+connect`). Vanilla Valheim has no launch argument to pre-fill a server password, so showing it on the card is what makes the world joinable. - **Custom launch parameters** per world, appended after everything PhValheim generates so they can override it. Validated in the admin UI and never `eval`'d by `startWorld.sh`. - **ADMINS editor** under CITIZENS in the world Settings modal, writing `adminlist.txt`. Entries are validated as SteamID64 — Valheim silently ignores malformed ones, which previously looked like "I added an admin and nothing happened." - **Boss registry** (`includes/bosses.php`): the boss list is now defined once and consumed by the API, the public card and the AJAX refresh. Adding a boss is one array entry, one DB column and one PNG. - **Password visibility control**: a per-world toggle (`password_public`) removes the password row from the public card entirely. It is also stripped from the AJAX payload, not just hidden in the markup. - **Copy button** next to Show on the vanilla card's password, with a non-secure-context fallback — `navigator.clipboard` is undefined over plain HTTP, which is how most self-hosted installs are reached on a LAN. ### Vanilla world refinements - Card now reads `Type: unmodded`. - The **HEALTH** bar is hidden for vanilla worlds in the admin UI. Tick health comes from the TickMonitor BepInEx plugin, which a vanilla world does not run, so the bar could only ever sit empty. - **Edit Mods is disabled** for vanilla worlds, and `edit_world.php` refuses them server-side — the page is reachable by URL regardless of the button. Switching a world to vanilla now clears its mod selection, so flipping back later does not resurrect a list you thought you had removed. - Offline vanilla cards grey out fully. The access badges set their own background, so they needed their colour **replaced** rather than faded — opacity alone left a tinted pill on an otherwise grey card. - The seed control is hidden when creating a vanilla world, replaced with an explanation. Custom seeds require the CustomSeed BepInEx mod and Valheim itself has no seed argument, so the field could only ever be ignored. - **Vanilla worlds no longer display a fabricated seed.** Creating one stored a seed that could never reach Valheim — the game invents its own when it first generates the `.fwl` — and the public card rendered that stored value as though it were the world's real seed. Nothing failed; the number was simply wrong. Vanilla worlds now store no seed at creation, the card shows *generated on first start*, and the engine reads the real seed back out of the `.fwl` once the world has started (same extraction `importWorld.sh` has always used on uploaded saves, verified against real Valheim saves). ### Access lists (CITIZENS / ADMINS / BANNED) - **The CITIZENS and ADMINS editors could report a save that never reached the disk.** Both wrote their file with `file_put_contents()` and ignored the return value, so a write that failed — most commonly a list file left owned by `root` by an older engine or by a restore — returned `{"success":true,"message":"Saved successfully"}` while the file kept its previous contents. The database and the file then disagreed permanently: `permittedlist.txt` went on gating the world with a stale list, so players the operator had just added were refused, and `adminlist.txt` looked like it was never written at all. Writes are now atomic (temp file + `rename`, which needs permission on the *directory* rather than the target file, so it also repairs a root-owned file on the next save) and **every failure is reported instead of swallowed**. - **Nothing ever rewrote these files from the database.** The admin UI was the only writer, at the moment Save was pressed. A world that was restored from a backup, or rebuilt, kept whatever list files came with it. `syncAccessLists.sh` now regenerates all three from the database at every world start, making the database the single source of truth and letting drift heal itself on the next restart. - **New BANNED list**, editing `bannedlist.txt`, alongside CITIZENS and ADMINS in the world Settings modal. A ban applies even when the world is public. - **`worldDirPrep` only ever created `permittedlist.txt`.** `adminlist.txt` and `bannedlist.txt` were left for Valheim to create on first boot, so the admin UI was editing files that did not exist yet. All three are now created with the world. - **An imported world's admins existed only on disk.** `importWorld.sh` wrote `adminlist.txt` directly but never set the `admins` column, so the Settings modal showed no admins for an imported world — and under the new sync those admins would have been dropped at the next start. It now writes the database and renders the files from it. - **A bare SteamID64 no longer matches anything in Valheim 1.0 — entries are now written as `V_`.** `ZNet.ListContainsId()` ends by looking up the *display-prefix* form of the ID (`Steam` → `V`) and **assigns** that result over the earlier bare/`Steam_` checks instead of OR-ing it, so the plain ID everyone knows can never match. This affected all three lists identically, and is why a world with the correct SteamID64 in `permittedlist.txt` still answered **"Banned"** — Valheim uses that same client message for "not on the allowlist". Found by decompiling the shipped assembly and confirmed on a live server. PhValheim now stores whatever the operator types and converts on write, in both the admin UI and the engine's world-start sync, so existing worlds repair themselves. - **Console players are supported.** Xbox / PlayStation / Nintendo / GameCenter IDs (`X_`, `S_`, `N_`, `A_`) are accepted; those platforms are *number-filtered* by Valheim, so their ID cannot be derived and must be read from the player's F2 panel. - **All three editors now explain how to get a player's ID**: join any public world and press **F2**. That is the only method that works for every platform. - **The "restart the world for this to take effect" prompts are gone.** Valheim re-reads all three files while running — verified on a live server, where a player rejected at 18:39 was admitted at 18:41 with no restart in between. Admin status is the one exception, since a connected client caches it until it reconnects. - Citizens are validated the same way admins already were. Valheim silently ignores anything else in these files, which is indistinguishable from "I added them and nothing happened". - File headers now match what Valheim itself writes byte-for-byte, including the double space in the admin and banned headers. Verified against the real Valheim dedicated server: it reads and writes all three lists in the `-savedir` root, creates any that are missing at startup, and does not overwrite entries written from outside — neither before it starts nor while it is running. `dev_tools/test-accesslists.sh` covers the above end to end against a live container. ### Fixes - **`-public` was hardcoded to `0`** in `startWorld.sh`, and `-password` was never passed at all despite being accepted as an argument. No world has ever been listed or password protected. - **`worlds.public` is not a "public server" flag.** It is the CITIZENS access-control flag — when set it blanks `permittedlist.txt`. Valheim's `-public` argument is now driven by a separate `listed` column, so worlds that were opened to all citizens are not silently published to the global server browser on upgrade. - **Trophy tooltip drift**: the AJAX refresh said "The Seeker Queen" where the server-rendered card said "The Queen", so the tooltip changed on first refresh. Both now come from the registry. - **SQL injection in `setHungHeads()`**: the world name and trophy column were interpolated into SQL from an unauthenticated POST body. Both are now bound/validated against the registry. ### Admin UI - **The mod browser is one "All" list.** The old "Available" tab held only the mods you had *not* picked, so ticking one made it vanish from the list you were reading. "All" holds every mod with the selected ones pinned to the top, and it is the landing tab on both Create World and Edit World. "Selected" remains as a filtered view. Previously the pages opened on "Selected" — empty by definition on a world being created — which rendered "No data available in table" and hid the whole catalogue behind a tab. - **Create World no longer offers mod selection for a vanilla world.** The whole card is hidden, not just the tables; the header and the clone-mods-from-another-world block used to stay on screen for a world that can hold no mods. - **World Settings modal reorganised** into General / Options / Access / Backups tabs, with the create and edit pages given a single primary action and a sticky action bar. - **Access tab**: the world access switch moved to the top — it decides whether the Citizens list is consulted at all — and gained its own **Save Access** button. Citizens keeps its own **Save Citizens**, which now hides along with the editor instead of sitting there answering "Citizens saved." for a list that was no longer on screen. - **One-time notice explaining the access switch change.** Upgrading flips how every world's switch *looks* — `Public World: on` becomes `Use Access List: off` — so the Access tab explains it once, then never again. Armed only for servers that already have worlds, so a fresh install is never told about a change it never saw. If the id-format notice is also due, the two are shown one after the other rather than stacked. - **One world that will not start no longer takes the engine down.** The start path called `exit 1`; supervisor then restarted the engine, whose pre-flight resets every world to `stopped` — so a single unstartable world became a restart loop that also clobbered `create` and `update` commands queued against the *other* worlds. It is now marked `broken` and the engine carries on. The wait that followed it was also unbounded, so a world that started and then died (a rejected password, a mod that aborts) parked the engine forever; that wait now gives up after 120s and marks the world `broken` too. - **Access tab decluttered.** The same five-line "how to find a player's ID" note used to sit above each of Citizens, Admins and Banned. It now appears once, above all three, as a disclosure that starts closed — a screen reader was reading the whole procedure out three times per visit. Each list instead carries a one-line hint with a real example (`V_76561198012345678`), replacing a placeholder that vanished on focus and never showed the `V_` form. Each list heading now shows a live count, and **Look Up SteamID is on all three lists** — it used to exist only on Citizens and always pasted its result there, so there was no way to look up an ID while editing Admins or Banned. Banned gains a warning line noting that a ban applies even with the access list switched off. - **"Public World" is now "Use Access List".** The switch never had anything to do with the Valheim server browser — it only decides whether `permittedlist.txt` is enforced — and calling it *Public* invited it to be read as the separate **List in server browser** option. The sense is inverted to match the new wording: **on** means the Citizens list is enforced. Nothing is stored differently, so a world's actual access is unchanged; a world that read "Public World: on" now reads "Use Access List: off". - **Look Up SteamID returns the `V_` form** rather than a bare SteamID64. It pastes straight into an access list, so it was manufacturing the exact input Valheim 1.0 refuses. The same helper in the legacy `citizensEditor.php` is fixed too. - Hint text spacing on the General and Options tabs; the "needs a world restart" note now shares a line with its Save button instead of sitting stranded below it. ### Upgrading from 2.39 - **Stored access IDs are converted to the `V_` form automatically** on first start, and the Access tab explains the change once. Idempotent; already-prefixed and console IDs are left alone, and anything unparseable is kept verbatim rather than dropped — silently deleting an unrecognised ID would lock someone out of their own world. Note this is a *display* fix: `syncAccessLists.sh` already canonicalised on the way out to the files, so an upgraded server was functionally correct before it ran. What it was not was legible — the Access tab showed bare IDs while the file Valheim reads said `V_…`. - `container/mysql/tsmods_seed.sql` refreshed: **9,390 → 11,030 mods** (the committed seed was seven months old, so a fresh install started that far behind until the first 12-hourly sync). ### Client - **No client update is required.** 2.0.12 remains current and works with both modded and vanilla worlds — vanilla worlds are joined from the public card's `steam://run/892970//+connect` button, which needs no client at all. ### Known gaps - **The Deep North boss cannot be a hung head.** Valheim 1.0 shipped without a trophy for it: the assets carry 131 `Trophy*` tokens and only 7 `BossStone*`, none for Kall Fimbulbringer, and the seven existing stones are confirmed. The hung-head wall therefore stays at seven bosses. `public/api.php` still logs any unrecognised `Trophy*` POST, so if one ever appears it identifies itself. See `docs/RELEASE-2.40-DESIGN.md` §9. - Custom seeds need a BepInEx mod, so vanilla worlds always generate a random seed. ## v2.39 — Modpack Rebuild Boot Fix First stable release of the 2.38 backup system work, plus a fix for worlds failing to boot after a modpack rebuild. ### Fixes - **World boot failure after modpack rebuild** ([#80](https://github.com/brianmiller/phvalheim-server/issues/80)): Mod zips packaged on Windows can store directories without the execute bit. `unzip` preserves that, leaving BepInEx unable to traverse the extracted plugin directories and aborting startup with a fatal `UnauthorizedAccessException`. `u+rwX` is now restored after Thunderstore extraction and after custom mods/configs/patchers installs (`cp -p` preserves the bad source permissions the same way). - **Backup/restore progress behind Cloudflare Tunnel**: Replaced streaming progress with background jobs plus polling, which Cloudflare Tunnels do not buffer. - **NGINX FastCGI buffering**: Disabled for streaming progress endpoints. - **Backups table schema**: The `orphaned` column is now present in the initial table creation, not only in the migration path. ### Included from v2.38 (previously pre-release) The full backup system modernization — activity-aware scheduling, tiered retention, compression, one-click restore, backup management UI, and startup reconciliation. See the v2.38 notes below for details. --- ## v2.38 — Backup System Modernization (Pre-release) ### Backup Engine - **Activity-aware scheduling**: Backups only trigger when players have been online since the last backup (configurable) - **Configurable intervals**: Set backup frequency per-server or per-world (default: 30 minutes) - **Full world backups**: Archives the entire world directory (game data, mods, configs) instead of just Unity save files - **Compression support**: Optional gzip or zstd compression with deferred scheduling (compress during off-peak hours) - **Tiered retention**: Keep all backups for N hours, then daily, weekly, and monthly tiers — with per-world overrides - **Performance tuning**: CPU priority (nice), I/O priority (ionice), and compression level controls to minimize impact on active players - **Disk space preflight checks**: Backup and compression operations check available space before starting; graceful fallback to uncompressed if space is insufficient - **Manual backups**: On-demand backup creation from the admin UI with real-time progress polling - **Transitional state protection**: Backups and restores are blocked while a world is starting, stopping, updating, or being deleted ### Restore - **One-click restore**: Restore any backup from the admin UI with live progress - **Pre-restore safety backup**: Automatically creates a safety snapshot before overwriting world data - **Legacy format support**: Detects and correctly restores backups from pre-2.38 (Unity save path format) - **Disk space checks**: Warns if insufficient space for the safety backup; skips safety backup rather than failing the restore ### Backup Management UI - **Backup history table**: View all backups per world with date, type (scheduled/manual), size, compression status - **Bulk operations**: Select and delete multiple backups at once - **Download**: Download any backup directly from the browser - **View details**: Inspect backup metadata including mod list and world settings at time of backup - **Per-world settings**: Override global backup settings (interval, retention, compression, performance) per world - **Orphan detection**: Automatically detects and flags backup records whose files are missing from disk ### Dashboard - **Storage card**: Consolidated volume status showing all mounted volumes (data, backups) with usage bars, mount paths, and capacity warnings - **Dedicated volume detection**: Uses `mountpoint` detection for accurate bind-mount identification - **Orphan warnings**: Dashboard shows count of orphaned backup records with a one-click cleanup button - **Dynamic updates**: Storage card refreshes after backup create, delete, and restore operations ### Backup Reconciliation - **Startup reconciliation**: On container start, scans for orphaned DB records (files missing) and untracked backup files (files on disk with no DB record) - **Auto-import**: Discovers backup files on disk that aren't tracked in the database and imports them - **Orphan recovery**: If a previously orphaned file reappears (e.g., volume remounted), the orphan flag is cleared automatically - **API endpoints**: Trigger reconciliation or purge orphaned records from the admin UI ### Infrastructure - **New scripts**: `worldBackupCompress`, `worldBackupRetention`, `worldBackupReconcile`, `worldActivityMonitor`, `worldRestore` - **New cron jobs**: Activity monitor (every 5 min), backup (every 10 min, self-gating), compression (hourly), retention (hourly) - **Database migration**: New `backups` table, backup settings columns in `settings` and `worlds` tables - **CSS tooltips**: Replaced native `title` tooltips with JS-powered tooltips that work inside modals - **Cloudflare Tunnel compatibility**: Backup/restore progress uses background jobs with polling instead of streaming, which Cloudflare Tunnels buffer --- ## v2.37 — macOS Apple Silicon BepInEx Fixes - Ship patched MonoMod.RuntimeDetour.dll and BepInEx.Preloader.dll for macOS arm64 - Fixes MonoMod Harmony exceptions caused by MAP_JIT W^X enforcement on M-series chips - All 8 BepInEx plugins now load with zero errors on macOS arm64 ## v2.36 — macOS Client Support - Cross-platform PhValheim Client (Windows, Linux, macOS) - Universal `.pkg` installer for macOS (Intel + Apple Silicon) ## v2.35 — Setup Wizard Fix - Fixed fresh install incorrectly showing settings modal instead of setup wizard - Removed `TZ` from env var upgrade detection loop ## v2.34 — Anonymous Usage Analytics - Optional anonymous usage analytics with opt-out - Analytics dashboard at analytics.phvalheim.com ## v2.33 — Analytics Infrastructure - Added analytics collection framework - UUID-based installation tracking ## v2.31 — Setup Wizard & DB-Backed Settings - All environment variables migrated to database settings - Setup wizard for fresh installations - Server Settings modal in admin UI - Migration notice for upgraders ## v2.27 — Mod Pack Management - Dependency resolution in PHP - Two-table mod selection layout - State-driven mod management architecture