{
  "schemaVersion": 2,
  "date": "2026.07.26",
  "publishedAt": "2026-07-26T17:13:34-07:00",
  "timeZone": "America/Los_Angeles",
  "title": "Making Hiro startup return promptly",
  "publicationStatus": "Published",
  "executiveSummary": [
    "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."
  ],
  "workstreams": [
    {
      "title": "Startup diagnosis",
      "status": "Completed",
      "details": [
        "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."
      ]
    },
    {
      "title": "Detached launcher",
      "status": "Completed",
      "details": [
        "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."
      ]
    },
    {
      "title": "Operational restart",
      "status": "Completed",
      "details": [
        "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": [
    "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": [
    {
      "check": "Launcher and compatibility tests",
      "status": "passed",
      "result": "Six focused tests passed, covering the detached launcher configuration, search-path normalization, pinned runtime, server ports, and nightly preflight compatibility."
    },
    {
      "check": "Cold detached startup",
      "status": "passed",
      "result": "The launcher returned successfully in approximately three seconds end to end and reported application readiness in approximately 1.2 seconds."
    },
    {
      "check": "Idempotent repeat startup",
      "status": "passed",
      "result": "A second invocation returned already_running in approximately 0.18 seconds and did not create a duplicate listener."
    },
    {
      "check": "Private-network task page",
      "status": "passed",
      "result": "The task page returned status 200 with the expected Hiro personal-list title."
    }
  ],
  "currentState": [
    "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."
  ],
  "limitations": [
    "The detached launcher is Windows-specific because Hiro's local runtime and process-management requirements are Windows-specific.",
    "A separate pre-existing scheduler data-encoding warning remains visible in startup logs; it did not cause the launcher attachment problem or prevent the task dashboard from starting."
  ],
  "nextSteps": [
    "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."
  ],
  "disclosureNote": "This public entry omits private network addresses, local paths, process identifiers, user data, and credential information."
}