@@ -0,0 +1,5 @@
+---
+'@shopify/cli': patch
+---
+
+Wait for file watcher readiness in app dev and stop startup when cancelled.
@@ -239,6 +239,30 @@ events from stderr; missing required input then produces a fatal error instead o
 
 ## Exempt only streaming commands
 
+`shopify app function replay --json` writes `FunctionReplayRecord` records to stdout as JSONL in watch mode.
+Each record has `type` and a UTC whole-second `timestamp`. The three record types are:
+
+- `status`: `watching` after the initial file scan completes, and `cancelled` when replay stops after cancellation.
+- `build`: `success` or `failed` after a rebuild. A failed build includes its failure message in `error`.
+- `execution`: the native Function runner `result` and the `exitCode` of that Function run. Native fields, numeric
+  tokens, and strings are preserved. `result.success: false` reports a completed Function failure.
+
+Rebuild records and executions wait for `watching`. The first execution uses the latest successful startup rebuild,
+or the original extension if no rebuild occurred. A failed startup rebuild waits for a successful rebuild before execution.
+Build failures and completed Function failures are recoverable: replay keeps watching and does not set the process
+exit code from the Function run. Build output and runner diagnostics use command diagnostic events on stderr.
+The failed build message is also available in the stdout build record; it does not create a second stderr diagnostic.
+
+Fatal setup, watcher, or runner failures stop replay, write the standard `{error: {...}}` envelope to stdout, and exit
+nonzero. They do not emit `cancelled`. On `SIGINT`, `SIGTERM`, or `SIGQUIT`, replay emits `cancelled` and exits with
+code 130, 143, or 131, respectively. When stdout closes with `EPIPE`, replay cancels and stops writing records so a
+pipeline can finish. There is no final success result. With `--no-watch --json`, replay returns one native
+`FunctionRunResult` document and uses that run's exit code instead.
+
+Setup prompts use stderr. Use `--json --no-input` for unattended replay with JSON diagnostics on stderr.
+`app function replay --json-schema` describes finite results, stdout records, fatal errors, and stderr side events.
+The stdout record definition is `FunctionReplayRecord`; `Event` describes stderr side events.
+
 `shopify app dev --json` writes dev stream records as identical JSONL bytes to stdout and the session log. Each record
 has `timestamp`, `source`, and `message`, with `level` when available. The log contains process output, preview URLs,
 and session status messages. There is no final success result. Preview errors remain log records so that the
 
@@ -689,6 +689,25 @@ describe('app-event-watcher', () => {
     })
   })
 })
