@treeseed/core 0.8.9 → 0.8.10

package/dist/dev.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { dirname, resolve, sep } from "node:path";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { setTimeout as delay } from "node:timers/promises";
 import {
@@ -37,6 +37,9 @@ const DEFAULT_SETUP_STEP_TIMEOUT_MS = 3e5;
 const DEFAULT_PROCESS_READY_GRACE_MS = 1200;
 const DEFAULT_SHUTDOWN_GRACE_MS = 2500;
 const DEFAULT_KILL_GRACE_MS = 500;
+const INITIAL_RESTART_BACKOFF_MS = 1e3;
+const MAX_RESTART_BACKOFF_MS = 15e3;
+const SETUP_RETRY_BACKOFF_MS = 3e3;
 function resolvePackageRoot(packageName, tenantRoot) {
   const resolvedPath = require2.resolve(packageName, {
     paths: [tenantRoot, packageRoot, process.cwd()]
@@ -51,6 +54,22 @@ function resolvePackageRoot(packageName, tenantRoot) {
   }
   return currentDir;
 }
+function resolveOptionalPackageRoot(packageName, tenantRoot) {
+  try {
+    return resolvePackageRoot(packageName, tenantRoot);
+  } catch {
+    return null;
+  }
+}
+function resolvePackageRootEnvOverride(env, envName, tenantRoot) {
+  const value = env[envName]?.trim();
+  if (!value) return null;
+  const root = isAbsolute(value) ? value : resolve(tenantRoot, value);
+  if (!existsSync(resolve(root, "package.json"))) {
+    throw new Error(`${envName} must point to a package root containing package.json.`);
+  }
+  return root;
+}
 function resolveNodeEntrypoint(packageDir, sourceRelativePath, distRelativePath) {
   const sourcePath = resolve(packageDir, sourceRelativePath);
   const runTsPath = resolve(packageDir, "scripts", "run-ts.mjs");
@@ -150,6 +169,33 @@ function browserHost(host) {
 function webUrlFor(host, port) {
   return `http://${browserHost(host)}:${port}`;
 }
+function surfaceCommandIds(surface) {
+  switch (surface) {
+    case "web":
+      return ["web"];
+    case "api":
+      return ["api"];
+    case "manager":
+      return ["manager"];
+    case "worker":
+      return ["worker"];
+    case "agents":
+      return ["agents"];
+    case "services":
+      return ["api", "manager", "worker", "agents"];
+    case "integrated":
+    default:
+      return ["web", "api"];
+  }
+}
+function nodeLocalRuntime(label) {
+  return {
+    requested: "local",
+    provider: "local",
+    selected: "node-local",
+    reason: `${label} runs as a local Node.js process.`
+  };
+}
 function dockerComposeIsAvailable(env) {
   const docker = resolveTreeseedToolBinary("docker", { env });
   if (!docker) return false;
@@ -204,7 +250,7 @@ function createTreeseedIntegratedDevResetPlan(options) {
     ]
   };
 }
-function createWatchEntries(tenantRoot, sdkPackageRoot) {
+function createWatchEntries(tenantRoot, roots) {
   const entries = [
     { kind: "tenant", root: resolve(tenantRoot, "src") },
     { kind: "tenant", root: resolve(tenantRoot, "content") },
@@ -218,20 +264,34 @@ function createWatchEntries(tenantRoot, sdkPackageRoot) {
   ];
   if (!packageRoot.split(sep).includes("node_modules")) {
     entries.push(
-      { kind: "package", root: resolve(packageRoot, "src") },
-      { kind: "package", root: resolve(packageRoot, "scripts", "dev-platform.ts") },
-      { kind: "package", root: resolve(packageRoot, "scripts", "build-tenant-worker.ts") },
-      { kind: "package", root: resolve(packageRoot, "scripts", "run-ts.mjs") },
-      { kind: "package", root: resolve(packageRoot, "package.json") }
+      { kind: "core", root: resolve(packageRoot, "src") },
+      { kind: "core", root: resolve(packageRoot, "scripts", "build-tenant-worker.ts") },
+      { kind: "core", root: resolve(packageRoot, "scripts", "run-ts.mjs") },
+      { kind: "core", root: resolve(packageRoot, "package.json") },
+      { kind: "core", root: resolve(packageRoot, "src", "dev.ts"), restartRequired: true },
+      { kind: "core", root: resolve(packageRoot, "scripts", "dev-platform.ts"), restartRequired: true }
     );
   }
-  if (!sdkPackageRoot.split(sep).includes("node_modules")) {
+  if (!roots.sdkPackageRoot.split(sep).includes("node_modules")) {
     entries.push(
-      { kind: "sdk", root: resolve(sdkPackageRoot, "src") },
-      { kind: "sdk", root: resolve(sdkPackageRoot, "scripts", "tenant-astro-command.ts") },
-      { kind: "sdk", root: resolve(sdkPackageRoot, "scripts", "tenant-d1-migrate-local.ts") },
-      { kind: "sdk", root: resolve(sdkPackageRoot, "scripts", "run-ts.mjs") },
-      { kind: "sdk", root: resolve(sdkPackageRoot, "package.json") }
+      { kind: "sdk", root: resolve(roots.sdkPackageRoot, "src") },
+      { kind: "sdk", root: resolve(roots.sdkPackageRoot, "scripts", "tenant-astro-command.ts") },
+      { kind: "sdk", root: resolve(roots.sdkPackageRoot, "scripts", "tenant-d1-migrate-local.ts") },
+      { kind: "sdk", root: resolve(roots.sdkPackageRoot, "scripts", "run-ts.mjs") },
+      { kind: "sdk", root: resolve(roots.sdkPackageRoot, "package.json") }
+    );
+  }
+  if (roots.agentPackageRoot && !roots.agentPackageRoot.split(sep).includes("node_modules")) {
+    entries.push(
+      { kind: "agent", root: resolve(roots.agentPackageRoot, "src") },
+      { kind: "agent", root: resolve(roots.agentPackageRoot, "package.json") },
+      { kind: "agent", root: resolve(roots.agentPackageRoot, "scripts", "run-ts.mjs") }
+    );
+  }
+  if (roots.cliPackageRoot && !roots.cliPackageRoot.split(sep).includes("node_modules")) {
+    entries.push(
+      { kind: "cli", root: resolve(roots.cliPackageRoot, "src", "cli", "handlers", "dev.ts"), restartRequired: true },
+      { kind: "cli", root: resolve(roots.cliPackageRoot, "dist", "cli", "handlers", "dev.js"), restartRequired: true }
     );
   }
   return entries;
@@ -248,6 +308,9 @@ function createSetupSteps(tenantRoot, setupMode, sdkPackageRoot, planLike, env,
       }
     ];
   }
+  const hasWebCommand = planLike.commands.some((command) => command.id === "web");
+  const hasLocalRuntimeCommand = planLike.commands.some((command) => command.id !== "web");
+  const needsCloudflareLocalRuntime = usesCloudflareWebRuntime || hasLocalRuntimeCommand;
   const coreScripts = [
     ["starlight-patch", "Patch Starlight content path", "scripts/patch-starlight-content-path.ts", "dist/scripts/patch-starlight-content-path.js"],
     ["books", "Generate book/public artifacts", "scripts/aggregate-book.ts", "dist/scripts/aggregate-book.js"],
@@ -272,18 +335,20 @@ function createSetupSteps(tenantRoot, setupMode, sdkPackageRoot, planLike, env,
     {
       id: "wrangler",
       label: "Verify Wrangler executable",
-      required: usesCloudflareWebRuntime,
+      required: needsCloudflareLocalRuntime,
       status: "planned",
       detail: resolveTreeseedToolBinary("wrangler", { env }) ?? void 0
     },
-    ...usesCloudflareWebRuntime ? [
+    ...needsCloudflareLocalRuntime ? [
       {
         id: "wrangler-config",
         label: "Generate local Wrangler config",
         required: true,
         status: "planned",
         detail: generatedLocalWranglerPath(tenantRoot)
-      },
+      }
+    ] : [],
+    ...usesCloudflareWebRuntime && hasWebCommand ? [
       {
         id: "web-build",
         label: "Build local Cloudflare web runtime",
@@ -293,7 +358,7 @@ function createSetupSteps(tenantRoot, setupMode, sdkPackageRoot, planLike, env,
         status: tenantBuild ? "planned" : "failed",
         detail: tenantBuild ? void 0 : "Unable to resolve the tenant build script."
       }
-    ] : coreScripts.map(([id, label, source, dist]) => {
+    ] : hasWebCommand ? coreScripts.map(([id, label, source, dist]) => {
       const script = resolveOptionalScriptEntrypoint(packageRoot, source, dist);
       return {
         id,
@@ -304,7 +369,7 @@ function createSetupSteps(tenantRoot, setupMode, sdkPackageRoot, planLike, env,
         status: script ? "planned" : "skipped",
         detail: script ? void 0 : `Script not found at ${source}.`
       };
-    }),
+    }) : [],
     {
       id: "mailpit",
       label: mailpitEnabled ? "Start Mailpit email runtime" : "Disable Mailpit email runtime",
@@ -315,7 +380,7 @@ function createSetupSteps(tenantRoot, setupMode, sdkPackageRoot, planLike, env,
       detail: mailpitEnabled ? mailpit ? "Mailpit SMTP will listen on 127.0.0.1:1025 and the web UI on http://127.0.0.1:8025." : "Unable to resolve the Mailpit startup script." : "Docker Compose is unavailable, so Mailpit is disabled for this local dev run."
     }
   ];
-  if (usesCloudflareWebRuntime && existsSync(resolve(tenantRoot, "migrations"))) {
+  if (needsCloudflareLocalRuntime && existsSync(resolve(tenantRoot, "migrations"))) {
     const migrate = resolveOptionalScriptEntrypoint(
       sdkPackageRoot,
       "scripts/tenant-d1-migrate-local.ts",
@@ -333,6 +398,56 @@ function createSetupSteps(tenantRoot, setupMode, sdkPackageRoot, planLike, env,
   }
   return steps;
 }
+function createAgentCommand(id, tenantRoot, agentPackageRoot, sharedEnv, apiHost, apiPort) {
+  const configs = {
+    api: {
+      label: "Treeseed API",
+      source: "src/api/server.ts",
+      dist: "dist/api/server.js",
+      extraEnv: {
+        HOST: apiHost,
+        PORT: String(apiPort),
+        TREESEED_API_REPO_ROOT: tenantRoot
+      }
+    },
+    manager: {
+      label: "Workday Manager",
+      source: "src/services/workday-manager.ts",
+      dist: "dist/services/workday-manager.js",
+      extraEnv: {}
+    },
+    worker: {
+      label: "Worker Runner",
+      source: "src/services/worker.ts",
+      dist: "dist/services/worker.js",
+      extraEnv: {}
+    },
+    agents: {
+      label: "Agents Loop",
+      source: "src/services/agents.ts",
+      dist: "dist/services/agents.js",
+      extraEnv: {}
+    }
+  };
+  const config = configs[id];
+  const entrypoint = resolveNodeEntrypoint(agentPackageRoot, config.source, config.dist);
+  return {
+    id,
+    label: config.label,
+    command: entrypoint.command,
+    args: entrypoint.args,
+    cwd: tenantRoot,
+    env: {
+      ...sharedEnv,
+      TREESEED_AGENT_REPO_ROOT: tenantRoot,
+      TREESEED_AGENT_D1_DATABASE: sharedEnv.TREESEED_API_D1_DATABASE_NAME ?? "SITE_DATA_DB",
+      TREESEED_AGENT_D1_PERSIST_TO: sharedEnv.TREESEED_API_D1_LOCAL_PERSIST_TO,
+      TREESEED_ENVIRONMENT: sharedEnv.TREESEED_ENVIRONMENT ?? "local",
+      ...config.extraEnv
+    },
+    localRuntime: nodeLocalRuntime(config.label)
+  };
+}
 function createTreeseedIntegratedDevPlan(options = {}) {
   const tenantRoot = resolve(options.cwd ?? process.cwd());
   const surface = options.surface ?? "integrated";
@@ -349,8 +464,11 @@ function createTreeseedIntegratedDevPlan(options = {}) {
   const projectId = options.projectId ?? mergedEnv.TREESEED_PROJECT_ID;
   const teamId = options.teamId ?? mergedEnv.TREESEED_HOSTING_TEAM_ID;
   const apiBaseUrl = options.apiHost != null || options.apiPort != null ? `http://${apiHost}:${apiPort}` : mergedEnv.TREESEED_API_BASE_URL?.trim() || `http://${apiHost}:${apiPort}`;
-  const webUrl = surface === "integrated" || surface === "web" ? webUrlFor(webHost, webPort) : null;
+  const selectedCommandIds = surfaceCommandIds(surface);
+  const webUrl = selectedCommandIds.includes("web") ? webUrlFor(webHost, webPort) : null;
   const sdkPackageRoot = resolvePackageRoot("@treeseed/sdk", tenantRoot);
+  const agentPackageRoot = resolvePackageRootEnvOverride(mergedEnv, "TREESEED_AGENT_PACKAGE_ROOT", tenantRoot) ?? resolveOptionalPackageRoot("@treeseed/agent", tenantRoot);
+  const cliPackageRoot = resolveOptionalPackageRoot("@treeseed/cli", tenantRoot);
   const deployConfig = loadDevDeployConfig(tenantRoot);
   const webLocalRuntime = selectWebLocalRuntime(deployConfig?.surfaces?.web, fallbackWebProviderFromDeployConfig(deployConfig));
   const usesCloudflareWebRuntime = webLocalRuntime.selected === "cloudflare-wrangler-local";
@@ -373,7 +491,7 @@ function createTreeseedIntegratedDevPlan(options = {}) {
       String(webPort)
     ]
   };
-  const watchEntries = watch ? createWatchEntries(tenantRoot, sdkPackageRoot) : [];
+  const watchEntries = watch ? createWatchEntries(tenantRoot, { sdkPackageRoot, agentPackageRoot, cliPackageRoot }) : [];
   const mailpitEnabled = dockerComposeIsAvailable(mergedEnv);
   const resetRequested = options.reset === true;
   const sharedEnv = {
@@ -407,7 +525,7 @@ function createTreeseedIntegratedDevPlan(options = {}) {
     sharedEnv.TREESEED_PUBLIC_DEV_WATCH_RELOAD = sharedEnv.TREESEED_PUBLIC_DEV_WATCH_RELOAD || "true";
   }
   const commands = [];
-  if (surface === "integrated" || surface === "web") {
+  if (selectedCommandIds.includes("web")) {
     commands.push({
       id: "web",
       label: usesCloudflareWebRuntime ? "Cloudflare Wrangler UI" : "Astro UI",
@@ -418,14 +536,21 @@ function createTreeseedIntegratedDevPlan(options = {}) {
       localRuntime: webLocalRuntime
     });
   }
+  if (selectedCommandIds.some((id) => id !== "web") && !agentPackageRoot) {
+    throw new Error("Unable to resolve @treeseed/agent for local API or agent service surfaces.");
+  }
+  for (const id of selectedCommandIds) {
+    if (id === "web") continue;
+    commands.push(createAgentCommand(id, tenantRoot, agentPackageRoot, sharedEnv, apiHost, apiPort));
+  }
   const readyChecks = commands.map((command) => {
-    if (command.id === "web") {
+    if (command.id === "web" || command.id === "api") {
       return {
         id: command.id,
         label: command.label,
         required: true,
         strategy: "http",
-        url: webUrl ?? void 0
+        url: command.id === "web" ? webUrl ?? void 0 : `${apiBaseUrl.replace(/\/+$/u, "")}/healthz`
       };
     }
     return {
@@ -458,7 +583,18 @@ function createTreeseedIntegratedDevPlan(options = {}) {
     watchEntries,
     commands,
     localRuntimes: {
-      web: webLocalRuntime
+      ...commands.some((command) => command.id === "web") ? { web: webLocalRuntime } : {},
+      ...commands.some((command) => command.id === "api") ? { api: nodeLocalRuntime("Treeseed API") } : {},
+      ...commands.some((command) => command.id === "manager") ? { manager: nodeLocalRuntime("Workday Manager") } : {},
+      ...commands.some((command) => command.id === "worker") ? { worker: nodeLocalRuntime("Worker Runner") } : {},
+      ...commands.some((command) => command.id === "agents") ? { agents: nodeLocalRuntime("Agents Loop") } : {}
+    },
+    restartPolicy: {
+      initialBackoffMs: INITIAL_RESTART_BACKOFF_MS,
+      maxBackoffMs: MAX_RESTART_BACKOFF_MS,
+      setupRetryBackoffMs: SETUP_RETRY_BACKOFF_MS,
+      commandImplementationChangesRequireRestart: true,
+      agentChanges: "defer"
     },
     reset
   };
@@ -559,6 +695,23 @@ function defaultWrite(line, stream) {
   const target = stream === "stderr" ? process.stderr : process.stdout;
   target.write(line);
 }
+function shouldRedactEnvValue(key) {
+  return /(TOKEN|SECRET|PASSWORD|PASSPHRASE|PRIVATE|CREDENTIAL|AUTH)/iu.test(key);
+}
+function redactEnvironment(env) {
+  return Object.fromEntries(
+    Object.entries(env).map(([key, value]) => [key, value == null || !shouldRedactEnvValue(key) ? value : "[redacted]"])
+  );
+}
+function serializeDevPlanForOutput(plan) {
+  return {
+    ...plan,
+    commands: plan.commands.map((command) => ({
+      ...command,
+      env: redactEnvironment(command.env)
+    }))
+  };
+}
 function resolveLocalMachineEnv(tenantRoot) {
   try {
     return resolveTreeseedMachineEnvironmentValues(tenantRoot, "local");
@@ -738,7 +891,7 @@ function runTreeseedIntegratedDevReset(reset, options, deps) {
 }
 function writePlan(plan, options, write) {
   if (options.json) {
-    write(`${JSON.stringify({ schemaVersion: 1, kind: "treeseed.dev.plan", ok: true, payload: plan }, null, 2)}
+    write(`${JSON.stringify({ schemaVersion: 1, kind: "treeseed.dev.plan", ok: true, payload: serializeDevPlanForOutput(plan) }, null, 2)}
 `, "stdout");
     return;
   }
@@ -1016,17 +1169,15 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
     });
     return 1;
   }
-  const setupResults = runLocalSetup(plan, options, { spawnSync: spawnSyncProcess, write });
-  const failedSetup = setupResults.find((step) => step.status === "failed" && step.required);
-  if (failedSetup) {
-    emitEvent(options, write, { type: "error", message: failedSetupMessage(failedSetup), detail: failedSetup });
-    return 1;
-  }
   writeCurrentDevRuntimeState(tenantRoot);
   const children = /* @__PURE__ */ new Map();
   const commandsById = new Map(plan.commands.map((command) => [command.id, command]));
   const requiredSurfaceIds = new Set(plan.readyChecks.filter((check) => check.required).map((check) => check.id));
   const exited = /* @__PURE__ */ new Map();
+  const restartAttempts = /* @__PURE__ */ new Map();
+  const restartTimers = /* @__PURE__ */ new Map();
+  let setupRetryTimer = null;
+  let readinessInProgress = false;
   let watchController = null;
   let settled = false;
   let readinessComplete = false;
@@ -1044,6 +1195,16 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
       watchController.stop();
       watchController = null;
     }
+    function clearTimers() {
+      if (setupRetryTimer) {
+        clearTimeout(setupRetryTimer);
+        setupRetryTimer = null;
+      }
+      for (const timer of restartTimers.values()) {
+        clearTimeout(timer);
+      }
+      restartTimers.clear();
+    }
     function finalize(exitCode) {
       if (settled) {
         return;
@@ -1053,6 +1214,7 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
     }
     async function finalizeAsync(exitCode) {
       stopWatching();
+      clearTimers();
       await Promise.all(
         [...children.values()].map((managed) => stopManagedProcess(managed, "SIGTERM", killProcess, shutdownGraceMs))
       );
@@ -1069,6 +1231,47 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
       );
       resolveExitCode(exitCode);
     }
+    function restartDelayFor(id) {
+      const attempts = restartAttempts.get(id) ?? 0;
+      return Math.min(MAX_RESTART_BACKOFF_MS, INITIAL_RESTART_BACKOFF_MS * 2 ** attempts);
+    }
+    function markRestartAttempt(id) {
+      const attempts = restartAttempts.get(id) ?? 0;
+      restartAttempts.set(id, attempts + 1);
+    }
+    function runSetupOnce() {
+      const setupResults = runLocalSetup(plan, options, { spawnSync: spawnSyncProcess, write });
+      const failedSetup = setupResults.find((step) => step.status === "failed" && step.required);
+      if (failedSetup) {
+        emitEvent(options, write, { type: "error", message: failedSetupMessage(failedSetup), detail: failedSetup });
+        return false;
+      }
+      return true;
+    }
+    function scheduleSetupRetry(reason) {
+      if (setupRetryTimer || settled) {
+        return;
+      }
+      emitEvent(options, write, {
+        type: "restart",
+        status: "retrying",
+        message: `${reason} Retrying local setup in ${Math.round(SETUP_RETRY_BACKOFF_MS / 1e3)}s.`
+      }, "stderr");
+      setupRetryTimer = setTimeout(() => {
+        setupRetryTimer = null;
+        if (settled) return;
+        if (!runSetupOnce()) {
+          scheduleSetupRetry("Local setup is still failing.");
+          return;
+        }
+        for (const command of plan.commands) {
+          if (!children.has(command.id)) {
+            spawnCommand(command);
+          }
+        }
+        void waitForReadiness();
+      }, SETUP_RETRY_BACKOFF_MS);
+    }
     function spawnCommand(command) {
       emitEvent(options, write, {
         type: "spawn",
@@ -1103,9 +1306,10 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
             surface: command.id,
             exitCode,
             signal,
-            message: `${command.label} exited unexpectedly during ${readinessComplete ? "supervision" : "startup"} with ${signal ?? exitCode}.`
+            message: `${command.label} exited unexpectedly during ${readinessComplete ? "supervision" : "startup"} with ${signal ?? exitCode}; restarting.`
           });
-          finalize(exitCode === 0 ? 1 : exitCode);
+          children.delete(command.id);
+          scheduleCommandRestart(command.id);
           return;
         }
         const status = exitCode === 0 ? "idle" : "degraded";
@@ -1123,6 +1327,25 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
       });
       return child;
     }
+    function scheduleCommandRestart(id) {
+      const command = commandsById.get(id);
+      if (!command || settled || restartTimers.has(id)) {
+        return;
+      }
+      const delayMs = restartDelayFor(id);
+      markRestartAttempt(id);
+      emitEvent(options, write, {
+        type: "restart",
+        surface: id,
+        status: "scheduled",
+        message: `Restarting ${command.label} in ${Math.round(delayMs / 1e3)}s.`
+      }, "stderr");
+      const timer = setTimeout(() => {
+        restartTimers.delete(id);
+        void restartCommand(id);
+      }, delayMs);
+      restartTimers.set(id, timer);
+    }
     async function restartCommand(id) {
       const command = commandsById.get(id);
       if (!command || settled) {
@@ -1139,6 +1362,7 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
       }
       spawnCommand(command);
       emitEvent(options, write, { type: "restart", surface: id, message: `Restarted ${command.label}.` });
+      void waitForReadiness();
     }
     function startLiveWatch() {
       if (watchController || plan.watchEntries.length === 0 || plan.feedbackMode === "off" || settled) {
@@ -1162,28 +1386,50 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
               detail: {
                 tenantChanged: change.tenantChanged,
                 tenantApiChanged: change.tenantApiChanged,
-                packageChanged: change.packageChanged,
-                sdkChanged: change.sdkChanged
+                coreChanged: change.coreChanged,
+                sdkChanged: change.sdkChanged,
+                agentChanged: change.agentChanged,
+                cliChanged: change.cliChanged,
+                commandImplementationChanged: change.commandImplementationChanged
               }
             });
-            if (commandsById.get("web")?.localRuntime?.selected === "cloudflare-wrangler-local" && (change.tenantChanged || change.packageChanged || change.sdkChanged)) {
-              const web = children.get("web");
-              if (web) {
-                await stopManagedProcess(web, "SIGTERM", killProcess, Math.min(shutdownGraceMs, 500));
-                children.delete("web");
-                exited.delete("web");
-              }
-              const setupResults2 = runLocalSetup(plan, options, { spawnSync: spawnSyncProcess, write });
-              const failedSetup2 = setupResults2.find((step) => step.status === "failed" && step.required);
-              if (failedSetup2) {
-                emitEvent(options, write, { type: "error", message: failedSetupMessage(failedSetup2), detail: failedSetup2 });
-                finalize(1);
+            if (change.commandImplementationChanged) {
+              emitEvent(options, write, {
+                type: "replace",
+                status: "restart-required",
+                message: "The dev command implementation changed. Stop and rerun `npx trsd dev` to load the new supervisor.",
+                detail: change.changedPaths
+              }, "stderr");
+              return;
+            }
+            if (change.agentChanged) {
+              emitEvent(options, write, {
+                type: "restart",
+                status: "deferred",
+                message: "Agent service changes detected; running agent services will keep their current code until the next workday or a manual restart.",
+                detail: change.changedPaths
+              });
+            }
+            if (change.tenantChanged || change.tenantApiChanged || change.coreChanged || change.sdkChanged) {
+              if (!runSetupOnce()) {
+                scheduleSetupRetry("Local setup failed after a development change.");
                 return;
               }
-              await restartCommand("web");
             }
-            if (change.packageChanged || change.sdkChanged) {
-              await restartCommand("web");
+            const restartIds = /* @__PURE__ */ new Set();
+            if ((change.tenantChanged || change.coreChanged || change.sdkChanged) && commandsById.has("web")) {
+              restartIds.add("web");
+            }
+            if ((change.tenantApiChanged || change.sdkChanged) && commandsById.has("api")) {
+              restartIds.add("api");
+            }
+            if (change.sdkChanged) {
+              for (const id of commandsById.keys()) {
+                restartIds.add(id);
+              }
+            }
+            for (const id of restartIds) {
+              await restartCommand(id);
             }
             if (plan.feedbackMode === "live") {
               writeDevReloadStamp(plan.tenantRoot);
@@ -1198,10 +1444,16 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
       watchController.rebaseline();
     }
     async function waitForReadiness() {
+      if (readinessInProgress) {
+        return;
+      }
+      readinessInProgress = true;
       const readinessTimeoutMs = options.readinessTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS;
       const processReadyGraceMs = options.processReadyGraceMs ?? DEFAULT_PROCESS_READY_GRACE_MS;
+      let allRequiredReady = true;
       for (const check of plan.readyChecks) {
         if (settled) {
+          readinessInProgress = false;
           return;
         }
         let ready = false;
@@ -1213,17 +1465,26 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
           ready = !exited.has(commandId) && children.has(commandId);
         }
         if (settled) {
+          readinessInProgress = false;
           return;
         }
         if (!ready && check.required) {
+          allRequiredReady = false;
           emitEvent(options, write, {
             type: "error",
             surface: check.id,
             url: check.url,
-            message: `${check.label} did not become ready${check.url ? ` at ${check.url}` : ""}.`
+            message: `${check.label} did not become ready${check.url ? ` at ${check.url}` : ""}; keeping dev alive and retrying.`
           });
-          finalize(1);
-          return;
+          if (check.id !== "mailpit") {
+            scheduleCommandRestart(check.id);
+          } else {
+            scheduleSetupRetry("Mailpit readiness failed.");
+          }
+          continue;
+        }
+        if (ready && check.id !== "mailpit") {
+          restartAttempts.set(check.id, 0);
         }
         emitEvent(options, write, {
           type: "ready",
@@ -1233,6 +1494,11 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
           message: `${check.label} is ${ready ? "ready" : "degraded"}.`
         });
       }
+      readinessInProgress = false;
+      if (!allRequiredReady) {
+        startLiveWatch();
+        return;
+      }
       readinessComplete = true;
       if (plan.webUrl) {
         emitEvent(options, write, { type: "ready", url: plan.webUrl, message: `Treeseed dev ready at ${plan.webUrl}.` });
@@ -1240,12 +1506,12 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
       if (shouldOpenBrowser(plan)) {
         try {
           await openBrowser(plan.webUrl);
-          emitEvent(options, write, { type: "open", url: plan.webUrl, message: `Opened ${plan.webUrl}.` });
+          emitEvent(options, write, { type: "open", url: plan.webUrl ?? void 0, message: `Opened ${plan.webUrl}.` });
         } catch (error) {
           emitEvent(options, write, {
             type: "open",
             status: "degraded",
-            url: plan.webUrl,
+            url: plan.webUrl ?? void 0,
             message: `Could not open ${plan.webUrl}.`,
             detail: error instanceof Error ? error.message : String(error)
           });
@@ -1253,17 +1519,23 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
       }
       startLiveWatch();
     }
-    for (const command of plan.commands) {
-      spawnCommand(command);
-    }
-    void waitForReadiness().catch((error) => {
-      emitEvent(options, write, {
-        type: "error",
-        message: "Dev readiness failed.",
-        detail: error instanceof Error ? error.message : String(error)
+    startLiveWatch();
+    if (runSetupOnce()) {
+      for (const command of plan.commands) {
+        spawnCommand(command);
+      }
+      void waitForReadiness().catch((error) => {
+        readinessInProgress = false;
+        emitEvent(options, write, {
+          type: "error",
+          message: "Dev readiness failed; keeping supervisor alive.",
+          detail: error instanceof Error ? error.message : String(error)
+        });
+        scheduleSetupRetry("Readiness failed unexpectedly.");
       });
-      finalize(1);
-    });
+    } else {
+      scheduleSetupRetry("Initial local setup failed.");
+    }
   });
 }
 export {