Hiro development journal

Making Hiro startup return promptly

2026.07.26 at 17:13:34 America/Los_Angeles Published Machine-readable JSON

Executive summary

Hiro's prior manual startup command successfully launched the service but remained attached to the long-running process tree, making the command appear stuck even after the dashboard was available.

A dedicated detached Windows launcher now starts Hiro with closed standard handles, a new process group, no console window, and an explicit job-breakaway flag.

The launcher normalizes the inherited Windows search path before creating the child process, waits only for the task page to become ready, and then returns structured startup information.

A real cold restart returned in approximately three seconds end to end, with Hiro ready in approximately 1.2 seconds. An idempotent second invocation returned in under 0.2 seconds without starting a duplicate.

Work completed

Startup diagnosis

Completed

Compared the interrupted launcher call with the resulting listeners and startup logs.
Confirmed that Hiro had reached application-ready state and was serving the task page while the initiating command still appeared active.
Identified descendant-process tracking and inherited process attachment as the cause of the apparent hang rather than slow application initialization.

Detached launcher

Completed

Added a checked-in Python launcher and a small Windows command wrapper using Hiro's pinned runtime.
The launcher removes duplicate case variants of the search-path variable and rebuilds one canonical Path value from the machine and user configuration.
The child starts with no standard input, file-backed output streams, closed inherited handles, no console window, a new process group, and an explicit Windows job-breakaway flag.
Startup is bounded by a configurable timeout and returns only after the task page health check succeeds.
The launcher detects an already-running healthy instance and returns immediately instead of spawning another process.

Operational restart

Completed

Stopped only the process owning Hiro's expected listeners and restarted it through the new launcher.
Confirmed that the replacement process owns the expected HTTPS, HTTP, and loopback-only internal listeners.
Confirmed that the private-network task page returned status 200 and the expected page title.

Decisions and reasoning

Keep the existing blocking runner for workflows that intentionally supervise Hiro, such as nightly preflight.
Use the new detached launcher for interactive and agent-triggered startup where the caller must return promptly.
Wait for an application-level task-page response rather than treating process creation or an open port alone as readiness.
Make startup idempotent and fail clearly if expected ports are occupied by something other than a healthy Hiro instance.

Validation and evidence

Check	Status	Result
Launcher and compatibility tests	passed	Six focused tests passed, covering the detached launcher configuration, search-path normalization, pinned runtime, server ports, and nightly preflight compatibility.
Cold detached startup	passed	The launcher returned successfully in approximately three seconds end to end and reported application readiness in approximately 1.2 seconds.
Idempotent repeat startup	passed	A second invocation returned already_running in approximately 0.18 seconds and did not create a duplicate listener.
Private-network task page	passed	The task page returned status 200 with the expected Hiro personal-list title.

Current state

Hiro is running through the detached startup path.
Interactive startup commands now return promptly after application readiness.
The existing blocking runner remains available for intentional supervision workflows.
The private task dashboard is responding normally.

Next steps

Use the detached command wrapper for future manual or agent-triggered Hiro starts.
Address the scheduler data-encoding warning in a separate scoped maintenance session.
Consider connecting the detached launcher to a supervised automatic-start mechanism if runtime availability needs to survive logoff or reboot.