@tempo-ai/mcp 0.0.103 → 0.0.104

package/dist/{serve-P7M4UFJS.js → serve-FWQ5ZBR7.js}

@@ -15,7 +15,7 @@ import {
   readAuthSync,
   resolveConvexSiteUrl,
   resolveConvexUrl
-} from "./chunk-KQNQSVOA.js";
+} from "./chunk-KFUOQZBJ.js";
 
 // ../../node_modules/.pnpm/cronstrue@3.24.0/node_modules/cronstrue/dist/cronstrue.js
 var require_cronstrue = __commonJS({
@@ -7820,6 +7820,46 @@ async function assertCanvasEndpointsShareable(endpoints, checkCanvasPushState) {
     });
   }
 }
+async function assertCanvasEndpointsHavePreviews(endpoints, deps) {
+  const ensure = deps.ensureCanvasPreview;
+  if (!ensure) return;
+  for (const endpoint of endpoints) {
+    if (!endpoint || typeof endpoint !== "object") continue;
+    const ep = endpoint;
+    if (ep.type !== "canvas") continue;
+    if (!ep.orgProjectId || !ep.canvasPath || !ep.branch) continue;
+    let hasPreview = false;
+    try {
+      const snapshot = await deps.convex.query(
+        api.canvasIndex.getCanvasPreviewSnapshot,
+        {
+          orgProjectId: ep.orgProjectId,
+          canvasPath: ep.canvasPath,
+          branch: ep.branch
+        }
+      );
+      hasPreview = (snapshot?.storyboards?.length ?? 0) > 0;
+    } catch {
+      hasPreview = false;
+    }
+    if (hasPreview) continue;
+    const result = await ensure({
+      orgProjectId: ep.orgProjectId,
+      canvasPath: ep.canvasPath,
+      branch: ep.branch
+    });
+    if (result.ok) continue;
+    throw new McpToolError({
+      code: "canvas_preview_capture_failed",
+      message: `Cannot link canvas "${ep.canvasPath}": a linked canvas must have a rendered preview so it is reviewable from the issue/doc it is linked to, and capturing one failed: ${result.message} Fix the capture (make sure the canvas devserver is running and the canvas's storyboards render \u2014 canvas_screenshot is a quick check), then retry link_items. No link was created.`,
+      details: {
+        canvasPath: ep.canvasPath,
+        branch: ep.branch,
+        captureFailure: result.message
+      }
+    });
+  }
+}
 async function resolveCanvasEndpoint(endpoint, resolve2) {
   if (!resolve2) return endpoint;
   const ep = endpoint;
@@ -7900,7 +7940,7 @@ function registerArtifactTools(server, deps) {
   const { convex, getWritePermission } = deps;
   server.tool(
     "link_items",
-    "Create a bidirectional link between two items in ONE call. Endpoint types: 'issue' (issueId \u2014 a human id like TEM-42 or a Convex id; either works), 'doc' (cloud doc \u2014 pass docId from docs_create), 'canvas', or 'branch' (orgProjectId + branchName). Links point at a BRANCH, never at one person's workspace, so everyone in the org sees the work. A 'workspace' endpoint (orgProjectId + localBranch) is still accepted and is TRANSLATED to the branch it sits on. Issue, doc, workspace, and branch links are created immediately. To link a CANVAS, pass just { type: 'canvas', canvasPath: '<slug, folder, or .canvas.tsx path>' } \u2014 the slug you gave canvas_create, or the canvas_dir/file_path returned by canvas_list. The server fills in the project id and git branch from the active workspace and normalizes the path. Canvas endpoints must match the active workspace project and their named branch must be positively verified on that repository's remote; the active branch must also be clean with no unpushed commits. Otherwise the tool returns branch_not_pushed and creates no link. Commit and push the canvas, then retry link_items so collaborators can fetch it.",
+    "Create a bidirectional link between two items in ONE call. Endpoint types: 'issue' (issueId \u2014 a human id like TEM-42 or a Convex id; either works), 'doc' (cloud doc \u2014 pass docId from docs_create), 'canvas', or 'branch' (orgProjectId + branchName). Links point at a BRANCH, never at one person's workspace, so everyone in the org sees the work. A 'workspace' endpoint (orgProjectId + localBranch) is still accepted and is TRANSLATED to the branch it sits on. Issue, doc, workspace, and branch links are created immediately. To link a CANVAS, pass just { type: 'canvas', canvasPath: '<slug, folder, or .canvas.tsx path>' } \u2014 the slug you gave canvas_create, or the canvas_dir/file_path returned by canvas_list. The server fills in the project id and git branch from the active workspace and normalizes the path. Canvas endpoints must match the active workspace project and their named branch must be positively verified on that repository's remote; the active branch must also be clean with no unpushed commits. Otherwise the tool returns branch_not_pushed and creates no link. Commit and push the canvas, then retry link_items so collaborators can fetch it. A linked canvas must also have a rendered PREVIEW: when none exists yet for the exact branch, the tool captures one at link time (the canvas devserver must be able to render the storyboards); if that capture fails it returns canvas_preview_capture_failed with the reason and creates no link \u2014 fix the render, then retry.",
     {
       endpointA: coercibleEndpointSchema(),
       endpointB: coercibleEndpointSchema()
@@ -7929,6 +7969,7 @@ function registerArtifactTools(server, deps) {
           [endpointA, endpointB],
           deps.checkCanvasPushState
         );
+        await assertCanvasEndpointsHavePreviews([endpointA, endpointB], deps);
         const linkId = await convex.mutation(api.artifact_links.createLink, {
           orgId: ctx.orgId,
           endpointA,
@@ -8912,6 +8953,7 @@ function createIssuesMcpServer(context) {
     convex,
     getWritePermission,
     checkCanvasPushState: context.checkCanvasPushState,
+    ensureCanvasPreview: context.ensureCanvasPreview,
     resolveCanvasLinkEndpoint: context.resolveCanvasLinkEndpoint,
     getWorkspaceEndpoint: context.getWorkspaceEndpoint,
     getOriginChatTabId: context.getOriginChatTabId,
@@ -15519,12 +15561,13 @@ scaffolded project.
 | \`scripts.install\` | string | Command to install dependencies (runs from the tempo root). A plain package-manager install (bare \`npm install\`/\`pnpm install\`/\u2026 or Tempo's chained \`cd .. && \u2026 && cd tempo && \u2026\` form) means "use Tempo's default install behavior": Tempo plans its own project-root + tempo-root installs with the detected package manager and the exact string is not executed. Anything else is a CUSTOM command \u2014 it runs verbatim from the tempo root, must cover BOTH roots' dependencies itself, and **Tempo never rewrites it**, so an edit you make here sticks. Only write a custom command when the default behavior actually fails (e.g. a \`root_deps_missing\` error on an unusual monorepo). |
 | \`scripts.start\` | string | Canvas-host launcher (runs from the tempo root). Prefer a foreground process. Tempo substitutes every literal \`\${PORT}\`, exports the same port as \`TEMPO_PORT\`, and sets \`TEMPO=true\`. |
 | \`scripts.stop\` | string? | Matching teardown for a daemonized/external host. Tempo substitutes \`\${PORT}\` and runs this before signalling the launcher group. Required when \`scripts.start\` exits successfully while the host continues in the background. |
-| \`urls.tempoHost\` | URL string? | Public \`/tempo-host\` URL to probe when stdout cannot describe the reachable boundary (containers, tunnels, remotes). May contain \`\${PORT}\`; e.g. \`http://127.0.0.1:\${PORT}/tempo-host\`. |
-| \`apps\` | array? | \`[{ "appDir"?, "start"?, "url"? }]\` \u2014 one entry per client app; only \`apps[0]\` is active today. \`start\` launches the user's REAL app for route storyboards and may be any foreground command; \`url\` optionally supplies the independent HTTP(S) readiness target and route base. \`\${APP_PORT}\` is an optional allocated-port helper and legacy \`\${PORT}\` remains supported. Legacy \`apps[].appStart\`, \`scripts.appStart\`, and top-level \`appDir\` still read and auto-migrate. |
+| \`urls.tempoHost\` | URL source? | Public \`/tempo-host\` URL to probe when stdout cannot describe the reachable boundary (containers, tunnels, remotes). Either an HTTP(S) string (which may contain \`\${PORT}\`) or \`{ "command": "..." }\`; the command runs once per launch and must print exactly one HTTP(S) URL. |
+| \`apps\` | array? | \`[{ "appDir"?, "start"?, "stop"?, "url"? }]\` \u2014 one entry per client app; only \`apps[0]\` is active today. \`start\` launches the user's REAL app for route storyboards. \`url\` is either an HTTP(S) string or \`{ "command": "..." }\`; a command runs once per launch and must print exactly one HTTP(S) URL. \`stop\` supplies teardown authority when \`start\` launches a container, tunnel, daemon, or remote workspace and exits. \`\${APP_PORT}\` is an optional allocated-port helper and legacy \`\${PORT}\` remains supported in all three fields. Legacy \`apps[].appStart\`, \`scripts.appStart\`, and top-level \`appDir\` still read and auto-migrate. |
 
 **Every command in this file runs through the platform shell \u2014 \`cmd.exe\` on
 Windows, not PowerShell.** That applies to \`scripts.install\` and
-\`scripts.start\` exactly as it does to app \`start\`. Write plain, cross-platform
+\`scripts.start\` exactly as it does to app \`start\`, \`stop\`, and
+\`url.command\` and \`urls.tempoHost.command\`. Write plain, cross-platform
 invocations; \`&&\` and \`cd\` are fine (cmd supports both). Never use PowerShell
 syntax \u2014 \`if (Test-Path \u2026) { \u2026 } else { \u2026 }\`, \`Test-Path\`, \`$env:FOO\` \u2014 because
 cmd.exe cannot parse it and aborts with "X was unexpected at this time" BEFORE
@@ -15665,7 +15708,7 @@ When Tempo starts the devserver (via the \`scripts.start\` command), it sets:
 - \`NODE_ENV=development\` \u2014 ensures React dev mode (needed for fiber-based element selection)
 - \`TEMPO=true\` \u2014 activates Tempo's framework-specific annotations: \`tempoVitePlugin()\` for Vite, \`tempoNextjsPlugin()\` for Next.js, and \`tempoExpoBabelPlugin\` for Expo web
 
-The host URL is detected from local URLs printed by the framework server; \`urls.tempoHost\`, when configured, is probed alongside the printed URL and wins whenever the printed URL is not reachable from Tempo (containers, tunnels, remotes). A literal \`urls.tempoHost\` (no \`\${PORT}\` token) is additionally probed without waiting for any stdout URL at all. Vite, Next.js, and Expo web can all use dynamic ports; agents should not hard-code a port into Expo setup unless the user explicitly asks for one.
+The host URL is detected from local URLs printed by the framework server; \`urls.tempoHost\`, when configured, is probed alongside the printed URL and wins whenever the printed URL is not reachable from Tempo (containers, tunnels, remotes). A literal \`urls.tempoHost\` (no \`\${PORT}\` token) is additionally probed without waiting for any stdout URL at all. A command-backed \`urls.tempoHost\` executes exactly once with \`TEMPO_PORT\` and \`PORT\` after spawn; when \`scripts.stop\` is configured it waits for the launcher to exit cleanly first, then the resolved URL owns liveness and stop owns teardown. Vite, Next.js, and Expo web can all use dynamic ports; agents should not hard-code a port into Expo setup unless the user explicitly asks for one.
 
 #### Customizing the launcher \u2014 decision ladder
 
@@ -15682,6 +15725,8 @@ Work down and stop at the FIRST line that fits; change nothing beyond it:
    with the reachable \`/tempo-host\` URL (use \`\${PORT}\` in it unless the
    boundary fixes the port), and forward \`TEMPO\` and \`TEMPO_PORT\` across the
    boundary.
+   If the boundary chooses its URL dynamically, use
+   \`{ "command": "..." }\`; the command's entire stdout must be that one URL.
 4. **Launcher exits after starting the real server** (e.g.
    \`docker compose up --detach\`)? Add \`scripts.stop\` as the matched
    teardown \u2014 without it the start fails with
@@ -15696,7 +15741,9 @@ Work down and stop at the FIRST line that fits; change nothing beyond it:
   attempt \u2014 unless \`urls.tempoHost\` spells a literal port (no \`\${PORT}\`
   token), which pins every attempt to that port. Either way it substitutes
   every literal \`\${PORT}\` in \`scripts.start\`, \`scripts.stop\`, and
-  \`urls.tempoHost\`, and always exports the chosen number as \`TEMPO_PORT\`.
+  a string \`urls.tempoHost\` or \`urls.tempoHost.command\`, and always exports
+  the chosen number as \`TEMPO_PORT\` (and as \`PORT\` when an explicit URL
+  source participates in launch).
   Custom launchers should read \`TEMPO_PORT\` or use the token; do not assume
   Tempo will overwrite a generic ambient \`PORT\` variable.
 - \`scripts.start\` should normally stay in the foreground. Tempo then owns the
@@ -15920,7 +15967,7 @@ export default function AuthComponentsCanvas() {
 
 Canvases created before the React format use object exports instead of JSX \u2014 \`export const Login: TempoStoryboard = { render: () => <LoginForm />, layout: {\u2026} }\` with a \`TempoCanvasConfig\` default export. Tempo migrates these to the React format automatically when they are opened in the Design tab. If you encounter one, run \`canvas_migrate_to_latest\` on it BEFORE making any edit \u2014 never hand-write legacy declarations, and never mix the two formats in one file.
 
-### Route Storyboards & the app dev config (\`apps[0].start\` / \`url\`)
+### Route Storyboards & the app dev config (\`apps[0].start\` / \`stop\` / \`url\`)
 
 Route storyboards (\`<RouteStoryboard>\`) load **the user's real app** in the iframe, NOT the canvas sidecar. They need a second supervised process \u2014 the user's actual app dev server \u2014 which Tempo manages from the app dev command in \`tempo.config.json\`, stored canonically on the \`apps[]\` list (one entry per client app; only \`apps[0]\` is active today):
 
@@ -15933,14 +15980,34 @@ Route storyboards (\`<RouteStoryboard>\`) load **the user's real app** in the if
   "apps": [
     {
       "appDir": "client",                          // app package dir, relative to repo root (omit for autodetect)
-      "start": "npm exec vite --port=\${APP_PORT}",    // arbitrary foreground command
-      "url": "http://127.0.0.1:\${APP_PORT}"           // optional HTTP(S) liveness target
+      "start": "make remote-workspace",                    // foreground server OR short-lived launcher
+      "stop": "make stop-remote-workspace",                 // required when start exits after handoff
+      "url": { "command": "make --silent show-workspace-url" } // or a literal HTTP(S) URL
     }
   ]
 }
 \`\`\`
 
-(Files written by older Tempo versions may still carry \`apps[].appStart\`, \`scripts.appStart\`, or top-level \`appDir\`. They read normally and migrate to canonical \`apps[].start\` on the next config write.)
+(Files written by older Tempo versions may still carry \`apps[].appStart\`, \`scripts.appStart\`, or top-level \`appDir\`. They read normally and migrate to \`apps[].start\` / \`apps[].appDir\` on the next config write.)
+
+The three app commands share one launch context: Tempo runs them from
+\`appDir\` and exports the selected port as \`APP_PORT\`, \`PORT\`, and
+\`TEMPO_APP_PORT\` (literal \`\${APP_PORT}\` and legacy \`\${PORT}\` tokens are
+also substituted). A command-backed \`url\` runs exactly once after spawn; in
+the \`stop + url.command\` handoff shape, it waits for \`start\` to exit cleanly
+first so a URL getter cannot race remote provisioning. It is bounded and
+abortable, and its entire trimmed stdout must be one HTTP(S) URL; Tempo never
+guesses whether a string is executable. Readiness is always HTTP-probed at the
+resolved URL.
+
+For an ordinary foreground dev server, the child process owns liveness and
+\`stop\` is optional. If \`start\` exits successfully before readiness, Tempo
+accepts the handoff only when \`stop\` is configured; the resolved URL then
+owns liveness, repeated probe failures demote the server, and \`stop\` owns
+teardown. Tempo persists the exact stop command, cwd, port, and resolved URL
+so the next session can reconcile a remote/container runtime after a hard
+crash instead of launching a duplicate. A failed URL command or readiness
+timeout after handoff also runs \`stop\` immediately.
 
 **The app's own bundler config MUST include the Tempo annotation plugin.** Route storyboards are served by the user's app dev server (NOT the \`tempo/\` sidecar), so the canvas can only select/edit their elements if THAT server injects the \`data-tempo-*\` annotations \u2014 i.e. the **app's own** framework config carries the Tempo plugin, active under \`TEMPO=true\`. Without it the app still renders in the iframe, but every click collapses to one unmappable root and the user reports *"route storyboard elements are not clickable."* This is separate from the \`tempo/\` sidecar's plugin (\xA74.2) \u2014 both configs need it, for different servers. Add the plugin to the app package (and add \`tempo-sdk\` to the app's deps) per framework:
 
@@ -15998,8 +16065,8 @@ The plugin no-ops unless \`TEMPO=true\` (which the supervisor sets when it runs
 Mechanics:
 
 - The supervisor always allocates a free local TCP port per workspace and persists it at \`<workspaceRoot>/.tempo/app-devserver.json\` (gitignored, per-worktree).
-- A \`url\` containing \`\${APP_PORT}\` (or legacy \`\${PORT}\`) uses that allocated helper value. A literal URL is an opaque HTTP(S) readiness target and route base: its hostname and port never control local allocation, so it may point through a container, tunnel, or remote machine.
-- Every literal \`\${APP_PORT}\` or legacy \`\${PORT}\` in app \`start\` and \`url\` is substituted before spawn/probe. The renderer resolves route storyboard paths against the resulting URL.
+- A string \`url\` containing \`\${APP_PORT}\` (or legacy \`\${PORT}\`) uses that allocated helper value. A literal URL is an opaque HTTP(S) readiness target and route base: its hostname and port never control local allocation, so it may point through a container, tunnel, or remote machine. A \`{ command }\` URL resolves the same target dynamically once per launch.
+- Every literal \`\${APP_PORT}\` or legacy \`\${PORT}\` in app \`start\`, \`stop\`, and \`url.command\` (or a string \`url\`) is substituted before execution/probing. The renderer resolves route storyboard paths against the resulting URL.
 - Lifecycle: warm with a 5-minute idle stop \u2014 the supervisor stays alive while a canvas with route storyboards is open and stops 5 minutes after the last canvas closes.
 - While starting, an overlay reads "Starting your app dev server\u2026" on every route storyboard.
 
@@ -16016,7 +16083,7 @@ Mechanics:
 
 **When using the allocated helper port, invoke the bundler binary directly \u2014 do NOT route the port flag through \`<pm> run dev -- --port=\${APP_PORT}\`.** When the \`dev\` script is a bare \`vite\` (the common case) and the project uses **pnpm**, that form can forward the literal \`--\` separator through to Vite, which treats it as a positional arg and ignores \`--port\`. The direct-exec form (\`pnpm exec vite \u2026\` / \`npx vite \u2026\`) is correct under every package manager. (\`--strictPort\` makes a mismatch fail loudly.)
 
-The command is otherwise arbitrary. The allocated helper token is optional, and a configured \`url\` is always the liveness target Tempo probes.
+The command is otherwise arbitrary. The allocated helper token is optional. A configured \`url\` is always the readiness target Tempo probes and becomes the ongoing liveness authority after a clean launcher handoff.
 
 **Independent readiness URL.** Use a literal \`url\` whenever the URL Tempo can reach differs from the locally allocated port, including a container, tunnel, or remote machine:
 
@@ -16031,9 +16098,14 @@ The command is otherwise arbitrary. The allocated helper token is optional, and
 
 The supervisor probes \`url\` directly rather than waiting for stdout URL discovery and uses it as the public route base after it responds. The local helper port remains independently allocated and available to \`start\` through \`APP_PORT\`, \`PORT\`, and \`TEMPO_APP_PORT\`, even when the literal URL spells a completely different host or explicit port.
 
-**Keep the command plain and cross-platform \u2014 one invocation, no shell conditionals.** Tempo spawns it through the platform shell (**cmd.exe on Windows**, not PowerShell) and substitutes \`\${APP_PORT}\` (or legacy \`\${PORT}\`) before spawning. A leading \`NAME=value\` prefix \u2014 for example \`PORT=\${APP_PORT} npm run dev\` \u2014 is also safe on every OS: the supervisor lifts it into the spawn environment instead of handing it to the shell, and it always sets \`APP_PORT\`, \`PORT\`, and \`TEMPO_APP_PORT\` in the environment regardless. Never use PowerShell syntax \u2014 \`if (Test-Path \u2026) { \u2026 } else { \u2026 }\`, \`Test-Path\`, \`$env:FOO\`, \`Get-\`/\`Set-\` cmdlets \u2014 cmd.exe can't parse it and aborts before running anything. If the app lives in a subdirectory, set \`appDir\` instead of changing directories inside the command.
+Use \`url: { command: "..." }\` when that target can only be discovered after
+\`start\`, such as a newly allocated remote workspace or tunnel. The explicit
+object is the execution boundary: plain URL strings are never treated as shell
+commands.
+
+**Keep every command plain and cross-platform \u2014 one invocation, no shell conditionals.** Tempo spawns \`start\`, \`stop\`, and \`url.command\` through the platform shell (**cmd.exe on Windows**, not PowerShell) and substitutes \`\${APP_PORT}\` (or legacy \`\${PORT}\`) before spawning. A leading \`NAME=value\` prefix \u2014 for example \`PORT=\${APP_PORT} npm run dev\` \u2014 is also safe on every OS for \`start\`: the supervisor lifts it into the spawn environment instead of handing it to the shell, and it always sets \`APP_PORT\`, \`PORT\`, and \`TEMPO_APP_PORT\` in the environment regardless. Never use PowerShell syntax \u2014 \`if (Test-Path \u2026) { \u2026 } else { \u2026 }\`, \`Test-Path\`, \`$env:FOO\`, \`Get-\`/\`Set-\` cmdlets \u2014 cmd.exe can't parse it and aborts before running anything. If the app lives in a subdirectory, set \`appDir\` instead of changing directories inside the command.
 
-**Driving the lifecycle directly.** Three sibling tools mirror the canvas-sidecar trio: \`check_app_dev_server\` / \`start_app_dev_server\` / \`stop_app_dev_server\` (vs \`check_canvas_devserver\` / \`start_canvas_devserver\` / \`stop_canvas_devserver\`). \`check_app_dev_server\` returns \`{configured, running, phase, port, url, error}\` \u2014 call it first when a route storyboard isn't loading, to disambiguate: \`configured: false\` \u2192 \`set_app_dev_command\`; \`configured: true, running: false\` \u2192 read \`error\`, then \`start_app_dev_server\`; \`running: true\` \u2192 the route itself is the problem, not the supervisor. After editing the app dev command, \`stop_app_dev_server\` then \`start_app_dev_server\` to pick up the new command.
+**Driving the lifecycle directly.** Three sibling tools mirror the canvas-sidecar trio: \`check_app_dev_server\` / \`start_app_dev_server\` / \`stop_app_dev_server\` (vs \`check_canvas_devserver\` / \`start_canvas_devserver\` / \`stop_canvas_devserver\`). \`check_app_dev_server\` returns \`{configured, running, phase, port, url, livenessSource, error}\` \u2014 call it first when a route storyboard isn't loading, to disambiguate: \`configured: false\` \u2192 \`set_app_dev_command\`; \`configured: true, running: false\` \u2192 read \`error\`, then \`start_app_dev_server\`; \`running: true\` \u2192 the route itself is the problem, not the supervisor. \`livenessSource: "probe"\` identifies an external-runtime handoff; \`"child"\` identifies a foreground app process. After editing the app dev command, \`stop_app_dev_server\` then \`start_app_dev_server\` to pick up the new command.
 
 **Pre-existing canvases with blank route iframes** on a project without an app dev command are a config gap, not a bug \u2014 call \`set_app_dev_command\` and the iframes light up.
 
@@ -24391,6 +24463,66 @@ async function atomicWriteText(filePath, content) {
   }
 }
 
+// ../tempo-devserver/http-url-source.ts
+var ANSI_ESCAPE_RE2 = /\x1b\[[0-9;]*m/g;
+async function resolveHttpUrlSource(options) {
+  if (typeof options.source === "string") {
+    return options.substitutePort(options.source, options.port);
+  }
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  let result;
+  try {
+    result = await runAbortableShellCommand({
+      command: options.substitutePort(options.source.command, options.port),
+      cwd: options.cwd,
+      env: options.env,
+      signal: controller.signal,
+      maxOutputBytes: 4e3
+    });
+  } finally {
+    clearTimeout(timeout);
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+  if (result.aborted) {
+    if (options.signal?.aborted) {
+      throw new Error(`${options.label}.command was aborted`);
+    }
+    throw new Error(
+      `${options.label}.command timed out after ${options.timeoutMs}ms`
+    );
+  }
+  if (result.spawnError) {
+    throw new Error(
+      `${options.label}.command could not start: ${result.spawnError.message}`
+    );
+  }
+  if (result.exitCode !== 0) {
+    const detail = result.stderr.trim();
+    throw new Error(
+      `${options.label}.command exited with code ${result.exitCode ?? "unknown"}${detail ? `: ${detail}` : ""}`
+    );
+  }
+  const output = result.stdout.replace(ANSI_ESCAPE_RE2, "").trim();
+  let parsed;
+  try {
+    parsed = new URL(output);
+  } catch {
+    throw invalidOutputError(options.label);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || output.includes("\n") || output.includes("\r")) {
+    throw invalidOutputError(options.label);
+  }
+  return output;
+}
+function invalidOutputError(label) {
+  return new Error(
+    `${label}.command must print exactly one valid HTTP(S) URL to stdout`
+  );
+}
+
 // ../tempo-devserver/app-devserver.ts
 var APP_DEVSERVER_STATE_FILENAME = "app-devserver.json";
 var APP_DEVSERVER_LOG_FILENAME = "app-devserver.log";
@@ -24401,8 +24533,8 @@ var DEFAULT_HTTP_READY_TIMEOUT_MS = 18e4;
 var HTTP_PROBE_ATTEMPT_TIMEOUT_MS = 5e3;
 var HTTP_PROBE_ABSOLUTE_CAP_MS = 6e5;
 var PUBLIC_HOSTNAME = "127.0.0.1";
-var PERSISTED_STATE_VERSION = 5;
-var ANSI_ESCAPE_RE2 = /\x1b\[[0-9;]*m/g;
+var PERSISTED_STATE_VERSION = 6;
+var ANSI_ESCAPE_RE3 = /\x1b\[[0-9;]*m/g;
 var URL_RE = /https?:\/\/[^\s"'`<>]+/gi;
 var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set([
   "127.0.0.1",
@@ -24421,6 +24553,12 @@ var AppDevServer = class _AppDevServer {
       error: null
     };
     this.child = null;
+    this.launcherFinished = false;
+    this.commandEnv = null;
+    this.urlHealthProbeTimer = null;
+    this.urlHealthProbeUrl = null;
+    this.urlHealthProbeConsecutiveFailures = 0;
+    this.urlHealthProbeInFlight = false;
     /** Invalidates late stdout/stderr/exit events from an earlier start cycle. */
     this.outputEpoch = 0;
     this.recentOutput = [];
@@ -24469,11 +24607,15 @@ var AppDevServer = class _AppDevServer {
     this.hasParentDeathWatchdog = false;
     this.options = {
       command: options.command,
+      stop: options.stop,
       url: options.url,
       cwd: path12.resolve(options.cwd),
       workspaceRoot: path12.resolve(options.workspaceRoot),
       urlScrapeTimeoutMs: resolveUrlScrapeTimeout(options.urlScrapeTimeoutMs),
       httpReadyTimeoutMs: resolveHttpReadyTimeout(options.httpReadyTimeoutMs),
+      urlCommandTimeoutMs: options.urlCommandTimeoutMs ?? 3e4,
+      urlHealthProbeIntervalMs: options.urlHealthProbeIntervalMs ?? 5e3,
+      urlHealthFailuresToDemote: options.urlHealthFailuresToDemote ?? 3,
       portRange: options.portRange ?? DEFAULT_PORT_RANGE,
       ownership: options.ownership
     };
@@ -24491,6 +24633,7 @@ var AppDevServer = class _AppDevServer {
   getStatus() {
     return {
       ...this.status,
+      livenessSource: this.status.phase === "running" ? this.launcherFinished ? "probe" : "child" : null,
       recentOutputTail: this.recentOutput.join("").slice(-2e3)
     };
   }
@@ -24531,6 +24674,11 @@ var AppDevServer = class _AppDevServer {
     if (ownership !== "reapable") {
       return ownership;
     }
+    let externalRuntimeReaped = false;
+    if (persisted.externalRuntime) {
+      externalRuntimeReaped = await this.cleanupPersistedExternalRuntime(persisted);
+      if (!externalRuntimeReaped) return "orphan_cleanup_failed";
+    }
     const identities = [
       [persisted.pid, persisted.pidStartedAt, "shell"],
       [persisted.serverPid, persisted.serverPidStartedAt, "server"]
@@ -24538,7 +24686,9 @@ var AppDevServer = class _AppDevServer {
     const hadProcessIdentity = identities.some(
       ([pid, startedAt]) => pid != null && startedAt != null
     );
-    if (!hadProcessIdentity) return "nothing_to_reconcile";
+    if (!hadProcessIdentity) {
+      return externalRuntimeReaped ? "orphan_reaped" : "nothing_to_reconcile";
+    }
     if (persisted.pid != null && await pidStartIdentityMatches(persisted.pid, persisted.pidStartedAt)) {
       const outcome = await reapOwnedProcessGroup(persisted.pid);
       devLog("app-devserver:registry-orphan-group-reap", {
@@ -24581,6 +24731,27 @@ var AppDevServer = class _AppDevServer {
     await this.persistServerPid(null);
     return "orphan_reaped";
   }
+  async cleanupPersistedExternalRuntime(persisted) {
+    const external = persisted.externalRuntime;
+    if (!external) return true;
+    const result = await this.runBoundedCommand(
+      external.stopCommand,
+      persisted.port,
+      1e4,
+      void 0,
+      external.cwd
+    );
+    devLog("app-devserver:persisted-external-stop", {
+      command: external.stopCommand,
+      exitCode: result.exitCode,
+      aborted: result.aborted,
+      spawnError: result.spawnError?.message ?? null,
+      workspaceRoot: this.options.workspaceRoot
+    });
+    const stopped = external.url ? await waitForAppUrlUnreachable(external.url, 5e3) : describeShellCommandFailure(result) === null;
+    if (stopped) await this.persistExternalRuntime(null);
+    return stopped;
+  }
   onStatusChange(listener) {
     this.listeners.push(listener);
     return () => {
@@ -24643,6 +24814,7 @@ var AppDevServer = class _AppDevServer {
    */
   forceKill() {
     this.intentionalStop = true;
+    this.stopUrlHealthProbe();
     this.outputEpoch += 1;
     this.clearOutputBroadcastTimer();
     const child = this.child;
@@ -24726,8 +24898,12 @@ var AppDevServer = class _AppDevServer {
     const outputEpoch = ++this.outputEpoch;
     this.setStatus({ phase: "starting", error: null });
     this.intentionalStop = false;
+    this.launcherFinished = false;
+    this.commandEnv = null;
+    this.stopUrlHealthProbe();
     this.detectedBaseUrl = null;
     this.recentOutput = [];
+    let startSpawned = false;
     const dialectIssue = findPowerShellSyntax(this.options.command);
     if (dialectIssue) {
       const error = `The app dev command was rejected before spawn: it contains PowerShell-only syntax (${dialectIssue}), which the shell Tempo runs commands with (cmd.exe on Windows) cannot parse \u2014 nothing was started. Rewrite "apps[0].start" in tempo.config.json as a single plain cross-platform command \u2014 use \${APP_PORT} only if it needs Tempo's allocated helper port \u2014 and if the app lives in a subdirectory set "appDir" instead of cd/pushd-ing inside the command (chaining with \`&&\` is fine; cmd supports it).`;
@@ -24738,6 +24914,19 @@ var AppDevServer = class _AppDevServer {
       this.setStatus({ phase: "error", error, url: null });
       return { ok: false, url: null, error };
     }
+    const stopDialectIssue = this.options.stop ? findPowerShellSyntax(this.options.stop) : null;
+    if (stopDialectIssue) {
+      const error = `The app stop command was rejected before spawn: it contains PowerShell-only syntax (${stopDialectIssue}). Rewrite "apps[0].stop" as one plain cross-platform command.`;
+      this.setStatus({ phase: "error", error, url: null });
+      return { ok: false, url: null, error };
+    }
+    const urlCommand = typeof this.options.url === "object" ? this.options.url.command : null;
+    const urlDialectIssue = urlCommand ? findPowerShellSyntax(urlCommand) : null;
+    if (urlDialectIssue) {
+      const error = `The app URL command was rejected before spawn: it contains PowerShell-only syntax (${urlDialectIssue}). Rewrite "apps[0].url.command" as one plain cross-platform command.`;
+      this.setStatus({ phase: "error", error, url: null });
+      return { ok: false, url: null, error };
+    }
     await this.truncateLogFile();
     throwIfAppLaunchAborted(signal);
     let removeAbortListener = () => {
@@ -24760,29 +24949,9 @@ var AppDevServer = class _AppDevServer {
         this.substitutePort(this.options.command, port)
       );
       const command = lifted.command;
-      const env = {
-        ...process.env,
-        APP_PORT: String(port),
-        PORT: String(port),
-        TEMPO_APP_PORT: String(port),
-        // Activate the Tempo annotation plugin (tempoVitePlugin /
-        // tempoNextjsPlugin / Expo babel plugin), which no-ops unless
-        // TEMPO=true. Without it the app server serves route storyboards with
-        // no data-tempo-* source annotations, so their elements can't be
-        // mapped back to source and aren't selectable on the canvas ("route
-        // storyboard elements not clickable"). The Next.js/Expo command shapes
-        // already prefix TEMPO=true, but the Vite shape does not, so the
-        // supervisor owns this for every framework. Same signal the canvas
-        // sidecar sets via buildManagedCommandEnv (TempoHostProcess).
-        TEMPO: "true"
-      };
-      for (const key of Object.keys(env)) {
-        const k2 = key.toLowerCase();
-        if (k2.startsWith("npm_") || k2.startsWith("pnpm_") || key === "INIT_CWD" || key === "NODE_PATH") {
-          delete env[key];
-        }
-      }
+      const env = buildAppCommandEnv(port);
       Object.assign(env, lifted.env);
+      this.commandEnv = env;
       devLog("app-devserver:spawn", {
         command,
         configuredUrl: this.options.url ?? null,
@@ -24817,6 +24986,7 @@ var AppDevServer = class _AppDevServer {
         windowsHide: true,
         env: commandEnv
       });
+      startSpawned = true;
       this.wireProcessEvents(outputEpoch);
       const onAbort = () => {
         void this.killChild();
@@ -24837,19 +25007,39 @@ var AppDevServer = class _AppDevServer {
             };
             return await this.runStartCycle(attempt + 1, signal);
           }
+          const startError = this.status.error;
+          const cleanupError2 = await this.cleanupFailedLaunch(
+            port,
+            startSpawned
+          );
+          const finalError2 = cleanupError2 ? `${startError ?? "App dev server failed to start."}
+
+Cleanup also failed: ${cleanupError2}` : startError;
+          this.setStatus({ phase: "error", error: finalError2, url: null });
           return {
             ok: false,
             url: null,
-            error: this.status.error
+            error: finalError2
           };
         }
         const error = "App dev server did not become reachable in time.";
-        await this.killChild();
-        this.setStatus({ phase: "error", error, url: null });
-        return { ok: false, url: null, error };
+        const cleanupError = await this.cleanupFailedLaunch(port, startSpawned);
+        const finalError = cleanupError ? `${error}
+
+Cleanup also failed: ${cleanupError}` : error;
+        this.setStatus({ phase: "error", error: finalError, url: null });
+        return { ok: false, url: null, error: finalError };
       }
       throwIfAppLaunchAborted(signal);
       this.setStatus({ phase: "running", url, error: null });
+      if (this.launcherFinished && this.options.stop) {
+        await this.persistExternalRuntime({
+          stopCommand: this.options.stop,
+          cwd: this.options.cwd,
+          url
+        });
+      }
+      if (this.launcherFinished) this.startUrlHealthProbe(url);
       const serverPid = await findPortListenerPid(port);
       throwIfAppLaunchAborted(signal);
       const persisted = await this.readPersistedState();
@@ -24867,17 +25057,97 @@ var AppDevServer = class _AppDevServer {
       return { ok: true, url, error: null };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      await this.killChild();
-      this.setStatus({ phase: "error", error: message });
-      return { ok: false, url: null, error: message };
+      const cleanupError = await this.cleanupFailedLaunch(
+        this.status.port,
+        startSpawned
+      );
+      const finalError = cleanupError ? `${message}
+
+Cleanup also failed: ${cleanupError}` : message;
+      this.setStatus({ phase: "error", error: finalError });
+      return { ok: false, url: null, error: finalError };
     } finally {
       removeAbortListener();
     }
   }
+  /**
+   * Undo any launch attempt that failed after `start` was spawned. External
+   * launchers can leave partial resources even on a nonzero exit, and after a
+   * clean handoff killing the child cannot tear down anything at all; `stop`
+   * is the only remaining authority. If cleanup itself fails, retain that
+   * authority durably so the next stop/start/session can retry it.
+   */
+  async cleanupFailedLaunch(port, startWasSpawned) {
+    this.stopUrlHealthProbe();
+    if (!startWasSpawned) {
+      this.commandEnv = null;
+      return null;
+    }
+    let cleanupError = null;
+    if (this.options.stop && port != null) {
+      const stopResult = await this.runBoundedCommand(
+        this.options.stop,
+        port,
+        1e4
+      );
+      devLog("app-devserver:failed-launch-stop-command", {
+        command: this.options.stop,
+        exitCode: stopResult.exitCode,
+        aborted: stopResult.aborted,
+        spawnError: stopResult.spawnError?.message ?? null,
+        stderr: stopResult.stderr.slice(-1e3),
+        workspaceRoot: this.options.workspaceRoot
+      });
+      cleanupError = describeShellCommandFailure(stopResult);
+    }
+    await this.killChild();
+    if (cleanupError && this.options.stop) {
+      await this.persistExternalRuntime({
+        stopCommand: this.options.stop,
+        cwd: this.options.cwd,
+        url: null
+      });
+    } else {
+      await this.persistExternalRuntime(null);
+    }
+    this.launcherFinished = false;
+    this.commandEnv = null;
+    return cleanupError;
+  }
   async runStopCycle() {
     this.intentionalStop = true;
+    this.stopUrlHealthProbe();
     this.clearOutputBroadcastTimer();
-    const port = this.status.port;
+    const persistedBeforeStop = await this.readPersistedState();
+    const persistedExternal = persistedBeforeStop?.externalRuntime ?? null;
+    if (persistedExternal && persistedBeforeStop && await this.classifyPersistedProcessOwnership(persistedBeforeStop) !== "reapable") {
+      const message = "External app server teardown belongs to another live Tempo manager; refusing to run its stop command.";
+      this.setStatus({ phase: "error", url: null, error: message });
+      throw new Error(message);
+    }
+    const port = this.status.port ?? persistedBeforeStop?.port ?? null;
+    const url = this.status.url ?? persistedExternal?.url ?? null;
+    const stopCommand = persistedExternal?.stopCommand ?? this.options.stop;
+    const stopCwd = persistedExternal?.cwd ?? this.options.cwd;
+    let stopCommandError = null;
+    if (stopCommand && port != null) {
+      const stopResult = await this.runBoundedCommand(
+        stopCommand,
+        port,
+        1e4,
+        void 0,
+        stopCwd
+      );
+      devLog("app-devserver:stop-command", {
+        command: stopCommand,
+        exitCode: stopResult.exitCode,
+        aborted: stopResult.aborted,
+        spawnError: stopResult.spawnError?.message ?? null,
+        stderr: stopResult.stderr.slice(-1e3),
+        workspaceRoot: this.options.workspaceRoot
+      });
+      stopCommandError = describeShellCommandFailure(stopResult);
+    }
     await this.killChild();
     this.outputEpoch += 1;
     await this.outputLog.flush();
@@ -24916,8 +25186,21 @@ var AppDevServer = class _AppDevServer {
       this.setStatus({ phase: "error", url: null, error: message });
       throw new Error(message);
     }
+    if (url && !await waitForAppUrlUnreachable(url, 5e3)) {
+      const message = `App dev server is still reachable at ${url} after stop`;
+      this.setStatus({ phase: "error", url: null, error: message });
+      throw new Error(message);
+    }
+    if (persistedExternal && !url && stopCommandError) {
+      const message = `External app server teardown could not be verified: ${stopCommandError}`;
+      this.setStatus({ phase: "error", url: null, error: message });
+      throw new Error(message);
+    }
     await this.persistChildPid(null);
     await this.persistServerPid(null);
+    await this.persistExternalRuntime(null);
+    this.launcherFinished = false;
+    this.commandEnv = null;
     this.setStatus({
       phase: "stopped",
       url: null,
@@ -25013,6 +25296,25 @@ var AppDevServer = class _AppDevServer {
       if (outputEpoch !== this.outputEpoch || this.child !== child) return;
       this.child = null;
       void this.persistChildPid(null);
+      const cleanLauncherExit = !this.intentionalStop && code === 0 && signal == null;
+      const acceptedLauncherHandoff = cleanLauncherExit && this.options.stop != null && (this.status.phase === "starting" || this.status.phase === "running");
+      if (acceptedLauncherHandoff && this.options.stop) {
+        this.launcherFinished = true;
+        void this.persistExternalRuntime({
+          stopCommand: this.options.stop,
+          cwd: this.options.cwd,
+          url: this.status.phase === "running" ? this.status.url : null
+        });
+        if (this.status.phase === "running" && this.status.url) {
+          this.startUrlHealthProbe(this.status.url);
+        }
+        devLog("app-devserver:launcher-finished", {
+          pid: child.pid ?? null,
+          afterReady: this.status.phase === "running",
+          workspaceRoot: this.options.workspaceRoot
+        });
+        return;
+      }
       if (!this.intentionalStop && this.status.phase !== "stopped") {
         const conflict = this.status.phase === "running" ? parseDevServerLockConflict(this.recentOutput.join("")) : null;
         if (conflict != null) {
@@ -25025,7 +25327,7 @@ var AppDevServer = class _AppDevServer {
         }
         const tail = this.recentOutput.join("").slice(-500);
         const hint = tail ? classifyDevServerOutput(tail) : null;
-        const error = `App dev server exited unexpectedly (code ${code ?? "null"}, signal ${signal ?? "null"}).${tail ? `
+        const error = cleanLauncherExit && this.status.phase === "starting" ? 'The app start command exited successfully before the configured URL became ready. Add a matching non-empty "apps[0].stop" command so Tempo has teardown authority for the external server.' : `App dev server exited unexpectedly (code ${code ?? "null"}, signal ${signal ?? "null"}).${tail ? `
 
 ${tail}` : ""}${hint ? `
 
@@ -25047,12 +25349,12 @@ Hint: ${hint.hint}` : ""}`;
     });
   }
   async waitForReady(port, signal) {
-    const configuredUrl = this.options.url ? substituteAppPort(this.options.url, port) : null;
+    const configuredUrl = await this.resolveConfiguredUrl(port, signal);
     if (!configuredUrl) {
       const scrapeDeadline = Date.now() + this.options.urlScrapeTimeoutMs;
       while (!this.detectedBaseUrl && Date.now() < scrapeDeadline) {
         throwIfAppLaunchAborted(signal);
-        if (!this.child) return null;
+        if (!this.hasLivenessAuthority()) return null;
         await sleepForAppLaunch(120, signal);
       }
     }
@@ -25066,7 +25368,7 @@ Hint: ${hint.hint}` : ""}`;
     let lastProgressAt = start;
     while (true) {
       throwIfAppLaunchAborted(signal);
-      if (!this.child) return null;
+      if (!this.hasLivenessAuthority()) return null;
       const outcome = await probeHttpOnce(
         publicUrl,
         HTTP_PROBE_ATTEMPT_TIMEOUT_MS,
@@ -25083,6 +25385,112 @@ Hint: ${hint.hint}` : ""}`;
       await sleepForAppLaunch(httpProbeInterval(now - start), signal);
     }
   }
+  hasLivenessAuthority() {
+    return this.launcherFinished || this.child !== null;
+  }
+  async resolveConfiguredUrl(port, signal) {
+    const source = this.options.url;
+    if (!source) return null;
+    if (typeof source === "object" && this.options.stop) {
+      await this.waitForLauncherHandoff(signal);
+    }
+    try {
+      return await resolveHttpUrlSource({
+        source,
+        label: "apps[0].url",
+        cwd: this.options.cwd,
+        env: this.commandEnv ?? buildAppCommandEnv(port),
+        port,
+        timeoutMs: this.options.urlCommandTimeoutMs,
+        signal,
+        substitutePort: substituteAppPort
+      });
+    } catch (error) {
+      throwIfAppLaunchAborted(signal);
+      throw error;
+    }
+  }
+  async waitForLauncherHandoff(signal) {
+    const deadline = Date.now() + HTTP_PROBE_ABSOLUTE_CAP_MS;
+    while (!this.launcherFinished) {
+      throwIfAppLaunchAborted(signal);
+      if (!this.child) {
+        throw new Error(
+          this.status.error ?? "The app start command stopped before URL resolution could run."
+        );
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          "Timed out waiting for the app start command to hand off before running apps[0].url.command"
+        );
+      }
+      await sleepForAppLaunch(120, signal);
+    }
+  }
+  async runBoundedCommand(command, port, timeoutMs, signal, cwd = this.options.cwd) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await runAbortableShellCommand({
+        command: substituteAppPort(command, port),
+        cwd,
+        env: this.commandEnv ?? buildAppCommandEnv(port),
+        signal: controller.signal,
+        maxOutputBytes: 4e3
+      });
+    } finally {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  startUrlHealthProbe(url) {
+    this.stopUrlHealthProbe();
+    this.urlHealthProbeUrl = url;
+    this.urlHealthProbeTimer = setInterval(() => {
+      void this.runUrlHealthProbeTick();
+    }, this.options.urlHealthProbeIntervalMs);
+    this.urlHealthProbeTimer.unref?.();
+  }
+  stopUrlHealthProbe() {
+    if (this.urlHealthProbeTimer) clearInterval(this.urlHealthProbeTimer);
+    this.urlHealthProbeTimer = null;
+    this.urlHealthProbeUrl = null;
+    this.urlHealthProbeConsecutiveFailures = 0;
+    this.urlHealthProbeInFlight = false;
+  }
+  async runUrlHealthProbeTick() {
+    if (this.urlHealthProbeInFlight) return;
+    const url = this.urlHealthProbeUrl;
+    if (!url || this.intentionalStop) return;
+    this.urlHealthProbeInFlight = true;
+    try {
+      const outcome = await probeHttpOnce(url, 1500);
+      if (this.urlHealthProbeUrl !== url || this.intentionalStop) return;
+      if (outcome === "reachable" || outcome === "held") {
+        this.urlHealthProbeConsecutiveFailures = 0;
+        return;
+      }
+      if (!this.launcherFinished) return;
+      this.urlHealthProbeConsecutiveFailures += 1;
+      if (this.urlHealthProbeConsecutiveFailures < this.options.urlHealthFailuresToDemote) {
+        return;
+      }
+      const error = `App dev server URL became unreachable after launcher handoff: ${url}`;
+      this.launcherFinished = false;
+      this.stopUrlHealthProbe();
+      this.setStatus({ phase: "error", url: null, error });
+      for (const listener of [...this.exitListeners]) {
+        try {
+          listener({ code: null, signal: null, error });
+        } catch {
+        }
+      }
+    } finally {
+      this.urlHealthProbeInFlight = false;
+    }
+  }
   async killChild() {
     const child = this.child;
     if (!child) return;
@@ -25172,6 +25580,19 @@ Hint: ${hint.hint}` : ""}`;
   async allocatePort() {
     const persisted = await this.readPersistedState();
     if (persisted) {
+      if (persisted.externalRuntime) {
+        const ownership = await this.classifyPersistedProcessOwnership(persisted);
+        if (ownership !== "reapable") {
+          throw new Error(
+            "An external app server is still owned by another Tempo manager; refusing to start a duplicate."
+          );
+        }
+        if (!await this.cleanupPersistedExternalRuntime(persisted)) {
+          throw new Error(
+            "The previously launched external app server could not be stopped; refusing to start a duplicate."
+          );
+        }
+      }
       if (await isPortFree(persisted.port)) {
         return persisted.port;
       }
@@ -25227,6 +25648,7 @@ Hint: ${hint.hint}` : ""}`;
       pidStartedAt: null,
       serverPid: null,
       serverPidStartedAt: null,
+      externalRuntime: null,
       ...this.persistedOwnership()
     });
     return fresh;
@@ -25257,6 +25679,7 @@ Hint: ${hint.hint}` : ""}`;
         pidStartedAt,
         serverPid: persisted.serverPid,
         serverPidStartedAt: persisted.serverPidStartedAt,
+        externalRuntime: persisted.externalRuntime,
         ...this.persistedOwnership(persisted)
       });
     });
@@ -25286,6 +25709,19 @@ Hint: ${hint.hint}` : ""}`;
         pidStartedAt: persisted.pidStartedAt,
         serverPid,
         serverPidStartedAt,
+        externalRuntime: persisted.externalRuntime,
+        ...this.persistedOwnership(persisted)
+      });
+    });
+  }
+  async persistExternalRuntime(externalRuntime) {
+    await this.runExclusiveStateFileOp(async () => {
+      const persisted = await this.readPersistedState();
+      if (!persisted) return;
+      await this.writePersistedStateUnlocked({
+        ...persisted,
+        version: PERSISTED_STATE_VERSION,
+        externalRuntime,
         ...this.persistedOwnership(persisted)
       });
     });
@@ -25341,7 +25777,12 @@ Hint: ${hint.hint}` : ""}`;
           serverPidStartedAt: typeof parsed.serverPidStartedAt === "string" ? parsed.serverPidStartedAt : null,
           ownerId: typeof parsed.ownerId === "string" ? parsed.ownerId : null,
           managerPid: typeof parsed.managerPid === "number" && Number.isInteger(parsed.managerPid) ? parsed.managerPid : null,
-          managerStartedAt: typeof parsed.managerStartedAt === "string" ? parsed.managerStartedAt : null
+          managerStartedAt: typeof parsed.managerStartedAt === "string" ? parsed.managerStartedAt : null,
+          externalRuntime: parsed.externalRuntime && typeof parsed.externalRuntime === "object" && typeof parsed.externalRuntime.stopCommand === "string" && typeof parsed.externalRuntime.cwd === "string" && (typeof parsed.externalRuntime.url === "string" || parsed.externalRuntime.url === null) ? {
+            stopCommand: parsed.externalRuntime.stopCommand,
+            cwd: parsed.externalRuntime.cwd,
+            url: parsed.externalRuntime.url
+          } : null
         };
       }
     } catch {
@@ -25414,7 +25855,7 @@ Hint: ${hint.hint}` : ""}`;
   }
 };
 function extractServerUrl(text) {
-  const stripped = text.replace(ANSI_ESCAPE_RE2, "");
+  const stripped = text.replace(ANSI_ESCAPE_RE3, "");
   const matches = stripped.match(URL_RE);
   if (!matches) return null;
   for (const raw of matches) {
@@ -25532,6 +25973,39 @@ function waitForWatchdogChildPid(watchdog, timeoutMs = 2e3) {
 function substituteAppPort(command, port) {
   return command.replace(/\$\{(?:APP_PORT|PORT)\}/g, String(port));
 }
+function buildAppCommandEnv(port) {
+  const env = {
+    ...process.env,
+    APP_PORT: String(port),
+    PORT: String(port),
+    TEMPO_APP_PORT: String(port),
+    TEMPO: "true"
+  };
+  for (const key of Object.keys(env)) {
+    const normalized = key.toLowerCase();
+    if (normalized.startsWith("npm_") || normalized.startsWith("pnpm_") || key === "INIT_CWD" || key === "NODE_PATH") {
+      delete env[key];
+    }
+  }
+  return env;
+}
+async function waitForAppUrlUnreachable(url, timeoutMs) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (await probeHttpOnce(url, 750) === "refused") return true;
+    await new Promise((resolve2) => setTimeout(resolve2, 100));
+  }
+  return await probeHttpOnce(url, 750) === "refused";
+}
+function describeShellCommandFailure(result) {
+  if (result.aborted) return "the app stop command timed out";
+  if (result.spawnError) {
+    return `the app stop command could not start: ${result.spawnError.message}`;
+  }
+  if (result.exitCode === 0) return null;
+  const detail = result.stderr.trim();
+  return `the app stop command exited with code ${result.exitCode ?? "unknown"}${detail ? `: ${detail}` : ""}`;
+}
 async function findFreePort(range) {
   const maxAttempts = 50;
   for (let i = 0; i < maxAttempts; i++) {
@@ -26343,7 +26817,7 @@ async function parcelEventToFileEvent(event, rootInfo) {
 // ../tempo-sdk/package.json
 var package_default = {
   name: "tempo-sdk",
-  version: "0.0.33",
+  version: "0.0.34",
   type: "module",
   description: "Tempo SDK \u2014 Vite, Next.js, and Expo plugins for JSX annotation and shared page/storyboard types",
   repository: {
@@ -28062,6 +28536,9 @@ var TempoHostProcess = class _TempoHostProcess {
     this.lastHint = null;
     this.hintListeners = [];
     this.explicitTempoHostUrl = options.explicitTempoHostUrl;
+    this.tempoHostUrlSource = options.tempoHostUrlSource;
+    this.injectedPort = options.injectedPort;
+    this.launchSignal = options.launchSignal;
     this.tempoHostUrlIsHardcoded = options.tempoHostUrlIsHardcoded ?? false;
     this.expectedProjectRoot = options.expectedProjectRoot;
     this.expectedIdentity = options.expectedIdentity ?? null;
@@ -28069,6 +28546,7 @@ var TempoHostProcess = class _TempoHostProcess {
     this.missingRootDepsProjectRoot = options.missingRootDepsProjectRoot ?? null;
     this.commandCwd = options.cwd;
     this.stopCommand = options.stopCommand ?? null;
+    this.onLauncherHandoff = options.onLauncherHandoff ?? null;
     this.hasParentDeathWatchdog = options.watchdogScriptPath != null;
     const lifted = extractLeadingEnvAssignments(options.command);
     devLog("process:spawn", {
@@ -28169,10 +28647,11 @@ ${output}` : "";
         this.rejectReady = null;
       }
     });
-    this.child.on("exit", (code, signal) => {
+    this.child.on("exit", async (code, signal) => {
       this.stopped = true;
       const cleanLauncherExit = !this.intentionalStop && !this.readinessConfirmed && code === 0 && signal == null;
       if (cleanLauncherExit && this.stopCommand) {
+        await this.onLauncherHandoff?.();
         this.launcherFinished = true;
         this.lastExitCrashed = false;
         devLog("process:launcher_finished", {
@@ -28340,7 +28819,21 @@ Hint: ${this.lastHint.hint}` : "";
       };
     }
     try {
-      if (!this.tempoHostUrlIsHardcoded) {
+      if (typeof this.tempoHostUrlSource === "object" && this.tempoHostUrlSource !== null) {
+        if (this.stopCommand) {
+          await this.waitForLauncherHandoff(timeoutMs);
+        }
+        this.explicitTempoHostUrl = await resolveHttpUrlSource({
+          source: this.tempoHostUrlSource,
+          label: "urls.tempoHost",
+          cwd: this.commandCwd,
+          env: this.commandEnv,
+          port: this.injectedPort,
+          timeoutMs: 3e4,
+          signal: this.launchSignal,
+          substitutePort: substituteAppPort
+        });
+      } else if (!this.tempoHostUrlIsHardcoded) {
         await withTimeout(
           this.readySignal,
           timeoutMs,
@@ -28348,6 +28841,7 @@ Hint: ${this.lastHint.hint}` : "";
         );
       }
     } catch (error) {
+      throwIfLaunchAborted(this.launchSignal);
       const contractError = error instanceof DaemonizedStartRequiresStopError;
       const crashed = this.lastExitCrashed;
       return {
@@ -28446,6 +28940,25 @@ Hint: ${this.lastHint.hint}` : "";
       pid: this.child.pid ?? null
     };
   }
+  async waitForLauncherHandoff(timeoutMs) {
+    const deadline = Date.now() + Math.max(timeoutMs, 3e4);
+    while (!this.launcherFinished) {
+      throwIfLaunchAborted(this.launchSignal);
+      if (this.stopped) {
+        await this.readySignal;
+        if (this.launcherFinished) return;
+        throw new Error(
+          "The canvas start command stopped before urls.tempoHost.command could run."
+        );
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          "Timed out waiting for the canvas start command to hand off before running urls.tempoHost.command"
+        );
+      }
+      await waitForLaunchDelay(120, this.launchSignal);
+    }
+  }
   async terminate() {
     this.intentionalStop = true;
     if (this.terminationPromise) return await this.terminationPromise;
@@ -28545,6 +29058,7 @@ function parsePersistedDevserverOwner(value) {
     portWasTempoAllocated: record.portWasTempoAllocated === true,
     launchPid: typeof record.launchPid === "number" && Number.isInteger(record.launchPid) && record.launchPid > 1 ? record.launchPid : null,
     launchProcessStartedAt: typeof record.launchProcessStartedAt === "string" ? record.launchProcessStartedAt : null,
+    launchPort: typeof record.launchPort === "number" && Number.isInteger(record.launchPort) && record.launchPort > 0 && record.launchPort < 65536 ? record.launchPort : null,
     stopCommand: typeof record.stopCommand === "string" && record.stopCommand.length > 0 ? record.stopCommand : null
   };
 }
@@ -28583,8 +29097,11 @@ var TempoDevServer = class _TempoDevServer {
     this.devserverReadyAt = null;
     this.devserverLaunchPid = null;
     this.devserverLaunchProcessStartedAt = null;
+    this.devserverLaunchPort = null;
     this.devserverStopCommand = null;
     this.devserverPortWasTempoAllocated = false;
+    /** Stop authority persisted after handoff but before URL readiness. */
+    this.devserverExternalRuntimePending = false;
     // File watcher on managed files (Section 11.6). On any relevant change/delete
     // a debounced repair() call fires. `@modules/file-watcher` wraps
     // @parcel/watcher with recursive watching, batching, coalescing, and
@@ -28875,6 +29392,15 @@ var TempoDevServer = class _TempoDevServer {
         describePowerShellRejection(startDialectIssue)
       );
     }
+    const tempoHostUrlCommand = this.config.tempoHostUrl !== null && typeof this.config.tempoHostUrl === "object" ? this.config.tempoHostUrl.command : null;
+    const tempoHostUrlDialectIssue = tempoHostUrlCommand ? findPowerShellSyntax(tempoHostUrlCommand) : null;
+    if (tempoHostUrlCommand && tempoHostUrlDialectIssue) {
+      t.done({ ok: false, reason: "tempo_host_url_shell_dialect_mismatch" });
+      throw new StartShellDialectMismatchError(
+        tempoHostUrlCommand,
+        `urls.tempoHost.command contains PowerShell-only syntax (${tempoHostUrlDialectIssue}); use one plain cross-platform command`
+      );
+    }
     this.idleProcessStatus = "starting";
     let process2;
     let missingRootDepsProjectRoot = null;
@@ -28912,6 +29438,7 @@ var TempoDevServer = class _TempoDevServer {
         if (process2 !== activeProcess) {
           return;
         }
+        this.devserverExternalRuntimePending = false;
         this.state.devserverUrl = null;
         this.state.urlUnreachableSince = null;
         this.idleProcessStatus = "exited";
@@ -28937,11 +29464,19 @@ var TempoDevServer = class _TempoDevServer {
       throwIfLaunchAborted(options?.signal);
       const expectedIdentity = await this.readExpectedHostIdentity();
       const stopCommand = this.config.scripts.stop ? substituteAppPort(this.config.scripts.stop, startPlan.injectedPort) : null;
-      const activeProcess = new TempoHostProcess({
+      this.devserverStopCommand = stopCommand;
+      this.devserverLaunchPort = startPlan.injectedPort;
+      this.devserverPortWasTempoAllocated = startPlan.portWasTempoAllocated;
+      this.devserverExternalRuntimePending = false;
+      let activeProcess;
+      activeProcess = new TempoHostProcess({
         cwd: this.commandCwd,
         command: startPlan.command,
         explicitTempoHostUrl: startPlan.tempoHostUrl,
-        tempoHostUrlIsHardcoded: this.config.tempoHostUrl !== null && !this.config.tempoHostUrl.includes("${PORT}"),
+        tempoHostUrlSource: this.config.tempoHostUrl,
+        injectedPort: startPlan.injectedPort,
+        launchSignal: options?.signal,
+        tempoHostUrlIsHardcoded: typeof this.config.tempoHostUrl === "string" && !this.config.tempoHostUrl.includes("${PORT}"),
         expectedProjectRoot: this.projectRoot,
         expectedIdentity,
         identityFailureMessage: sdkUpgradeResult ? new CanvasHostIdentityError({
@@ -28953,6 +29488,11 @@ var TempoDevServer = class _TempoDevServer {
         }).message : null,
         missingRootDepsProjectRoot,
         stopCommand,
+        onLauncherHandoff: async () => {
+          if (this.activeHostProcess !== activeProcess) return;
+          this.devserverExternalRuntimePending = true;
+          await this.persistStatus();
+        },
         // The tempo-sdk Next plugin applies this documented Next config field.
         // It keeps Tempo's host cache isolated from the user's own `next dev`.
         extraEnv: {
@@ -28968,8 +29508,6 @@ var TempoDevServer = class _TempoDevServer {
       this.activeHostProcess = activeProcess;
       this.devserverLaunchPid = activeProcess.getPid();
       this.devserverLaunchProcessStartedAt = this.devserverLaunchPid ? await readProcessStartedAt(this.devserverLaunchPid) : null;
-      this.devserverStopCommand = stopCommand;
-      this.devserverPortWasTempoAllocated = startPlan.portWasTempoAllocated;
       attachProcessListeners(activeProcess);
       await this.writeProcessMarker(activeProcess.getPid()).catch(() => {
       });
@@ -29151,6 +29689,7 @@ var TempoDevServer = class _TempoDevServer {
           self.state.devserverUrl = result.url;
           self.state.urlUnreachableSince = null;
           self.devserverReadyAt = Date.now();
+          self.devserverExternalRuntimePending = false;
           const shellPid = process2.getPid();
           if (shellPid) {
             const workerPids = new Set(
@@ -30414,7 +30953,12 @@ var TempoDevServer = class _TempoDevServer {
   // branch `state.devserverUrl` in THIS instance is left untouched: a
   // persisted URL is never resurrected into live state.
   async reconcilePersistedDevserverUrl(staleUrl, staleOwner) {
-    if (!staleUrl) return "nothing_to_reconcile";
+    if (!staleUrl) {
+      if (!staleOwner) return "nothing_to_reconcile";
+      if (isPidAlive(staleOwner.managerPid)) return "live_sibling";
+      const markedOurs2 = supervisorAppInstanceId !== null && staleOwner.appInstanceId === supervisorAppInstanceId;
+      return markedOurs2 ? await this.purgeOwnedOrphanDevserver(null, staleOwner) : "foreign_process";
+    }
     if (staleUrl === this.state.devserverUrl) return "current_runtime";
     const markedOurs = staleOwner !== null && supervisorAppInstanceId !== null && staleOwner.appInstanceId === supervisorAppInstanceId;
     if (markedOurs) {
@@ -30455,8 +30999,9 @@ var TempoDevServer = class _TempoDevServer {
   // listener is signalled only when its pid and birth identity match the
   // launch record; a fresh port lookup alone is diagnostic, never proof.
   async purgeOwnedOrphanDevserver(staleUrl, owner) {
-    const port = portFromReadyUrl(staleUrl);
+    const port = owner.launchPort ?? (staleUrl ? portFromReadyUrl(staleUrl) : null);
     let stopCommandRan = false;
+    let stopCommandSucceeded = false;
     if (owner.stopCommand) {
       const stopResult = await runBoundedShellCommand({
         command: owner.stopCommand,
@@ -30468,6 +31013,7 @@ var TempoDevServer = class _TempoDevServer {
         timeoutMs: 1e4
       });
       stopCommandRan = true;
+      stopCommandSucceeded = stopResult.ok;
       devLog("supervisor:owned_orphan_stop_command", {
         url: staleUrl,
         command: owner.stopCommand,
@@ -30484,14 +31030,14 @@ var TempoDevServer = class _TempoDevServer {
     if (maySignalListener && listenerPid !== null) {
       await terminateProcessTreeByPid(listenerPid, 3e3, 2e3);
     }
-    const finalOutcome = await probeTempoHost(
+    const finalOutcome = staleUrl ? await probeTempoHost(
       staleUrl,
       1500,
       this.projectRoot,
       await this.readExpectedHostIdentity()
-    );
+    ) : null;
     const launchIdentityStillAlive = owner.launchPid !== null && owner.launchProcessStartedAt !== null && await readProcessStartedAt(owner.launchPid) === owner.launchProcessStartedAt;
-    const reconciled = finalOutcome !== "ok" && !launchIdentityStillAlive;
+    const reconciled = !launchIdentityStillAlive && (staleUrl ? finalOutcome !== "ok" : stopCommandSucceeded);
     devLog("supervisor:owned_orphan_purge_result", {
       url: staleUrl,
       markerPid: owner.managerPid,
@@ -30514,6 +31060,8 @@ var TempoDevServer = class _TempoDevServer {
     };
     if (this.state.devserverUrl) {
       nextStatus.devserverUrl = this.state.devserverUrl;
+    }
+    if (this.state.devserverUrl || this.devserverExternalRuntimePending) {
       nextStatus.devserverOwner = {
         appInstanceId: supervisorAppInstanceId,
         managerPid: process.pid,
@@ -30521,6 +31069,7 @@ var TempoDevServer = class _TempoDevServer {
         portWasTempoAllocated: this.devserverPortWasTempoAllocated,
         launchPid: this.devserverLaunchPid,
         launchProcessStartedAt: this.devserverLaunchProcessStartedAt,
+        launchPort: this.devserverLaunchPort,
         stopCommand: this.devserverStopCommand
       };
     }
@@ -30957,7 +31506,8 @@ async function getAvailableLocalPort() {
   });
 }
 function portFromConfiguredTempoHostUrl(tempoHostUrl) {
-  if (!tempoHostUrl || tempoHostUrl.includes("${PORT}")) return null;
+  if (!tempoHostUrl || typeof tempoHostUrl !== "string" || tempoHostUrl.includes("${PORT}"))
+    return null;
   try {
     const parsed = new URL(tempoHostUrl);
     if (parsed.port) return Number(parsed.port);
@@ -30968,10 +31518,10 @@ function portFromConfiguredTempoHostUrl(tempoHostUrl) {
 function buildManagedStartPlan(options) {
   const commandUsesPortToken = options.command.includes("${PORT}");
   const configuredPort = portFromConfiguredTempoHostUrl(options.tempoHostUrl);
-  const urlUsesPortToken = options.tempoHostUrl?.includes("${PORT}") ?? false;
+  const urlUsesPortToken = typeof options.tempoHostUrl === "string" && options.tempoHostUrl.includes("${PORT}");
   const recognizedCommand = canInjectDevServerPort(options.command);
   const command = commandUsesPortToken ? substituteAppPort(options.command, options.port) : recognizedCommand ? injectDevServerPort(options.command, options.port, options.framework) : options.command;
-  const tempoHostUrl = options.tempoHostUrl ? substituteAppPort(options.tempoHostUrl, options.port) : null;
+  const tempoHostUrl = typeof options.tempoHostUrl === "string" ? substituteAppPort(options.tempoHostUrl, options.port) : null;
   const shouldExportGenericPort = commandUsesPortToken || urlUsesPortToken || recognizedCommand || options.tempoHostUrl !== null;
   return {
     command,
@@ -32319,13 +32869,7 @@ function validateAppStart(value, label = "scripts.appStart") {
   const trimmed2 = value.trim();
   return trimmed2;
 }
-function validateAppUrl(value, label) {
-  if (value === void 0 || value === null) return void 0;
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(
-      `tempo.config.json field "${label}" must be a non-empty string when set`
-    );
-  }
+function validateHttpUrlString(value, label) {
   const trimmed2 = value.trim();
   let parsed;
   try {
@@ -32340,6 +32884,29 @@ function validateAppUrl(value, label) {
   }
   return trimmed2;
 }
+function validateHttpUrlSource(value, label) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string") {
+    if (value.trim().length === 0) {
+      throw new Error(
+        `tempo.config.json field "${label}" must be a non-empty string when set`
+      );
+    }
+    return validateHttpUrlString(value, label);
+  }
+  if (!isObjectRecord(value)) {
+    throw new Error(
+      `tempo.config.json field "${label}" must be an HTTP(S) URL string or an object with a non-empty "command"`
+    );
+  }
+  const keys = Object.keys(value);
+  if (keys.length !== 1 || keys[0] !== "command" || typeof value.command !== "string" || value.command.trim().length === 0) {
+    throw new Error(
+      `tempo.config.json field "${label}" command source must be exactly { "command": "<non-empty command>" }`
+    );
+  }
+  return { command: value.command.trim() };
+}
 function validateScriptsStop(value) {
   if (value === void 0 || value === null) return void 0;
   if (typeof value !== "string" || value.trim().length === 0) {
@@ -32356,20 +32923,11 @@ function validateUrls(value) {
   }
   const raw = value;
   if (raw.tempoHost !== void 0) {
-    if (typeof raw.tempoHost !== "string" || raw.tempoHost.trim().length === 0) {
-      throw new Error(
-        'tempo.config.json field "urls.tempoHost" must be a non-empty string'
-      );
-    }
-    const tempoHost = raw.tempoHost.trim();
-    try {
-      new URL(tempoHost.replace(/\$\{PORT\}/g, "5173"));
-    } catch {
-      throw new Error(
-        'tempo.config.json field "urls.tempoHost" must be a valid URL'
-      );
-    }
-    return { tempoHost };
+    const tempoHost = validateHttpUrlSource(
+      raw.tempoHost,
+      "urls.tempoHost"
+    );
+    return tempoHost === void 0 ? void 0 : { tempoHost };
   }
   return void 0;
 }
@@ -32444,8 +33002,9 @@ function validateApps(value) {
       }
       seenAppDirs.add(appDir);
     }
-    const url = validateAppUrl(raw.url, `apps[${i}].url`);
+    const url = validateHttpUrlSource(raw.url, `apps[${i}].url`);
     const start = validateAppStart(raw.start, `apps[${i}].start`);
+    const stop = validateAppStart(raw.stop, `apps[${i}].stop`);
     const legacyAppStart = validateAppStart(
       raw.appStart,
       `apps[${i}].appStart`
@@ -32461,18 +33020,24 @@ function validateApps(value) {
         `tempo.config.json field "apps[${i}].url" requires "apps[${i}].start"`
       );
     }
+    if (stop !== void 0 && effectiveStart === void 0) {
+      throw new Error(
+        `tempo.config.json field "apps[${i}].stop" requires "apps[${i}].start"`
+      );
+    }
     const uiFramework = validateUiFramework(
       raw.uiFramework,
       `apps[${i}].uiFramework`
     );
-    if (appDir === void 0 && effectiveStart === void 0 && url === void 0 && uiFramework === void 0) {
+    if (appDir === void 0 && effectiveStart === void 0 && stop === void 0 && url === void 0 && uiFramework === void 0) {
       throw new Error(
-        `tempo.config.json field "apps[${i}]" must set "appDir", "start", "url", and/or "uiFramework" \u2014 an empty entry encodes nothing`
+        `tempo.config.json field "apps[${i}]" must set "appDir", "start", "stop", "url", and/or "uiFramework" \u2014 an empty entry encodes nothing`
       );
     }
     return {
       ...appDir !== void 0 ? { appDir } : {},
       ...effectiveStart !== void 0 ? { start: effectiveStart } : {},
+      ...stop !== void 0 ? { stop } : {},
       ...url !== void 0 ? { url } : {},
       ...uiFramework !== void 0 ? { uiFramework } : {}
     };
@@ -32761,7 +33326,12 @@ async function writeTempoConfigFile(configDir, config) {
     ...normalized.scripts.stop ? { stop: normalized.scripts.stop } : {}
   };
   if (normalized.apps) {
-    rendered.apps = normalized.apps;
+    rendered.apps = normalized.apps.map(
+      ({ appStart: _legacyAppStart, ...app }) => {
+        void _legacyAppStart;
+        return app;
+      }
+    );
   }
   if (normalized.setupScript) {
     rendered.setupScript = normalized.setupScript;
@@ -32847,6 +33417,7 @@ async function resolveTempoConfig(projectRoot) {
     apps = config.apps.map((app) => ({
       appDir: app.appDir,
       start: app.start ?? null,
+      stop: app.stop ?? null,
       url: app.url ?? null,
       appStart: app.start ?? null,
       ...app.uiFramework ? { uiFramework: app.uiFramework } : {}
@@ -32857,6 +33428,7 @@ async function resolveTempoConfig(projectRoot) {
       {
         ...config.appDir !== void 0 ? { appDir: config.appDir } : {},
         start: legacyStart,
+        stop: null,
         url: null,
         appStart: legacyStart
       }
@@ -32880,7 +33452,8 @@ async function resolveTempoConfig(projectRoot) {
       install: config.scripts.install,
       start: config.scripts.start,
       stop: config.scripts.stop ?? null,
-      appStart: activeApp.appStart
+      appStart: activeApp.appStart,
+      appStop: activeApp.stop
     },
     apps
   };
@@ -41961,7 +42534,7 @@ async function analyzeProject(projectPath) {
 
 // ../tempo-project/tempo-project.ts
 function configsEqual(left, right) {
-  return left.projectRoot === right.projectRoot && left.tempoConfigPath === right.tempoConfigPath && left.rootRel === right.rootRel && left.tempoRoot === right.tempoRoot && left.pagesDir === right.pagesDir && left.packageJsonPath === right.packageJsonPath && left.viteConfigPath === right.viteConfigPath && left.tsconfigPath === right.tsconfigPath && left.tempoHostUrl === right.tempoHostUrl && left.uiFramework === right.uiFramework && left.scripts.install === right.scripts.install && left.scripts.start === right.scripts.start && left.scripts.stop === right.scripts.stop;
+  return left.projectRoot === right.projectRoot && left.tempoConfigPath === right.tempoConfigPath && left.rootRel === right.rootRel && left.tempoRoot === right.tempoRoot && left.pagesDir === right.pagesDir && left.packageJsonPath === right.packageJsonPath && left.viteConfigPath === right.viteConfigPath && left.tsconfigPath === right.tsconfigPath && JSON.stringify(left.tempoHostUrl) === JSON.stringify(right.tempoHostUrl) && left.uiFramework === right.uiFramework && left.scripts.install === right.scripts.install && left.scripts.start === right.scripts.start && left.scripts.stop === right.scripts.stop;
 }
 function usesTempoManagedSidecarPackage(config, framework) {
   if (!looksLikeGeneratedInstallScript(config.scripts.install)) return false;
@@ -44474,28 +45047,33 @@ function registerTools(server, context) {
   );
   server.tool(
     "set_app_dev_command",
-    "Configure the user's REAL app dev server in tempo.config.json, stored canonically as `apps[0].start` plus optional `apps[0].url`. Legacy `apps[0].appStart` and `scripts.appStart` still read and migrate to `start` on write. Required for route storyboards. `start` may be any foreground command. `url`, when set, is only the HTTP(S) readiness target and route base: it is probed as written, never controls local allocation, and may point through a container, tunnel, or remote machine. Tempo exposes its independently allocated helper port through `${APP_PORT}` and still accepts legacy `${PORT}` in app start/URL fields. Invoke commands directly, keep them cross-platform, and use appDir for subdirectory apps. At least one of command/url must be provided; null clears that field. Idempotent.",
+    "Configure the user's REAL app dev server in tempo.config.json as `apps[0].start` plus optional `stop` and `url`. `url` is either an HTTP(S) string or `{ command }`; a URL command runs only during launch and must exit 0 with exactly one HTTP(S) URL on stdout. A clean early `start` exit is accepted only with `stop`, after which URL probes own liveness and `stop` owns teardown. Tempo exposes `${APP_PORT}` (legacy `${PORT}` also works) to every command. Legacy appStart spellings still read and migrate. At least one field must be provided; null clears it. Idempotent.",
     {
       command: z23.string().nullish().describe(
         "The canonical apps[0].start foreground command. It may be arbitrary; use `${APP_PORT}` when the command should consume Tempo's allocated helper port. Legacy `${PORT}` remains supported. Omit to leave unchanged; pass null/empty to clear the app server configuration."
       ),
-      url: z23.string().nullish().describe(
-        "Optional canonical apps[0].url. This is the HTTP(S) readiness target and route base only. It may contain `${APP_PORT}` (or legacy `${PORT}`) or be any literal reachable HTTP(S) URL, including a container, tunnel, or remote host; it never controls local port allocation. Omit to leave unchanged; pass null/empty to clear only this field."
+      url: z23.union([z23.string(), z23.object({ command: z23.string().min(1) }).strict()]).nullish().describe(
+        'Optional canonical apps[0].url: either a reachable HTTP(S) URL string or `{ command: "..." }`. The command runs once per launch from appDir (after start exits in the stop-backed handoff shape), receives APP_PORT/PORT/TEMPO_APP_PORT, and must print exactly one HTTP(S) URL. Omit to leave unchanged; pass null/empty to clear.'
+      ),
+      stop: z23.string().nullish().describe(
+        "Optional canonical apps[0].stop teardown command. Required when start exits successfully while the app remains reachable externally. Runs on normal stop and stale-runtime reconciliation. Omit to leave unchanged; pass null/empty to clear."
       ),
       ...appDevServerTargetArgs
     },
-    async ({ command, url, repo_root, app_dir }) => {
+    async ({ command, stop, url, repo_root, app_dir }) => {
       if (!context.appDevServer)
         return unsupportedEnvironmentResult("appDevServer");
-      if (command === void 0 && url === void 0) {
-        return errorResult9("Provide command and/or url to update.");
+      if (command === void 0 && stop === void 0 && url === void 0) {
+        return errorResult9("Provide command, stop, and/or url to update.");
       }
       const startValue = command === void 0 ? void 0 : typeof command === "string" && command.trim().length > 0 ? command.trim() : null;
-      const urlValue = url === void 0 ? void 0 : typeof url === "string" && url.trim().length > 0 ? url.trim() : null;
+      const urlValue = url === void 0 ? void 0 : typeof url === "string" ? url.trim().length > 0 ? url.trim() : null : url === null ? null : { command: url.command.trim() };
+      const stopValue = stop === void 0 ? void 0 : typeof stop === "string" && stop.trim().length > 0 ? stop.trim() : null;
       try {
         await context.appDevServer.setConfig(
           {
             ...startValue !== void 0 ? { start: startValue } : {},
+            ...stopValue !== void 0 ? { stop: stopValue } : {},
             ...urlValue !== void 0 ? { url: urlValue } : {}
           },
           toAppDevServerTarget({ repo_root, app_dir })
@@ -44507,11 +45085,13 @@ function registerTools(server, context) {
               // tool output instead of only the tool arguments.
               ...startValue !== void 0 ? { app_dev_command: startValue } : {},
               ...urlValue !== void 0 ? { app_dev_url: urlValue } : {},
+              ...stopValue !== void 0 ? { app_dev_stop: stopValue } : {},
               app_dev_config_update: {
                 ...startValue !== void 0 ? { start: startValue } : {},
+                ...stopValue !== void 0 ? { stop: stopValue } : {},
                 ...urlValue !== void 0 ? { url: urlValue } : {}
               },
-              note: startValue === null ? "Cleared." : "Saved. The supervisor allocates the optional local `${APP_PORT}` helper independently (legacy `${PORT}` remains supported); a configured URL is probed exactly as the readiness target and route base. Before declaring setup complete, verify the app depends on tempo-sdk and its own bundler config carries Tempo instrumentation. For standalone Svelte/Vite, add @sveltejs/vite-plugin-svelte only if missing, preserve compatible configured versions, and use tempoVitePlugin() plus tempoSveltePreprocess(...) first in the app's preprocess chain; tempo/ only configures the sidecar."
+              note: startValue === null ? "Cleared." : "Saved. The supervisor allocates `${APP_PORT}` independently; static or command-resolved URLs are the readiness target and route base. If start hands off to an external server, stop is required and URL probes become liveness authority. Before declaring setup complete, verify the app depends on tempo-sdk and its own bundler config carries Tempo instrumentation. For standalone Svelte/Vite, add @sveltejs/vite-plugin-svelte only if missing, preserve compatible configured versions, and use tempoVitePlugin() plus tempoSveltePreprocess(...) first in the app's preprocess chain; tempo/ only configures the sidecar."
             },
             null,
             2
@@ -44526,7 +45106,7 @@ function registerTools(server, context) {
   );
   server.tool(
     "check_app_dev_server",
-    "Check the per-workspace app dev server configured by canonical `apps[0].start`/`url` (legacy appStart spellings also read). Returns `{configured, running, phase, port, url, error}`. Use this when a route storyboard isn't rendering. `configured: false` means start is unset; `phase: 'error'` carries the supervisor failure.",
+    "Check the per-workspace app dev server configured by canonical `apps[0].start`/`stop`/`url` (legacy appStart spellings also read). Returns `{configured, running, phase, port, url, livenessSource, error}`; liveness is `child` for foreground servers and `probe` after external handoff. Use this when a route storyboard isn't rendering. `configured: false` means start is unset; `phase: 'error'` carries the supervisor failure.",
     { ...appDevServerTargetArgs },
     async ({ repo_root, app_dir }) => {
       if (!context.appDevServer)
@@ -44545,7 +45125,7 @@ function registerTools(server, context) {
   );
   server.tool(
     "start_app_dev_server",
-    "Start the per-workspace app dev server if it isn't already running. Spawns canonical `apps[0].start`, substitutes `${APP_PORT}` (or legacy `${PORT}`) in start/url, persists the independently selected local helper port under `<workspaceRoot>/.tempo/app-devserver.json`, and HTTP-gates readiness against the configured URL or detected local URL. A literal URL is probed as written and does not affect local allocation. No-op if already running. When start is unset, returns `{configured: false}`; call `set_app_dev_command` first.",
+    "Start the per-workspace app dev server if it isn't already running. Spawns canonical `apps[0].start`, substitutes `${APP_PORT}` (or legacy `${PORT}`) in start/stop/url commands, persists the independently selected local helper port under `<workspaceRoot>/.tempo/app-devserver.json`, resolves `url.command` once when configured, and HTTP-gates readiness against the resolved/static URL or detected local URL. A clean early start exit requires `apps[0].stop`; then URL probes own liveness and stop owns teardown. A literal URL is probed as written and does not affect local allocation. No-op if already running. When start is unset, returns `{configured: false}`; call `set_app_dev_command` first.",
     { ...appDevServerTargetArgs },
     async ({ repo_root, app_dir }) => {
       if (!context.appDevServer)
@@ -44762,7 +45342,7 @@ function registerTools(server, context) {
     // unpushed/dirty branch before any capture), captures a whole-canvas
     // composite screenshot + each storyboard's HTML, saves them as the link's
     // preview snapshot, then mints the share URL.
-    "Create a shareable link to a canvas and get back a screenshot of the whole canvas. **The canvas MUST be fully committed and pushed to a remote (clean git state) before sharing** \u2014 exactly like link_items \u2014 otherwise this returns a 'branch_not_pushed' error and you must commit + push the canvas's branch first so the recipient can access the code. It captures a composite screenshot of every storyboard, saves it as the link's preview, then mints the link. Returns the URL plus the whole-canvas screenshot (auto-displayed inline). By default the link is member-only (the recipient opens it as an org member); pass public: true to mint an anyone-with-the-link token instead. Args: canvas_slug (folder name, or root-relative path when the name isn't unique), public (optional, default false).",
+    "Create a shareable link to a canvas and get back a screenshot of the whole canvas. **The canvas MUST be fully committed and pushed to a remote (clean git state) before sharing** \u2014 exactly like link_items \u2014 otherwise this returns a 'branch_not_pushed' error and you must commit + push the canvas's branch first so the recipient can access the code. Cache-first: when a published preview already exists for the branch's exact pushed commit, the link returns immediately with no re-capture; otherwise it captures a composite screenshot of every storyboard, publishes it as the branch's preview, then mints the link. Share links are BRANCH-LIVE: an existing link (and its public token) keeps its URL and automatically shows the newest published preview each time the branch's pushed canvas is re-captured \u2014 no need to re-share after pushing new commits. Returns the URL plus the whole-canvas screenshot (auto-displayed inline). By default the link is member-only (the recipient opens it as an org member); pass public: true to mint an anyone-with-the-link token instead. Args: canvas_slug (folder name, or root-relative path when the name isn't unique), public (optional, default false).",
     {
       canvas_slug: z23.string().describe(
         "Slug of the canvas \u2014 its folder name, or its path under the canvases root (`design-system/web-design-system/actions`). Pass the PATH whenever the folder name may not be unique; a bare name that matches several canvases is rejected with ambiguous_canvas_slug rather than resolved by guess"
@@ -45222,7 +45802,7 @@ function isExternallyExposed(toolName, opts) {
 }
 
 // src/version.ts
-var CLI_VERSION = "0.0.103";
+var CLI_VERSION = "0.0.104";
 
 // src/canvas-hooks.ts
 var import_pngjs3 = __toESM(require_png(), 1);
@@ -47196,4 +47776,4 @@ export {
   runServe,
   scopeParamsFor
 };
-//# sourceMappingURL=serve-P7M4UFJS.js.map
+//# sourceMappingURL=serve-FWQ5ZBR7.js.map