Hiro development journal

Recurring Windows Path environment constraint documented

2026.07.20 at 18:53:48 America/Los_Angeles Published Machine-readable JSON

Executive summary

Recorded the recurring Windows Path/PATH case-collision as a standing Hiro workspace constraint so future planning accounts for it before introducing process launchers.

The durable guidance requires child-process startup code to collapse the search path to one canonical process-scoped Path value while preserving the remainder of the inherited environment.

The note also prohibits using Start-Process -UseNewEnvironment as a shortcut because today's API startup validation showed that discarding inherited runtime context can break Hiro's bundled Python environment.

Work completed

Durable workspace guidance

Completed

Added a Windows process environment section to the root AGENTS.md instructions used for future Hiro work.
Documented that launch environments may simultaneously contain Path and PATH even though Windows treats those names case-insensitively.
Documented the observed failure mode: PowerShell environment enumeration and Start-Process can reject the duplicate keys before a child process starts.
Specified the safe preparation step: rebuild one process-scoped Path from the machine and user Path values before spawning a Windows child.
Required preservation of all other inherited environment values, especially those used by Hiro's bundled and virtual Python runtime.
Directed future work to reuse checked-in normalized launch helpers and include a real child-process startup test whenever a new launcher is introduced.

Decisions and reasoning

Place the note in AGENTS.md rather than leaving it only in conversation history, because that file is loaded as standing workspace guidance for later sessions.
Treat Path/PATH normalization as a planning constraint, not merely an error-recovery technique after Start-Process fails.
Normalize only the process search path. Do not clear or replace the full inherited environment.
Retain real startup validation as a required gate because parser-only and validate-only checks cannot expose Windows process-environment behavior.

Validation and evidence

Check	Status	Result
Standing instruction content	passed	The root AGENTS.md now contains the Windows process environment section with the collision, normalization, environment-preservation, helper-reuse, and real-startup-test requirements.
Workspace diff validation	passed	git diff --check reported no whitespace errors for AGENTS.md.

Current state

Future Hiro planning is instructed to assume that both Path and PATH may be present in Windows launch environments.
New process launchers must normalize to one process-scoped Path before calling Start-Process.
The remaining inherited environment must be preserved; Start-Process -UseNewEnvironment is explicitly excluded.
The guidance is stored locally in the project root and is not dependent on this conversation remaining in context.

Next steps

Apply the standing normalization pattern to any future Windows startup, model-launch, dashboard, or automation scripts.
Add a real child-process startup test whenever a new launcher crosses the PowerShell-to-Python boundary.