+test('does not notify startup listeners when cancelled during the initial file scan', async () => {
+  await inTemporaryDirectory(async (directory) => {
+    const controller = new AbortController()
+    const app = testAppLinked({directory})
+    const fileWatcher = new FileWatcher(app, {...outputOptions, signal: controller.signal})
+    vi.spyOn(fileWatcher, 'start').mockImplementation(async () => {
+      controller.abort()
+    })
+    const watcher = new AppEventWatcher(app, undefined, undefined, fileWatcher)
+    const onStart = vi.fn()
+    const onLateStart = vi.fn()
+    watcher.onStart(onStart)
+    await watcher.start({...outputOptions, signal: controller.signal}, false)
+    watcher.onStart(onLateStart)
+    expect(onStart).not.toHaveBeenCalled()
+    expect(onLateStart).not.toHaveBeenCalled()
+  })
+})
+
 test('keeps command output context when processing native file events', async () => {
   await inTemporaryDirectory(async (directory) => {
     const nativeCallback = new AsyncResource('app-file-watcher')
 
@@ -156,6 +156,7 @@ export class AppEventWatcher extends EventEmitter {
         })
     })
     await this.fileWatcher.start()
+    if (this.options.signal.aborted) return
 
     this.ready = true
     this.emit('ready', {app: this.app, extensionEvents: this.initialEvents})
 
@@ -1,19 +1,32 @@
 import {watchReplay, type WatchReplayOptions, type ReplayWatchEvent} from './watch.js'
-import {functionReplayEventSchema} from './types.js'
-import {renderCommandEventAsJson} from '@shopify/cli-kit/node/command-events'
+import {functionReplayRecordSchema} from './types.js'
+import {emitCommandEvent} from '@shopify/cli-kit/node/command-events'
 import {formatJsonOutputTimestamp} from '@shopify/cli-kit/node/json-output-schema'
 import {outputResult, unstyled} from '@shopify/cli-kit/node/output'
+import {AsyncResource} from 'node:async_hooks'
 
 export async function watchReplayJson(options: Omit<WatchReplayOptions, 'onEvent'>): Promise<void> {
+  let stdoutClosed = false
+  const onStdoutError = (error: NodeJS.ErrnoException) => {
+    if (error.code !== 'EPIPE') return
+    stdoutClosed = true
+    options.abortController.abort()
+  }
   const onSignal = (receivedSignal: 'SIGINT' | 'SIGTERM' | 'SIGQUIT') => {
     process.exitCode = {SIGINT: 130, SIGTERM: 143, SIGQUIT: 131}[receivedSignal]
     options.abortController.abort()
   }
   process.on('shopify:signal', onSignal)
+  process.stdout.on('error', onStdoutError)
+  // Native watcher callbacks can run outside the command event context.
+  const onEvent = AsyncResource.bind((event: ReplayWatchEvent) => {
+    if (!stdoutClosed) writeEvent(event)
+  })
   try {
-    await watchReplay({...options, onEvent: writeEvent})
+    await watchReplay({...options, onEvent})
   } finally {
     process.removeListener('shopify:signal', onSignal)
+    process.stdout.removeListener('error', onStdoutError)
   }
 }
 
@@ -23,12 +36,12 @@ function writeEvent(event: ReplayWatchEvent): void {
   if (event.type === 'diagnostic') {
     const message = unstyled(event.message)
     if (message.trim().length > 0) {
-      renderCommandEventAsJson({type: 'diagnostic', timestamp, level: 'warning', message})
+      emitCommandEvent({type: 'diagnostic', level: 'warning', message})
     }
     return
   }
   if (event.type === 'execution') {
-    functionReplayEventSchema.validate({
+    functionReplayRecordSchema.validate({
       type: 'execution',
       timestamp,
       result: JSON.parse(event.resultJson),
@@ -43,10 +56,14 @@ function writeEvent(event: ReplayWatchEvent): void {
     )
   } else {
     outputResult(
-      JSON.stringify(functionReplayEventSchema.validate({type: event.type, timestamp, status: event.status})),
+      JSON.stringify(
+        functionReplayRecordSchema.validate({
+          type: event.type,
+          timestamp,
+          status: event.status,
+          ...(event.type === 'build' && event.status === 'failed' ? {error: unstyled(event.error)} : {}),
+        }),
+      ),
     )
-    if (event.type === 'build' && event.status === 'failed') {
-      renderCommandEventAsJson({type: 'diagnostic', timestamp, level: 'error', message: event.error})
-    }
   }
 }
@@ -1,10 +1,22 @@
-import {functionReplayEventSchema} from './types.js'
+import {functionReplayRecordSchema, functionReplayJsonOutputSchema} from './types.js'
 import {expect, test} from 'vitest'
 
 test.each([
   {type: 'status', timestamp: '2026-10-26T09:00:00.123Z', status: 'watching'},
   {type: 'status', timestamp: '2026-10-26T09:00:00Z', status: 'finished'},
   {type: 'build', timestamp: '2026-10-26T09:00:00Z', status: 'success', extra: true},
+  {type: 'build', timestamp: '2026-10-26T09:00:00Z', status: 'failed'},
+  {type: 'build', timestamp: '2026-10-26T09:00:00Z', status: 'success', error: 'Unexpected error'},
 ])('rejects invalid CLI-owned record fields: %j', (record) => {
-  expect(() => functionReplayEventSchema.encode(record as never)).toThrow()
+  expect(() => functionReplayRecordSchema.encode(record as never)).toThrow()
+})
+
+test('describes stdout records and Function execution outcomes', () => {
+  const schema = functionReplayJsonOutputSchema.jsonSchema
+  expect(schema.definitions).toHaveProperty('FunctionReplayRecord')
+  expect(schema.definitions).not.toHaveProperty('FunctionReplayEvent')
+  const serialized = JSON.stringify(schema)
+  expect(serialized).toContain('The exit code of this Function run, not the replay process.')
+  expect(serialized).toContain('False for a completed Function execution that failed.')
+  expect(serialized).not.toContain('the command exits nonzero')
 })
@@ -10,33 +10,43 @@ const lifecycleSchema = zod
   })
   .strict()
 
-const buildSchema = zod
-  .object({
-    type: zod.literal('build'),
-    timestamp: jsonOutputTimestampSchema,
-    status: zod.enum(['success', 'failed']),
-  })
-  .strict()
+const buildSchema = zod.discriminatedUnion('status', [
+  zod
+    .object({
+      type: zod.literal('build'),
+      timestamp: jsonOutputTimestampSchema,
+      status: zod.literal('success'),
+    })
+    .strict(),
+  zod
+    .object({
+      type: zod.literal('build'),
+      timestamp: jsonOutputTimestampSchema,
+      status: zod.literal('failed'),
+      error: zod.string().describe('The rebuild failure message.'),
+    })
+    .strict(),
+])
 
 const executionSchema = zod
   .object({
     type: zod.literal('execution'),
     timestamp: jsonOutputTimestampSchema,
     result: functionRunJsonOutputSchema.schema,
-    exitCode: zod.number().int().nonnegative(),
+    exitCode: zod.number().int().nonnegative().describe('The exit code of this Function run, not the replay process.'),
   })
   .strict()
 
-export const functionReplayEventSchema = defineJsonOutputSchema({
-  name: 'FunctionReplayEvent',
-  schema: zod.discriminatedUnion('type', [lifecycleSchema, buildSchema, executionSchema]),
+export const functionReplayRecordSchema = defineJsonOutputSchema({
+  name: 'FunctionReplayRecord',
+  schema: zod.union([lifecycleSchema, buildSchema, executionSchema]),
 })
 
 export const functionReplayJsonOutputSchema = defineJsonOutputSchema({
   name: 'FunctionReplayOutput',
-  schema: zod.union([functionRunJsonOutputSchema.schema, functionReplayEventSchema.schema]),
+  schema: zod.union([functionRunJsonOutputSchema.schema, functionReplayRecordSchema.schema]),
   definitions: {
     FunctionRunResult: functionRunJsonOutputSchema.schema,
-    FunctionReplayEvent: functionReplayEventSchema.schema,
+    FunctionReplayRecord: functionReplayRecordSchema.schema,
   },
 })
@@ -276,6 +276,55 @@ test.each(['watching', 'running', 'diagnostic'])(
   },
 )
 
+test.each([false, true])('defers startup rebuilds and uses the latest extension (build failed: %s)', async (failed) => {
+  const {options, events, emit, startWatcher, start} = await fixture()
+  const updatedExtension = await testFunctionExtension({
+    config: {
+      ...options.extension.configuration,
+      build: {...options.extension.configuration.build, path: 'dist/updated.wasm', wasm_opt: true},
+    },
+  })
+  let finishStartup!: () => void
+  startWatcher.mockReturnValue(
+    new Promise((resolve) => {
+      finishStartup = resolve
+    }),
+  )
+  const running = start()
+  try {
+    await flushPromises()
+    emit([
+      {
+        type: EventType.Updated,
+        extension: updatedExtension,
+        buildResult: failed
+          ? {status: 'error', error: 'Compilation failed', uid: updatedExtension.uid}
+          : {status: 'ok', uid: updatedExtension.uid},
+      },
+    ])
+    await flushPromises()
+    expect(events).toEqual([])
+    expect(captureFunctionRun).not.toHaveBeenCalled()
+    finishStartup()
+    await flushPromises()
+    expect(events.slice(0, 2)).toEqual([
+      {type: 'status', status: 'watching'},
+      failed ? {type: 'build', status: 'failed', error: 'Compilation failed'} : {type: 'build', status: 'success'},
+    ])
+    if (failed) {
+      expect(captureFunctionRun).not.toHaveBeenCalled()
+      emit([{type: EventType.Updated, extension: updatedExtension}])
+      await flushPromises()
+    }
+    expect(captureFunctionRun).toHaveBeenCalledOnce()
+    expect(vi.mocked(captureFunctionRun).mock.calls[0]![0].functionExtension).toBe(updatedExtension)
+  } finally {
+    finishStartup()
+    options.abortController.abort()
+    await running
+  }
+})
+
 test.each(['startup', 'watcher', 'runner', 'invalid-result'])('propagates a fatal %s failure', async (source) => {
   const {options, events, startWatcher} = await fixture()
   const error = new Error('Watch failed')
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@shopify/cli': patch
 +---
++
 +Wait for file watcher readiness in app dev and stop startup when cancelled.