[gonzaloriestra]

WHY are these changes introduced?

Agents cannot discover a running hydrogen dev session or read its output after it starts in another terminal. Part of https://github.com/shop/issues-develop/issues/24321, following Shopify/cli#8976.

WHAT is this pull request doing?

Use CLI Kit's Dev Instance API to record readiness, URLs, and JSONL logs under the project's .shopify/dev/ directory. Ownership uses the command, project, environment, environment branch, and environment file, so changing the port does not allow a duplicate session.

Capture runtime output while keeping terminal rendering. Exclude session files from file-change logs to prevent feedback loops. Stop owned resources and drain queued logs on startup failure, Ctrl+C, SIGTERM, or lost ownership. Cancel tunnel polling, authentication, storefront prompts, token polling, and environment loading on shutdown or another startup failure. Persist newly created storefronts before honoring cancellation, so the next run reuses their link. Preserve the previous project config if storefront provisioning fails. Wait for startup, config writes, and resource cleanup to settle before releasing ownership. Preserve Admin API network retries when passing a cancellation signal. Restore previous Customer Account URLs if setup is cancelled after the update or saving local config fails. Key symlinked projects by the env file they actually load. Describe session discovery and lifecycle behavior in command help and update the manifest.

Pin CLI Kit to 5.0.0 for the Dev Instance API, including the bundled dependency in create-hydrogen.

HOW to test your changes?

1. Build and link this checkout's CLI with the repository's usual setup (pnpm patch-cli after building).
2. Run pnpm shopify hydrogen dev --path /path/to/project against an existing Hydrogen project. Read the matching instance JSON in its .shopify/dev/ directory and follow its logFile. Confirm the status becomes running and URLs appear.
3. Change a route and visit the local server. Confirm new runtime output appears in the log while the terminal keeps its normal rendering.
4. Start the same command in another terminal, including with a different port. It should report the existing instance.
5. Press Ctrl+C once. The instance JSON and lock should disappear, while the JSONL log remains.

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or functional changes
• I've added tests to cover my changes
• I've added or updated the documentation

[shopify]

Oxygen deployed a preview of your gonzalo/hydrogen-dev-preview-instances branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	October 28, 2026 4:39 PM

Learn more about Hydrogen's GitHub integration.