[isaacroldan]

WHY are these changes introduced?

Fixes https://github.com/shop/issues-develop/issues/24318

Agents cannot find a running theme dev session or read its output after the command starts in another terminal.

WHAT is this pull request doing?

Use Dev Instance to record the session, preview URLs, and JSONL logs under the theme's .shopify/dev/ directory. Ownership uses the store and theme ID, so a duplicate start can report the existing session. Acquisition stays in the service.

Capture theme messages and setup progress through their current output path. Theme log records contain timestamp and message, without repeating a source field. The shared log schema allows this field to be omitted; app-dev continues to include its process sources. On Ctrl+C, SIGTERM, or loss of instance ownership, cancel dev work and drain queued output before releasing the instance. This also adds cancellation for the file watcher, theme-editor polling, and session refresh timer.

This PR does not add theme dev --json.

The shared agent workflow is in docs/cli/dev-instance-agent-workflow.md, with separate app and theme sections.

How to manually test your changes?

1. In a test store, start a development theme with pnpm shopify theme dev --path /path/to/theme --store your-store.myshopify.com --theme DEVELOPMENT_THEME_ID.
2. Read the matching instance JSON in /path/to/theme/.shopify/dev/. Check the store, theme ID, status, and preview URLs. Open its logFile, change a theme asset, and visit the local preview. Confirm that sync messages and request lines appear in the terminal and log.
3. Run the same command in another terminal. It should report the existing instance. A different port or listing does not allow a second session for the same store and theme in that directory.
4. Press Ctrl+C once. Check that the process exits, the instance JSON and lock are removed, and the JSONL log remains.

Validation and stress tests

• All 1,211 theme tests pass, including the new session and cleanup checks. Theme type checking, lint for the changed TypeScript files, the theme build, and the CLI bundle pass.
• Real child processes load the service and bootstrap from workspace sources, with remote theme setup replaced by a fixture. On Node 22 and 26, SIGINT and SIGTERM each preserve all 1,000 queued messages plus the shutdown message, exit on the first signal, and remove ownership files.
• Local HTTP tests check output after server setup and port release. Other tests cover duplicate starts, setup failure, cancellation during setup, pending file events, polling cancellation, refresh timer cleanup, and interactive stdin cleanup.
• Removing the cancellation guard makes the late-server-start regression test fail. The guard is restored.
• No live-store theme synchronization was performed.

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type and added a changeset.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/private/node/dev-instance-output.d.ts

@@ -2,18 +2,18 @@ import { zod } from '../../public/node/schema.js';
 import { Writable, type WritableOptions } from 'stream';
 export declare const devInstanceLogOutputSchema: import("../../public/node/json-output-schema.js").JsonOutputSchema<zod.ZodObject<{
     timestamp: zod.ZodString;
-    source: zod.ZodString;
+    source: zod.ZodOptional<zod.ZodString>;
     level: zod.ZodOptional<zod.ZodEnum<["debug", "info", "warning", "error"]>>;
     message: zod.ZodString;
 }, "strict", zod.ZodTypeAny, {
-    source: string;
     message: string;
     timestamp: string;
+    source?: string | undefined;
     level?: "info" | "error" | "debug" | "warning" | undefined;
 }, {
-    source: string;
     message: string;
     timestamp: string;
+    source?: string | undefined;
     level?: "info" | "error" | "debug" | "warning" | undefined;
 }>>;
 /** One line of a dev instance's JSON Lines log. */
@@ -30,7 +30,7 @@ export declare function createDevInstanceOutput({ logFile, logOutput, isActive,
         timestamp?: string;
     }) => Promise<void>;
     tee: (target: Writable, { source, stringWritesAreMessages }: {
-        source: string;
+        source?: string;
         stringWritesAreMessages?: boolean;
     }) => DevInstanceOutput;
     flush: () => Promise<PromiseSettledResult<void>[]>;

packages/cli-kit/dist/public/node/dev-instance.d.ts

@@ -80,7 +80,8 @@ export interface DevInstance {
      * The returned stream forwards the original bytes to `target` unchanged.
      */
     tee: (target: Writable, options: {
-        source: string;
+        /** Omit the source field when the stream does not need to distinguish producers. */
+        source?: string;
         /** Treat each string write as a complete message. Byte writes remain buffered into lines. */
         stringWritesAreMessages?: boolean;
     }) => Writable;