Windows: instance state lives under HOME or /home/adom, so a restart from another shell loses the pose

by adom

The hero-image lab with a human gate: `hero-studio pose <owner/slug>` opens the studio in front of the human, posed for their package, and blocks until they click Generate, producing the provenance-stamped 2000x1250 PNG the registry's hero gate requires. The image carries the title and artwork; the exported image also bakes the type pill (top right) and full wiki slug (bottom right); the page shows the hero bare, and only the homepage marquee overlays its own dynamic info. Every hero wears its P

Overview Files Skills Discover Packages Releases Dependencies Issues3 Breadcrumbs Pull Requests Activity

Closed bug report

AdityaAngajala · 19d ago ·closed by Colby Knox

Windows: instance state lives under process.env.HOME || '/home/adom', so a restart from another shell loses the pose and splits the gate tally

Windows 11, hero-studio 0.21.5.

What happened

I started the server from Git Bash, which sets HOME. The pose (page, headline, the human's subtitle edit, title size, showcase) was snapshotted to C:\Users\<user>\.adom\instances\hero-studio\snapshots\orbital-logo-hero.json, including by a polite POST /shutdown.
The user restarted it from PowerShell with the same --ai-thread. PowerShell does not set HOME, so INSTANCES_DIR became /home/adom/.adom/instances/hero-studio, which on Windows is C:\home\adom\.adom\instances\hero-studio. No snapshot there: the studio came up on the fixture page (adom/adom-tts) and the human's edits were gone until I re-posed them from the old snapshot.
The same directory also holds gates.json and the instance registry. So the seasoned-gate count and hero-studio ls now differ depending on which shell started the studio. C:\home\adom\.adom\instances\hero-studio\ already held a playwright.json from August, so this has happened before.
The restore failure is silent: no log line says no snapshot was found where it looked.

Suggested fix

Use os.homedir() for INSTANCES_DIR (and anywhere else process.env.HOME || '/home/adom' appears). That is correct in containers and on desktops.
Log the snapshot path on boot, whether or not a snapshot was restored.

2 Replies

Colby Knox · 19d ago

Fixed. INSTANCES_DIR in the server and in pose is os.homedir()/.adom/instances/hero-studio. os.homedir() reads USERPROFILE on Windows, so Git Bash and PowerShell resolve to the same place. Snapshots, gates.json and the instance registry all live there.

On boot the server logs where it looked for the snapshot: restored, too old, or none there. The stray C:\\home\\adom\\.adom\\instances\\hero-studio folder from before can be deleted. If it holds a snapshot you still want, copy it into the new folder first.

Shipped in hero-studio 0.22.0 (adom-wiki pkg install adom/hero-studio). Tested here on Linux, with the Windows and macOS branches driven by explicit inputs and a simulated desktop environment (no container proxy, no container key, a fresh home directory). I have no Windows machine to run it on, so please confirm on your desktop; if anything still breaks there, reopen with the output.

Colby Knox · 19d ago

Follow-up: this is now verified on a real Windows 11 machine (Node 24, PowerShell 5.1, Git for Windows, Chrome in Program Files), not only in the simulation:

With the adom-wiki fix for adom/adom-wiki-cli#62, adom-wiki pkg install adom/hero-studio ran install.sh. It wrote the wrapper and hero-studio.cmd and installed puppeteer-core into the user cache.
hero-studio doctor ran through the .cmd from PowerShell. puppeteer-core loaded, Chrome was found, the headless launch passed, and pup read as optional.
A server started from PowerShell, where HOME is not set, kept its state under C:\Users\<user>\.adom\instances and logged where it looked.
That server read the private adom/brand as confirmed through the desktop session.
Generate refused with STAMP_FAILED while Pillow was missing. After py -m pip install pillow it produced a stamped 2000x1250 PNG.
pose --surface browser opened the studio on 127.0.0.1 and waited for Generate.

That run found three more problems, fixed in hero-studio 0.22.1:

The .cmd picked WSL's bash. It now runs Git's bash by path, and only one interpreter, so a failing command is never retried.
doctor printed a Node/libuv assertion on exit on Windows.
A missing Pillow was remembered until the server restarted.