@polderlabs/bizar-plugin 0.5.4 → 0.6.1

package/index.ts

@@ -109,6 +109,7 @@ import {
 } from "./src/options.js";
 
 import { ServeLifecycle } from "./src/serve.js";
+import { writeServeInfo, clearServeInfo } from "./src/serve-info.js";
 import { HttpClient } from "./src/http-client.js";
 import { EventStream } from "./src/event-stream.js";
 import { BackgroundStateStore, type BackgroundState } from "./src/background-state.js";
@@ -124,9 +125,12 @@ import { SettingsStore } from "./src/settings.js";
 import { parseSlashCommand } from "./src/commands.js";
 import { createPlanActionTool } from "./src/tools/plan-action.js";
 import { createWaitForFeedbackTool } from "./src/tools/wait-for-feedback.js";
+import { wrapFetchForReasoningCleanup } from "./src/reasoning-clean.js";
 
 // v0.5.0 — visual plan wiring: side-effect executor + plan-fs
 import { executeSideEffect, type ExecuteOptions } from "./src/commands-impl.js";
+import { join as pathJoin } from "node:path";
+import { homedir } from "node:os";
 
 // --- Env-var constants (per spec §8) -------------------------------------
 
@@ -216,6 +220,7 @@ let instanceManagerHandle: InstanceManager | null = null;
 let serveHandle: ServeLifecycle | null = null;
 let streamHandle: EventStream | null = null;
 let loggerHandle: Logger | null = null;
+const signalHandlerRefs = new Map<"SIGTERM" | "SIGINT", () => void>();
 
 // --- Plugin entry point ---------------------------------------------------
 
@@ -359,6 +364,20 @@ async function init(
       });
       serveHandle = serve;
       const serveInfo = await serve.start();
+      // v3.5.7 — Persist serve-info so the dashboard can talk to us
+      try {
+        writeServeInfo(options.stateDir, {
+          baseUrl: serveInfo.baseUrl,
+          port: serveInfo.port,
+          password: serveInfo.password,
+          worktree: serveInfo.worktree,
+          pid: serveInfo.pid,
+          startedAt: serveInfo.startedAt,
+        }, logger);
+        logger.info(`[bizar] wrote serve-info to ${options.stateDir}/serve.json`);
+      } catch (err) {
+        logger.warn(`[bizar] failed to write serve-info: ${err instanceof Error ? err.message : String(err)}`);
+      }
       const http = new HttpClient({
         baseUrl: `http://127.0.0.1:${serveInfo.port}`,
         password: serveInfo.password,
@@ -437,7 +456,7 @@ async function init(
 
   // --- Signal traps (spec §5.3) ------------------------------------------
 
-  installSignalHandlers(logger, instanceManager, serve, stream);
+  installSignalHandlers(logger, instanceManager, serve, stream, options.stateDir);
 
   const ctx: RuntimeContext = {
     logger,
@@ -462,6 +481,7 @@ function installSignalHandlers(
   instanceManager: InstanceManager | null,
   serve: ServeLifecycle | null,
   stream: EventStream | null,
+  stateDir: string,
 ): void {
   const onSignal = async (sig: "SIGTERM" | "SIGINT") => {
     if (shuttingDown) return;
@@ -503,7 +523,10 @@ function installSignalHandlers(
       }
     }
 
-    // 4. Exit. (Note: the host may keep the process alive if other work
+    // 4. Clear serve-info so the dashboard doesn't try to talk to a dead serve.
+    clearServeInfo(stateDir, logger);
+
+    // 5. Exit. (Note: the host may keep the process alive if other work
     //    is pending, but for the plugin process this is the end.)
     try {
       process.exit(0);
@@ -516,14 +539,19 @@ function installSignalHandlers(
   // duplicate handlers. Use `process.once` so each handler runs at most
   // once per signal; the `shuttingDown` guard catches reentry.
   for (const sig of ["SIGTERM", "SIGINT"] as const) {
-    try {
-      process.removeAllListeners(sig);
-    } catch {
-      // ignore
+    const previous = signalHandlerRefs.get(sig);
+    if (previous) {
+      try {
+        process.removeListener(sig, previous);
+      } catch {
+        // ignore
+      }
     }
-    process.on(sig, () => {
+    const handler = () => {
       void onSignal(sig);
-    });
+    };
+    signalHandlerRefs.set(sig, handler);
+    process.once(sig, handler);
   }
 }
 
@@ -728,9 +756,40 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
       };
 
   return {
-    // §3.1 — config: no mutation. We already resolved options in init().
-    config: async () => {
-      // intentionally empty — options are resolved at init time
+    // §3.1 — config: wrap provider fetches to strip duplicated inline
+    // think blocks from responses of reasoning models that emit BOTH a
+    // structured reasoning field (rendered as a thought) AND an inline
+    // `` block (which would otherwise leak into the visible message).
+    // See plugins/bizar/src/reasoning-clean.ts for the full rationale.
+    config: async (cfg) => {
+      try {
+        const providers = (cfg as { provider?: Record<string, unknown> } | undefined)?.provider;
+        if (!providers || typeof providers !== "object") return;
+        const debug = (msg: string) => ctx.logger.debug(`bizar: ${msg}`);
+        for (const [name, provider] of Object.entries(providers)) {
+          if (!provider || typeof provider !== "object") continue;
+          const prov = provider as { options?: Record<string, unknown> };
+          if (!prov.options || typeof prov.options !== "object") continue;
+          const original = prov.options.fetch;
+          if (typeof original !== "function") continue;
+          // Only wrap once — detect by stamping a sentinel.
+          const wrapped = (original as { __bizarReasoningClean?: boolean })
+            .__bizarReasoningClean;
+          if (wrapped) continue;
+          prov.options.fetch = wrapFetchForReasoningCleanup(
+            original as Parameters<typeof wrapFetchForReasoningCleanup>[0],
+            { debug, providers: [name] },
+          );
+          (prov.options.fetch as { __bizarReasoningClean?: boolean }).__bizarReasoningClean = true;
+          debug(`wrapped provider.fetch for ${name}`);
+        }
+      } catch (err) {
+        ctx.logger.warn(
+          `bizar: config hook failed (passing through): ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      }
     },
 
     // §3.1, §4.5.1 — event: track session boundaries. We do NOT create
@@ -837,6 +896,29 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
                 finalResponse = `Command failed: ${msg}`;
               }
             }
+            // --- v0.5.1: dialog support.
+            // If the command emitted a dialog descriptor, persist it to disk
+            // so Tyr's dialog-poller can broadcast it to the dashboard.
+            // We return without throwing so no chat bubble is shown.
+            if (result.dialog) {
+              // S4 — defense-in-depth: validate ID shape before touching disk.
+              if (!/^dlg_[a-zA-Z0-9_-]{1,64}$/.test(result.dialog.id)) {
+                return; // silently drop malformed dialog IDs
+              }
+              try {
+                const { mkdir, writeFile } = await import("node:fs/promises");
+                const dialogDir = pathJoin(homedir(), ".cache", "bizar", "dialogs");
+                await mkdir(dialogDir, { recursive: true });
+                await writeFile(
+                  pathJoin(dialogDir, `${result.dialog.id}.json`),
+                  JSON.stringify({ ...result.dialog, createdAt: new Date().toISOString() }, null, 2),
+                );
+              } catch (dialogErr: unknown) {
+                const msg = dialogErr instanceof Error ? dialogErr.message : String(dialogErr);
+                ctx.logger.warn(`bizar: failed to write dialog file: ${msg}`);
+              }
+              return;
+            }
             // Surface the response to the user/host. We throw so the
             // message is treated as handled; the LLM does not process
             // it further. The host renders the throw message.
@@ -1070,6 +1152,7 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
           );
         }
       }
+      clearServeInfo(ctx.options.stateDir, ctx.logger);
     },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar-plugin",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "Bizar opencode plugin — loop detection, status reporting, handoff signal, background agents, and slash commands + visual plan flow for subagent activity",
   "type": "module",
   "main": "./index.ts",

package/src/background-state.ts

@@ -99,6 +99,15 @@ export type BackgroundStatus =
  *   - `interventionAt` — epoch ms of the most recent intervention.
  *   - `interventionReason` — short human-readable description of the
  *     intervention, e.g. `"thinking loop (5m 12s without tool/text)"`.
+ *
+ * v0.5.5 — persistent auto-restart. These are typed as optional so
+ * existing state files on disk remain valid after upgrade.
+ *   - `persistent` — when true, the manager auto-restarts on terminal
+ *     failure (up to maxRestarts). Default false.
+ *   - `restartCount` — number of times this instance has been
+ *     auto-restarted (not including the original spawn). Default 0.
+ *   - `maxRestarts` — cap; default 3.
+ *   - `lastRestartAt` — epoch ms of the most recent auto-restart.
  */
 export interface BackgroundState {
   instanceId: string;
@@ -127,6 +136,23 @@ export interface BackgroundState {
   interventionCount?: number;
   interventionAt?: number;
   interventionReason?: string;
+  // v0.5.5 — persistent auto-restart
+  persistent?: boolean;
+  restartCount?: number;
+  maxRestarts?: number;
+  lastRestartAt?: string;
+  /**
+   * Full original prompt text, stored so the instance can be restarted
+   * with the same input. Optional for backward compat; always set on
+   * new spawns from v0.5.5+.
+   */
+  prompt?: string;
+  /**
+   * Human-readable error from the last failed restart attempt.
+   * Set only when `_maybeAutoRestart` calls `restart()` and it returns
+   * `{ ok: false }`. Cleared on a successful restart.
+   */
+  restartError?: string;
 }
 
 /**
@@ -159,6 +185,10 @@ export const EMPTY_BACKGROUND_STATE: Omit<
   lastEventAt: 0,
   lastToolOrTextAt: 0,
   interventionCount: 0,
+  // v0.5.5 — persistent auto-restart defaults
+  persistent: false,
+  restartCount: 0,
+  maxRestarts: 3,
 };
 
 /**
@@ -314,6 +344,17 @@ function readState(
     if (typeof parsed.interventionCount !== "number") {
       parsed.interventionCount = 0;
     }
+    // v0.5.5 — backfill persistent/restart fields for files written by
+    // older versions. These are optional but the restarter needs them.
+    if (typeof parsed.persistent !== "boolean") {
+      parsed.persistent = false;
+    }
+    if (typeof parsed.restartCount !== "number") {
+      parsed.restartCount = 0;
+    }
+    if (typeof parsed.maxRestarts !== "number") {
+      parsed.maxRestarts = 3;
+    }
     return parsed;
   } catch (err: unknown) {
     logger.log({
@@ -389,11 +430,22 @@ export class BackgroundStateStore {
    */
   async save(state: BackgroundState): Promise<void> {
     if (!this.ensureDir()) return;
+    return withLock(this.locks, state.instanceId, () => this.saveUnlocked(state));
+  }
+
+  /**
+   * Persist a `BackgroundState` without acquiring the per-instance mutex.
+   *
+   * Callers must already hold the lock for `state.instanceId`. This exists
+   * for internal code paths such as `InstanceManager.update()` that need to
+   * mutate in-memory state while holding the same lock; calling `save()`
+   * there would re-enter the mutex and deadlock the promise chain.
+   */
+  saveUnlocked(state: BackgroundState): Promise<void> {
+    if (!this.ensureDir()) return Promise.resolve();
     const filePath = backgroundStateFilePath(this.stateDir, state.instanceId);
-    return withLock(this.locks, state.instanceId, () => {
-      writeStateAtomic(filePath, state, this.logger);
-      return Promise.resolve();
-    });
+    writeStateAtomic(filePath, state, this.logger);
+    return Promise.resolve();
   }
 
   /**

package/src/background.ts

@@ -139,6 +139,7 @@ const STALL_CHECK_INTERVAL_MS = 15_000;
  */
 export class InstanceManager {
   private instances = new Map<string, BackgroundState>();
+  private eventUnsubscribers = new Map<string, () => void>();
   private addLock: Promise<unknown> = Promise.resolve();
   private stateStore: BackgroundStateStore;
   private maxConcurrent: number;
@@ -193,6 +194,7 @@ export class InstanceManager {
       () => void this.runStallAndLoopChecks(),
       STALL_CHECK_INTERVAL_MS,
     );
+    this.stallCheckerTimer.unref?.();
   }
 
   // --- Getters ------------------------------------------------------------
@@ -276,6 +278,30 @@ export class InstanceManager {
     }
   }
 
+  // --- Internal dispatch (shared by add() and restart()) ------------------
+
+  /**
+   * Insert a fully-constructed BackgroundState into the in-memory map
+   * and persist to disk asynchronously. Does NOT check the concurrency
+   * cap — the caller handles that.
+   *
+   * This is extracted from `add()` so `restart()` can reuse the same
+   * insert-and-persist path without duplicating the logic.
+   */
+  private dispatchInternal(full: BackgroundState): BackgroundState {
+    this.instances.set(full.instanceId, full);
+    // Persist asynchronously; failure is logged but does not roll back
+    // the in-memory insert (the instance is "tracked" either way).
+    this.stateStore.save(full).catch((err: unknown) => {
+      this.logger.warn(
+        `bizar: failed to persist new instance ${full.instanceId}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    });
+    return full;
+  }
+
   // --- Atomic add (spec §2.2) ---------------------------------------------
 
   /**
@@ -313,16 +339,7 @@ export class InstanceManager {
         lastToolOrTextAt: now,
         interventionCount: 0,
       };
-      this.instances.set(draft.instanceId, full);
-      // Persist asynchronously; failure is logged but does not roll back
-      // the in-memory insert (the instance is "tracked" either way).
-      this.stateStore.save(full).catch((err: unknown) => {
-        this.logger.warn(
-          `bizar: failed to persist new instance ${draft.instanceId}: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-      });
+      this.dispatchInternal(full);
       // BUGFIX (v0.5.1): Do NOT call attachEventHandler() here. The
       // instance was just added with sessionId="" (filled in later by
       // POST /session). EventStream.onSessionEvent rejects empty strings,
@@ -376,8 +393,11 @@ export class InstanceManager {
       if (TERMINAL_STATUSES.has(patch.status ?? current.status) && !current.completedAt) {
         current.completedAt = Date.now();
       }
+      if (TERMINAL_STATUSES.has(current.status)) {
+        this.detachEventHandler(instanceId);
+      }
       try {
-        await this.stateStore.save(current);
+        await this.stateStore.saveUnlocked(current);
       } catch (err: unknown) {
         this.logger.warn(
           `bizar: failed to persist update for ${instanceId}: ${
@@ -421,6 +441,86 @@ export class InstanceManager {
     });
     this.logger.info(`bizar: killed background instance ${instanceId}`);
   }
+
+  // --- Restart (v0.5.5 — persistent auto-restart) ------------------------
+
+  /**
+   * Re-spawn a failed persistent instance with the same prompt, agent,
+   * and model config. The new instance gets a fresh `instanceId` and is
+   * linked to the original via `parentInstanceId`.
+   *
+   * Returns `{ ok: true, newInstanceId }` on success, or
+   * `{ ok: false, error: "..." }` on failure. Does NOT check the
+   * concurrency cap — the original instance is terminal, so its slot
+   * is already freed.
+   */
+  async restart(instanceId: string): Promise<{
+    ok: boolean;
+    newInstanceId?: string;
+    error?: string;
+  }> {
+    const existing = this.instances.get(instanceId);
+    if (!existing) return { ok: false, error: "instance_not_found" };
+    const totalRestarts = this.getTotalRestartCount(instanceId);
+    if (totalRestarts >= (existing.maxRestarts ?? 3)) {
+      return { ok: false, error: "max_restarts_reached" };
+    }
+
+    const now = Date.now();
+    const newInstanceId = generateInstanceId();
+    const full: BackgroundState = {
+      instanceId: newInstanceId,
+      sessionId: "",
+      agent: existing.agent,
+      model: existing.model,
+      promptPreview: (existing.prompt ?? existing.promptPreview ?? "").slice(0, PROMPT_PREVIEW_MAX),
+      prompt: existing.prompt,
+      parentAgent: existing.parentAgent,
+      parentInstanceId: instanceId,
+      logPath: `${this.worktree}/.opencode/log/${newInstanceId}.log`,
+      timeoutMs: existing.timeoutMs,
+      toolCallCount: 0,
+      // v0.5.5 — persist the auto-restart fields
+      persistent: existing.persistent,
+      maxRestarts: existing.maxRestarts,
+      restartCount: (existing.restartCount ?? 0) + 1,
+      status: "pending",
+      startedAt: now,
+      lastEventAt: now,
+      lastToolOrTextAt: now,
+      interventionCount: 0,
+    };
+
+    this.dispatchInternal(full);
+    this.logger.info(
+      `bizar: restarted instance ${instanceId} as ${newInstanceId} (restart #${full.restartCount})`,
+    );
+    return { ok: true, newInstanceId };
+  }
+
+  /**
+   * Walk the parent chain to compute the true restart count for this
+   * instance (Forseti C4). `restartCount` alone only reflects the child's
+   * own counter, so a chain of restarts can exceed `maxRestarts`. This
+   * helper sums the counters across the entire chain (parent + all
+   * descendants) and returns the total.
+   */
+  private getTotalRestartCount(instanceId: string): number {
+    let current = this.instances.get(instanceId);
+    if (!current) return 0;
+    let count = current.restartCount ?? 0;
+    let parentId = current.parentInstanceId;
+    const visited = new Set<string>([instanceId]);
+    while (parentId && !visited.has(parentId)) {
+      visited.add(parentId);
+      const parent = this.instances.get(parentId);
+      if (!parent) break;
+      count += parent.restartCount ?? 0;
+      parentId = parent.parentInstanceId;
+    }
+    return count;
+  }
+
   // --- Collect ------------------------------------------------------------
 
   /**
@@ -629,6 +729,8 @@ export class InstanceManager {
       error: `No activity for ${this.stallTimeoutMs}ms — LLM appears stalled`,
       completedAt: Date.now(),
     });
+    // v0.5.5 — persistent auto-restart on stall
+    await this._maybeAutoRestart(inst.instanceId);
   }
 
   /**
@@ -699,18 +801,33 @@ export class InstanceManager {
       error: `Thinking loop detected: ${formatDuration(sinceMs)} of thinking without tool calls or output. Spawn a Mimir agent for research.`,
       completedAt: Date.now(),
     });
+    // v0.5.5 — persistent auto-restart on thinking-loop exhaustion
+    await this._maybeAutoRestart(inst.instanceId);
   }
 
   // --- Internal: per-session event handler -------------------------------
 
   public attachEventHandler(inst: BackgroundState): () => void {
+    this.detachEventHandler(inst.instanceId);
     const handler: SessionEventHandler = (ev: StreamEvent) => {
       void this.handleInstanceEvent(inst.instanceId, ev);
     };
     const unsubscribe = this.stream.onSessionEvent(inst.sessionId, handler);
+    this.eventUnsubscribers.set(inst.instanceId, unsubscribe);
     return unsubscribe;
   }
 
+  private detachEventHandler(instanceId: string): void {
+    const unsubscribe = this.eventUnsubscribers.get(instanceId);
+    if (!unsubscribe) return;
+    try {
+      unsubscribe();
+    } catch {
+      // ignore
+    }
+    this.eventUnsubscribers.delete(instanceId);
+  }
+
   private async handleInstanceEvent(
     instanceId: string,
     ev: StreamEvent,
@@ -741,6 +858,37 @@ export class InstanceManager {
         error: errMsg,
         completedAt: Date.now(),
       });
+      // v0.5.5 — persistent auto-restart. If the instance is persistent
+      // and was not explicitly killed, try to restart.
+      if (inst.persistent && inst.status !== "killed") {
+        await this._maybeAutoRestart(instanceId);
+      }
+    }
+  }
+
+  /** v0.5.5 — Attempt an auto-restart for a persistent failed instance. */
+  private async _maybeAutoRestart(instanceId: string): Promise<void> {
+    const inst = this.instances.get(instanceId);
+    if (!inst || !inst.persistent) return;
+    if (inst.status === "killed") return; // user killed it — do not restart
+    this.logger.info(
+      `bizar: persistent instance ${instanceId} failed; auto-restarting`,
+    );
+    const result = await this.restart(instanceId);
+    if (result.ok) {
+      // Clear any previous restartError on the parent so the operator
+      // sees a clean state.
+      await this.update(instanceId, { restartError: undefined });
+      this.logger.info(
+        `bizar: auto-restart complete: ${instanceId} -> ${result.newInstanceId}`,
+      );
+    } else {
+      // Persist a human-readable error so the operator can see why the
+      // restart was rejected (e.g. max_restarts_reached).
+      await this.update(instanceId, { restartError: result.error || "unknown" });
+      this.logger.warn(
+        `bizar: auto-restart failed for ${instanceId}: ${result.error}`,
+      );
     }
   }
 
@@ -782,7 +930,11 @@ export class InstanceManager {
         patch.completedAt = Date.now();
       }
       await this.update(instanceId, patch);
-      if (patch.status === "failed") return;
+      // v0.5.5 — persistent auto-restart on tool-call cap
+      if (patch.status === "failed") {
+        await this._maybeAutoRestart(instanceId);
+        return;
+      }
     }
 
     // --- Loop-guard threshold-12 detection (spec §4.1) ---
@@ -798,6 +950,8 @@ export class InstanceManager {
             loopGuardTool: tool,
             completedAt: Date.now(),
           });
+          // v0.5.5 — persistent auto-restart on loop-guard
+          await this._maybeAutoRestart(instanceId);
           return;
         }
       }

package/src/commands-impl.ts

@@ -112,6 +112,9 @@ export interface ExecuteResult {
  *                    list so we can include status + lastEdited).
  * `open_plan_url` — just returns the parser's response (the parser
  *                    already built the URL). No I/O.
+ * `launch_dashboard` — spawns `bizar dash start` as a detached
+ *                    child process. Reads the port file back and
+ *                    appends the URL to the parser's response.
  * `tool_invocation` — delegates to `executeToolInvocation`.
  *
  * Never throws. All failures become `responseOverride` strings.
@@ -131,6 +134,8 @@ export async function executeSideEffect(
         // No I/O — the parser already built the URL. The chat hook
         // uses the parser's response unchanged.
         return {};
+      case "launch_dashboard":
+        return await executeLaunchDashboard(sideEffect.defaultPort, ctx);
       case "tool_invocation":
         return await executeToolInvocation(sideEffect, ctx, opts);
       default: {
@@ -188,6 +193,96 @@ async function executeListPlans(
   };
 }
 
+/**
+ * Launch the Bizar dashboard as a detached child process.
+ *
+  * We spawn `bizar dash start` with `detached: true` and `unref()`
+ * so the child's lifetime is independent of the plugin host. We then
+ * poll the port file (written by the child) for up to ~3s and append
+ * the URL to the parser's response. If anything goes wrong we surface
+ * a clear error so the user knows where to look.
+ *
+ * Never throws — all failures become responseSuffix/Override.
+ */
+async function executeLaunchDashboard(
+  defaultPort: number,
+  ctx: ExecutorContext,
+): Promise<ExecuteResult> {
+  const { spawn } = await import("node:child_process");
+  const { existsSync, readFileSync } = await import("node:fs");
+  const { join } = await import("node:path");
+  const { homedir } = await import("node:os");
+
+  const portFile = join(homedir(), ".config", "bizar", "dashboard.port");
+
+  // If a dashboard is already running, just report its URL.
+  if (existsSync(portFile)) {
+    try {
+      const port = readFileSync(portFile, "utf8").trim();
+      if (port && Number.isFinite(Number(port))) {
+        return {
+          responseSuffix:
+            `\n✓ Dashboard already running at http://localhost:${port}/`,
+        };
+      }
+    } catch {
+      /* fall through to spawn */
+    }
+  }
+
+  try {
+    // `bizar` is on $PATH for global installs; for npx / local installs
+    // we'd want to resolve to the package's bin. Spawn `bizar` directly
+    // for now — the user's $PATH is the source of truth.
+    const child = spawn("bizar", ["dash", "start"], {
+      detached: true,
+      stdio: "ignore",
+      cwd: ctx.worktree,
+    });
+    child.on("error", (err) => {
+      ctx.logger.warn(`bizar: dashboard spawn error: ${err.message}`);
+    });
+    child.unref();
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      responseOverride:
+        `Could not launch the Bizar dashboard: ${msg}\n` +
+        `Try running \`bizar dash start\` in your terminal.`,
+    };
+  }
+
+  // Poll the port file briefly so the response carries the live URL.
+  const deadline = Date.now() + 3000;
+  let resolvedPort: number | null = null;
+  while (Date.now() < deadline) {
+    if (existsSync(portFile)) {
+      try {
+        const port = Number(readFileSync(portFile, "utf8").trim());
+        if (Number.isFinite(port) && port > 0) {
+          resolvedPort = port;
+          break;
+        }
+      } catch {
+        /* ignore — keep polling */
+      }
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+
+  if (resolvedPort === null) {
+    return {
+      responseSuffix:
+        `\n✓ Dashboard launching… (preferred port ${defaultPort}, ` +
+        `fallback to a free port). The browser will open shortly.`,
+    };
+  }
+
+  return {
+    responseSuffix: `\n✓ Dashboard running at http://localhost:${resolvedPort}/`,
+  };
+}
+
 // --- executeToolInvocation -----------------------------------------------
 
 /**