nextclaw 0.9.3 → 0.9.4

package/dist/cli/index.js

@@ -9,7 +9,7 @@ import {
   loadConfig as loadConfig7,
   saveConfig as saveConfig6,
   getConfigPath as getConfigPath4,
-  getDataDir as getDataDir7,
+  getDataDir as getDataDir8,
   ConfigSchema as ConfigSchema2,
   getWorkspacePath as getWorkspacePath6,
   expandHome as expandHome2,
@@ -26,8 +26,8 @@ import {
   resolvePluginChannelMessageToolHints as resolvePluginChannelMessageToolHints2,
   setPluginRuntimeBridge as setPluginRuntimeBridge2
 } from "@nextclaw/openclaw-compat";
-import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
-import { join as join6, resolve as resolve9 } from "path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync6, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "fs";
+import { join as join7, resolve as resolve9 } from "path";
 import { createInterface as createInterface2 } from "readline";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { spawn as spawn3 } from "child_process";
@@ -2128,6 +2128,11 @@ var DiagnosticsCommands = class {
       issues.push(`Managed service health check failed: ${managedHealth.detail}`);
       recommendations.push(`Check logs at ${serviceState?.logPath ?? resolveServiceLogPath()}.`);
     }
+    if (running && serviceState?.startupState === "degraded" && managedHealth.state !== "ok") {
+      const startupHint = serviceState.startupLastProbeError ? ` (${serviceState.startupLastProbeError})` : "";
+      issues.push(`Service is in degraded startup state${startupHint}.`);
+      recommendations.push(`Wait and re-check ${APP_NAME} status; if it does not recover, inspect logs and restart.`);
+    }
     if (!running) {
       recommendations.push(`Run ${APP_NAME} start to launch the service.`);
     }
@@ -2244,8 +2249,8 @@ import {
   stopPluginChannelGateways
 } from "@nextclaw/openclaw-compat";
 import { startUiServer } from "@nextclaw/server";
-import { closeSync, cpSync, existsSync as existsSync7, mkdirSync as mkdirSync3, openSync, rmSync as rmSync3 } from "fs";
-import { dirname, isAbsolute as isAbsolute2, join as join4, relative, resolve as resolve7 } from "path";
+import { appendFileSync, closeSync, cpSync, existsSync as existsSync8, mkdirSync as mkdirSync4, openSync, rmSync as rmSync3 } from "fs";
+import { dirname, isAbsolute as isAbsolute2, join as join5, relative, resolve as resolve7 } from "path";
 import { spawn as spawn2 } from "child_process";
 import { request as httpRequest } from "http";
 import { request as httpsRequest } from "https";
@@ -2980,6 +2985,497 @@ var GatewayAgentRuntimePool = class {
   }
 };
 
+// src/cli/commands/ui-chat-run-coordinator.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, readdirSync, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
+import { join as join4 } from "path";
+import {
+  getDataDir as getDataDir5,
+  parseAgentScopedSessionKey as parseAgentScopedSessionKey2,
+  safeFilename
+} from "@nextclaw/core";
+var RUNS_DIR = join4(getDataDir5(), "runs");
+var NON_TERMINAL_STATES = /* @__PURE__ */ new Set(["queued", "running"]);
+function createRunId() {
+  const now = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `run-${now}-${rand}`;
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readOptionalString(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function isAbortError(error) {
+  if (error instanceof DOMException && error.name === "AbortError") {
+    return true;
+  }
+  if (error instanceof Error) {
+    if (error.name === "AbortError") {
+      return true;
+    }
+    const message = error.message.toLowerCase();
+    if (message.includes("aborted") || message.includes("abort")) {
+      return true;
+    }
+  }
+  return false;
+}
+function cloneEvent(event) {
+  return JSON.parse(JSON.stringify(event));
+}
+var UiChatRunCoordinator = class {
+  constructor(options) {
+    this.options = options;
+    mkdirSync3(RUNS_DIR, { recursive: true });
+    this.loadPersistedRuns();
+  }
+  runs = /* @__PURE__ */ new Map();
+  sessionRuns = /* @__PURE__ */ new Map();
+  startRun(input) {
+    const request = this.resolveRequest(input);
+    const stopCapability = this.options.runtimePool.supportsTurnAbort({
+      sessionKey: request.sessionKey,
+      agentId: request.agentId,
+      channel: request.channel,
+      chatId: request.chatId,
+      metadata: request.metadata
+    });
+    const run = {
+      runId: request.runId,
+      sessionKey: request.sessionKey,
+      ...request.agentId ? { agentId: request.agentId } : {},
+      ...request.model ? { model: request.model, requestedModel: request.model } : {},
+      state: "queued",
+      requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      stopSupported: stopCapability.supported,
+      ...stopCapability.reason ? { stopReason: stopCapability.reason } : {},
+      events: [],
+      waiters: /* @__PURE__ */ new Set(),
+      abortController: null,
+      cancelRequested: false
+    };
+    this.runs.set(run.runId, run);
+    this.bindRunToSession(run.sessionKey, run.runId);
+    this.syncSessionRunState(run);
+    this.persistRun(run);
+    this.emitRunUpdated(run);
+    void this.executeRun(run, request);
+    return this.toRunView(run);
+  }
+  getRun(params) {
+    const run = this.getRunRecord(params.runId);
+    return run ? this.toRunView(run) : null;
+  }
+  listRuns(params = {}) {
+    const sessionKey = readOptionalString(params.sessionKey);
+    const stateFilter = Array.isArray(params.states) && params.states.length > 0 ? new Set(params.states) : null;
+    const limit = Number.isFinite(params.limit) ? Math.max(0, Math.trunc(params.limit)) : 0;
+    const records = Array.from(this.runs.values()).filter((run) => {
+      if (sessionKey && run.sessionKey !== sessionKey) {
+        return false;
+      }
+      if (stateFilter && !stateFilter.has(run.state)) {
+        return false;
+      }
+      return true;
+    }).sort((left, right) => Date.parse(right.requestedAt) - Date.parse(left.requestedAt));
+    const total = records.length;
+    const runs = (limit > 0 ? records.slice(0, limit) : records).map((run) => this.toRunView(run));
+    return { runs, total };
+  }
+  async *streamRun(params) {
+    const run = this.getRunRecord(params.runId);
+    if (!run) {
+      throw new Error(`chat run not found: ${params.runId}`);
+    }
+    let cursor = Number.isFinite(params.fromEventIndex) ? Math.max(0, Math.trunc(params.fromEventIndex)) : 0;
+    while (true) {
+      while (cursor < run.events.length) {
+        yield cloneEvent(run.events[cursor]);
+        cursor += 1;
+      }
+      if (!NON_TERMINAL_STATES.has(run.state)) {
+        return;
+      }
+      if (params.signal?.aborted) {
+        return;
+      }
+      await this.waitForRunUpdate(run, params.signal);
+    }
+  }
+  async stopRun(params) {
+    const runId = readOptionalString(params.runId) ?? "";
+    if (!runId) {
+      return {
+        stopped: false,
+        runId: "",
+        reason: "runId is required"
+      };
+    }
+    const run = this.getRunRecord(runId);
+    if (!run) {
+      return {
+        stopped: false,
+        runId,
+        ...readOptionalString(params.sessionKey) ? { sessionKey: readOptionalString(params.sessionKey) } : {},
+        reason: "run not found or already completed"
+      };
+    }
+    const requestedSessionKey = readOptionalString(params.sessionKey);
+    if (requestedSessionKey && requestedSessionKey !== run.sessionKey) {
+      return {
+        stopped: false,
+        runId,
+        sessionKey: run.sessionKey,
+        reason: "session key mismatch"
+      };
+    }
+    if (!run.stopSupported) {
+      return {
+        stopped: false,
+        runId,
+        sessionKey: run.sessionKey,
+        reason: run.stopReason ?? "run stop is not supported"
+      };
+    }
+    if (!NON_TERMINAL_STATES.has(run.state)) {
+      return {
+        stopped: false,
+        runId,
+        sessionKey: run.sessionKey,
+        reason: `run already ${run.state}`
+      };
+    }
+    run.cancelRequested = true;
+    if (run.abortController) {
+      run.abortController.abort(new Error("chat turn stopped by user"));
+    }
+    return {
+      stopped: true,
+      runId,
+      sessionKey: run.sessionKey
+    };
+  }
+  resolveRequest(input) {
+    const message = readOptionalString(input.message) ?? "";
+    const sessionKey = readOptionalString(input.sessionKey) ?? `ui:${Date.now().toString(36)}:${Math.random().toString(36).slice(2, 8)}`;
+    const explicitAgentId = readOptionalString(input.agentId);
+    const parsedAgentId = parseAgentScopedSessionKey2(sessionKey)?.agentId;
+    const agentId = explicitAgentId ?? readOptionalString(parsedAgentId);
+    const model = readOptionalString(input.model);
+    const metadata = isRecord(input.metadata) ? { ...input.metadata } : {};
+    if (model) {
+      metadata.model = model;
+    }
+    const runId = readOptionalString(input.runId) ?? createRunId();
+    return {
+      runId,
+      message,
+      sessionKey,
+      ...agentId ? { agentId } : {},
+      ...model ? { model } : {},
+      metadata,
+      channel: readOptionalString(input.channel) ?? "ui",
+      chatId: readOptionalString(input.chatId) ?? "web-ui"
+    };
+  }
+  async executeRun(run, request) {
+    if (run.cancelRequested) {
+      this.transitionState(run, "aborted");
+      return;
+    }
+    this.transitionState(run, "running");
+    const abortController = run.stopSupported ? new AbortController() : null;
+    run.abortController = abortController;
+    const assistantDeltaParts = [];
+    try {
+      const reply = await this.options.runtimePool.processDirect({
+        content: request.message,
+        sessionKey: request.sessionKey,
+        channel: request.channel,
+        chatId: request.chatId,
+        agentId: request.agentId,
+        metadata: request.metadata,
+        ...abortController ? { abortSignal: abortController.signal } : {},
+        onAssistantDelta: (delta) => {
+          if (typeof delta !== "string" || delta.length === 0) {
+            return;
+          }
+          assistantDeltaParts.push(delta);
+          this.pushStreamEvent(run, { type: "delta", delta });
+        },
+        onSessionEvent: (event) => {
+          this.pushStreamEvent(run, {
+            type: "session_event",
+            event: this.mapSessionEvent(event)
+          });
+        }
+      });
+      this.pushStreamEvent(run, {
+        type: "final",
+        result: {
+          reply,
+          sessionKey: request.sessionKey,
+          ...request.agentId ? { agentId: request.agentId } : {},
+          ...request.model ? { model: request.model } : {}
+        }
+      });
+      run.reply = reply;
+      this.transitionState(run, "completed");
+    } catch (error) {
+      const aborted = (abortController?.signal.aborted ?? false) || isAbortError(error);
+      if (aborted) {
+        const partialReply = assistantDeltaParts.join("");
+        if (partialReply.trim().length > 0) {
+          this.persistAbortedAssistantReply(run.sessionKey, partialReply);
+        }
+        this.pushStreamEvent(run, {
+          type: "final",
+          result: {
+            reply: partialReply,
+            sessionKey: request.sessionKey,
+            ...request.agentId ? { agentId: request.agentId } : {},
+            ...request.model ? { model: request.model } : {}
+          }
+        });
+        run.reply = partialReply;
+        this.transitionState(run, "aborted", {
+          error: abortController?.signal.reason instanceof Error ? abortController.signal.reason.message : readOptionalString(abortController?.signal.reason)
+        });
+        return;
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.pushStreamEvent(run, {
+        type: "error",
+        error: errorMessage
+      });
+      this.transitionState(run, "failed", { error: errorMessage });
+    } finally {
+      run.abortController = null;
+      this.persistRun(run);
+      this.notifyRunWaiters(run);
+    }
+  }
+  transitionState(run, next, options = {}) {
+    run.state = next;
+    if (next === "running") {
+      run.startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    if (!NON_TERMINAL_STATES.has(next)) {
+      run.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    if (options.error) {
+      run.error = options.error;
+    } else if (next === "completed") {
+      run.error = void 0;
+    }
+    this.syncSessionRunState(run);
+    this.persistRun(run);
+    this.emitRunUpdated(run);
+    this.notifyRunWaiters(run);
+  }
+  pushStreamEvent(run, event) {
+    run.events.push(event);
+    this.persistRun(run);
+    this.notifyRunWaiters(run);
+    this.emitRunUpdated(run);
+  }
+  waitForRunUpdate(run, signal) {
+    return new Promise((resolve10) => {
+      const wake = () => {
+        cleanup();
+        resolve10();
+      };
+      const onAbort = () => {
+        cleanup();
+        resolve10();
+      };
+      const cleanup = () => {
+        run.waiters.delete(wake);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      run.waiters.add(wake);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  notifyRunWaiters(run) {
+    if (run.waiters.size === 0) {
+      return;
+    }
+    const waiters = Array.from(run.waiters);
+    run.waiters.clear();
+    for (const wake of waiters) {
+      wake();
+    }
+  }
+  bindRunToSession(sessionKey, runId) {
+    const existing = this.sessionRuns.get(sessionKey);
+    if (existing) {
+      existing.add(runId);
+      return;
+    }
+    this.sessionRuns.set(sessionKey, /* @__PURE__ */ new Set([runId]));
+  }
+  syncSessionRunState(run) {
+    const session = this.options.sessionManager.getOrCreate(run.sessionKey);
+    const metadata = session.metadata;
+    metadata.ui_last_run_id = run.runId;
+    metadata.ui_last_run_state = run.state;
+    metadata.ui_last_run_updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    if (NON_TERMINAL_STATES.has(run.state)) {
+      metadata.ui_active_run_id = run.runId;
+      metadata.ui_run_state = run.state;
+      metadata.ui_run_requested_at = run.requestedAt;
+      if (run.startedAt) {
+        metadata.ui_run_started_at = run.startedAt;
+      }
+    } else if (metadata.ui_active_run_id === run.runId) {
+      delete metadata.ui_active_run_id;
+      delete metadata.ui_run_state;
+      delete metadata.ui_run_requested_at;
+      delete metadata.ui_run_started_at;
+    }
+    session.updatedAt = /* @__PURE__ */ new Date();
+    this.options.sessionManager.save(session);
+  }
+  persistAbortedAssistantReply(sessionKey, partialReply) {
+    const session = this.options.sessionManager.getOrCreate(sessionKey);
+    const latest = session.messages.length > 0 ? session.messages[session.messages.length - 1] : null;
+    if (latest?.role === "assistant" && typeof latest.content === "string" && latest.content === partialReply) {
+      return;
+    }
+    this.options.sessionManager.addMessage(session, "assistant", partialReply);
+    this.options.sessionManager.save(session);
+  }
+  mapSessionEvent(event) {
+    const raw = event.data?.message;
+    const messageRecord = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : null;
+    const message = messageRecord && typeof messageRecord.role === "string" ? {
+      role: messageRecord.role,
+      content: messageRecord.content,
+      timestamp: typeof messageRecord.timestamp === "string" ? messageRecord.timestamp : event.timestamp,
+      ...typeof messageRecord.name === "string" ? { name: messageRecord.name } : {},
+      ...typeof messageRecord.tool_call_id === "string" ? { tool_call_id: messageRecord.tool_call_id } : {},
+      ...Array.isArray(messageRecord.tool_calls) ? { tool_calls: messageRecord.tool_calls } : {},
+      ...typeof messageRecord.reasoning_content === "string" ? { reasoning_content: messageRecord.reasoning_content } : {}
+    } : void 0;
+    return {
+      seq: event.seq,
+      type: event.type,
+      timestamp: event.timestamp,
+      ...message ? { message } : {}
+    };
+  }
+  emitRunUpdated(run) {
+    this.options.onRunUpdated?.(this.toRunView(run));
+  }
+  toRunView(run) {
+    return {
+      runId: run.runId,
+      sessionKey: run.sessionKey,
+      ...run.agentId ? { agentId: run.agentId } : {},
+      ...run.model ? { model: run.model } : {},
+      state: run.state,
+      requestedAt: run.requestedAt,
+      ...run.startedAt ? { startedAt: run.startedAt } : {},
+      ...run.completedAt ? { completedAt: run.completedAt } : {},
+      stopSupported: run.stopSupported,
+      ...run.stopReason ? { stopReason: run.stopReason } : {},
+      ...run.error ? { error: run.error } : {},
+      ...typeof run.reply === "string" ? { reply: run.reply } : {},
+      eventCount: run.events.length
+    };
+  }
+  getRunPath(runId) {
+    return join4(RUNS_DIR, `${safeFilename(runId)}.json`);
+  }
+  persistRun(run) {
+    const persisted = {
+      runId: run.runId,
+      sessionKey: run.sessionKey,
+      ...run.agentId ? { agentId: run.agentId } : {},
+      ...run.model ? { model: run.model } : {},
+      state: run.state,
+      requestedAt: run.requestedAt,
+      ...run.startedAt ? { startedAt: run.startedAt } : {},
+      ...run.completedAt ? { completedAt: run.completedAt } : {},
+      stopSupported: run.stopSupported,
+      ...run.stopReason ? { stopReason: run.stopReason } : {},
+      ...run.error ? { error: run.error } : {},
+      ...typeof run.reply === "string" ? { reply: run.reply } : {},
+      events: run.events
+    };
+    writeFileSync3(this.getRunPath(run.runId), `${JSON.stringify(persisted, null, 2)}
+`);
+  }
+  loadPersistedRuns() {
+    if (!existsSync7(RUNS_DIR)) {
+      return;
+    }
+    for (const entry of readdirSync(RUNS_DIR, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) {
+        continue;
+      }
+      const path = join4(RUNS_DIR, entry.name);
+      try {
+        const parsed = JSON.parse(readFileSync6(path, "utf-8"));
+        const runId = readOptionalString(parsed.runId);
+        const sessionKey = readOptionalString(parsed.sessionKey);
+        if (!runId || !sessionKey) {
+          continue;
+        }
+        const state = this.normalizeRunState(parsed.state);
+        const events = Array.isArray(parsed.events) ? parsed.events : [];
+        const run = {
+          runId,
+          sessionKey,
+          ...readOptionalString(parsed.agentId) ? { agentId: readOptionalString(parsed.agentId) } : {},
+          ...readOptionalString(parsed.model) ? { model: readOptionalString(parsed.model) } : {},
+          state,
+          requestedAt: readOptionalString(parsed.requestedAt) ?? (/* @__PURE__ */ new Date()).toISOString(),
+          ...readOptionalString(parsed.startedAt) ? { startedAt: readOptionalString(parsed.startedAt) } : {},
+          ...readOptionalString(parsed.completedAt) ? { completedAt: readOptionalString(parsed.completedAt) } : {},
+          stopSupported: Boolean(parsed.stopSupported),
+          ...readOptionalString(parsed.stopReason) ? { stopReason: readOptionalString(parsed.stopReason) } : {},
+          ...readOptionalString(parsed.error) ? { error: readOptionalString(parsed.error) } : {},
+          ...typeof parsed.reply === "string" ? { reply: parsed.reply } : {},
+          events,
+          waiters: /* @__PURE__ */ new Set(),
+          abortController: null,
+          cancelRequested: false
+        };
+        if (NON_TERMINAL_STATES.has(run.state)) {
+          run.state = "failed";
+          run.error = run.error ?? "run interrupted by service restart";
+          run.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+          this.persistRun(run);
+        }
+        this.runs.set(run.runId, run);
+        this.bindRunToSession(run.sessionKey, run.runId);
+      } catch {
+      }
+    }
+  }
+  normalizeRunState(value) {
+    if (value === "queued" || value === "running" || value === "completed" || value === "failed" || value === "aborted") {
+      return value;
+    }
+    return "failed";
+  }
+  getRunRecord(runId) {
+    const normalized = readOptionalString(runId);
+    if (!normalized) {
+      return null;
+    }
+    return this.runs.get(normalized) ?? null;
+  }
+};
+
 // src/cli/commands/service.ts
 var {
   APP_NAME: APP_NAME2,
@@ -2987,7 +3483,7 @@ var {
   CronService: CronService2,
   getApiBase,
   getConfigPath: getConfigPath3,
-  getDataDir: getDataDir5,
+  getDataDir: getDataDir6,
   getProvider,
   getProviderName,
   getWorkspacePath: getWorkspacePath5,
@@ -2999,7 +3495,7 @@ var {
   resolveConfigSecrets: resolveConfigSecrets2,
   saveConfig: saveConfig5,
   SessionManager,
-  parseAgentScopedSessionKey: parseAgentScopedSessionKey2
+  parseAgentScopedSessionKey: parseAgentScopedSessionKey3
 } = NextclawCore;
 function createSkillsLoader(workspace) {
   const ctor = NextclawCore.SkillsLoader;
@@ -3008,21 +3504,6 @@ function createSkillsLoader(workspace) {
   }
   return new ctor(workspace);
 }
-function isAbortError(error) {
-  if (error instanceof DOMException && error.name === "AbortError") {
-    return true;
-  }
-  if (error instanceof Error) {
-    if (error.name === "AbortError") {
-      return true;
-    }
-    const message = error.message.toLowerCase();
-    if (message.includes("aborted") || message.includes("abort")) {
-      return true;
-    }
-  }
-  return false;
-}
 var ServiceCommands = class {
   constructor(deps) {
     this.deps = deps;
@@ -3059,7 +3540,7 @@ var ServiceCommands = class {
         }
       }
     };
-    const cronStorePath = join4(getDataDir5(), "cron", "jobs.json");
+    const cronStorePath = join5(getDataDir6(), "cron", "jobs.json");
     const cron2 = new CronService2(cronStorePath);
     const uiConfig = resolveUiConfig(config2, options.uiOverrides);
     const uiStaticDir = options.uiStaticDir === void 0 ? resolveUiStaticDir() : options.uiStaticDir;
@@ -3213,7 +3694,7 @@ var ServiceCommands = class {
     } else {
       console.log("Warning: No channels enabled");
     }
-    this.startUiIfEnabled(uiConfig, uiStaticDir, cron2, runtimePool);
+    this.startUiIfEnabled(uiConfig, uiStaticDir, cron2, runtimePool, sessionManager);
     const cronStatus = cron2.status();
     if (cronStatus.jobs > 0) {
       console.log(`\u2713 Cron: ${cronStatus.jobs} scheduled jobs`);
@@ -3327,7 +3808,7 @@ var ServiceCommands = class {
     }
     const sessionKey = sentinelSessionKey ?? fallbackSessionKey ?? "cli:default";
     const parsedSession = parseSessionKey(sessionKey);
-    const parsedAgentSession = parseAgentScopedSessionKey2(sessionKey);
+    const parsedAgentSession = parseAgentScopedSessionKey3(sessionKey);
     const parsedSessionRoute = parsedSession && parsedSession.channel !== "agent" ? parsedSession : null;
     const context = payload.deliveryContext;
     const channel = this.normalizeOptionalString(context?.channel) ?? parsedSessionRoute?.channel ?? this.normalizeOptionalString((params.sessionManager.getIfExists(sessionKey)?.metadata ?? {}).last_channel);
@@ -3426,50 +3907,65 @@ var ServiceCommands = class {
     }
     const logPath = resolveServiceLogPath();
     const logDir = resolve7(logPath, "..");
-    mkdirSync3(logDir, { recursive: true });
+    mkdirSync4(logDir, { recursive: true });
     const logFd = openSync(logPath, "a");
+    const readinessTimeoutMs = this.resolveStartupTimeoutMs(options.startupTimeoutMs);
+    const quickPhaseTimeoutMs = Math.min(8e3, readinessTimeoutMs);
+    const extendedPhaseTimeoutMs = Math.max(0, readinessTimeoutMs - quickPhaseTimeoutMs);
+    this.appendStartupStage(
+      logPath,
+      `start requested: ui=${uiConfig.host}:${uiConfig.port}, readinessTimeoutMs=${readinessTimeoutMs}`
+    );
+    console.log(`Starting ${APP_NAME2} background service (readiness timeout ${Math.ceil(readinessTimeoutMs / 1e3)}s)...`);
     const serveArgs = buildServeArgs({
       uiPort: uiConfig.port
     });
+    this.appendStartupStage(logPath, `spawning background process: ${process.execPath} ${[...process.execArgv, ...serveArgs].join(" ")}`);
     const child = spawn2(process.execPath, [...process.execArgv, ...serveArgs], {
       env: process.env,
       stdio: ["ignore", logFd, logFd],
       detached: true
     });
+    this.appendStartupStage(logPath, `spawned background process pid=${child.pid ?? "unknown"}`);
     closeSync(logFd);
     if (!child.pid) {
+      this.appendStartupStage(logPath, "spawn failed: child pid missing");
       console.error("Error: Failed to start background service.");
       return;
     }
     const healthUrl = `${apiUrl}/health`;
+    this.appendStartupStage(logPath, `health probe started: ${healthUrl} (phase=quick, timeoutMs=${quickPhaseTimeoutMs})`);
     let readiness = await this.waitForBackgroundServiceReady({
       pid: child.pid,
       healthUrl,
-      timeoutMs: 8e3
+      timeoutMs: quickPhaseTimeoutMs
     });
-    if (!readiness.ready && isProcessRunning(child.pid)) {
-      const extendedTimeoutMs = process.platform === "win32" ? 2e4 : 25e3;
+    if (!readiness.ready && isProcessRunning(child.pid) && extendedPhaseTimeoutMs > 0) {
       console.warn(
-        `Warning: Background service is still running but not ready after 8s; waiting up to ${Math.ceil(extendedTimeoutMs / 1e3)}s more.`
+        `Warning: Background service is still running but not ready after ${Math.ceil(quickPhaseTimeoutMs / 1e3)}s; waiting up to ${Math.ceil(extendedPhaseTimeoutMs / 1e3)}s more.`
+      );
+      this.appendStartupStage(
+        logPath,
+        `health probe entering extended phase (timeoutMs=${extendedPhaseTimeoutMs}, lastError=${readiness.lastProbeError ?? "none"})`
       );
       readiness = await this.waitForBackgroundServiceReady({
         pid: child.pid,
         healthUrl,
-        timeoutMs: extendedTimeoutMs
+        timeoutMs: extendedPhaseTimeoutMs
       });
     }
     if (!readiness.ready) {
-      if (isProcessRunning(child.pid)) {
-        try {
-          process.kill(child.pid, "SIGTERM");
-          await waitForExit(child.pid, 2e3);
-        } catch {
-        }
+      if (!isProcessRunning(child.pid)) {
+        clearServiceState();
+        const hint = readiness.lastProbeError ? ` Last probe error: ${readiness.lastProbeError}` : "";
+        this.appendStartupStage(logPath, `startup failed: process exited before ready.${hint}`);
+        console.error(`Error: Failed to start background service. Check logs: ${logPath}.${hint}`);
+        return;
       }
-      clearServiceState();
-      const hint = readiness.lastProbeError ? ` Last probe error: ${readiness.lastProbeError}` : "";
-      console.error(`Error: Failed to start background service. Check logs: ${logPath}.${hint}`);
-      return;
+      this.appendStartupStage(
+        logPath,
+        `startup degraded: process alive but health probe timed out after ${readinessTimeoutMs}ms (lastError=${readiness.lastProbeError ?? "none"})`
+      );
     }
     child.unref();
     const state = {
@@ -3479,10 +3975,22 @@ var ServiceCommands = class {
       apiUrl,
       uiHost: uiConfig.host,
       uiPort: uiConfig.port,
-      logPath
+      logPath,
+      startupState: readiness.ready ? "ready" : "degraded",
+      startupLastProbeError: readiness.lastProbeError,
+      startupTimeoutMs: readinessTimeoutMs,
+      startupCheckedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     writeServiceState(state);
-    console.log(`\u2713 ${APP_NAME2} started in background (PID ${state.pid})`);
+    if (!readiness.ready) {
+      const hint = readiness.lastProbeError ? ` Last probe error: ${readiness.lastProbeError}` : "";
+      console.warn(
+        `Warning: ${APP_NAME2} is running (PID ${state.pid}) but not healthy yet after ${Math.ceil(readinessTimeoutMs / 1e3)}s. Marked as degraded.${hint}`
+      );
+      console.warn(`Tip: Run "${APP_NAME2} status --json" and check logs: ${logPath}`);
+    } else {
+      console.log(`\u2713 ${APP_NAME2} started in background (PID ${state.pid})`);
+    }
     console.log(`UI: ${uiUrl}`);
     console.log(`API: ${apiUrl}`);
     await this.printPublicUiUrls(uiConfig.host, uiConfig.port);
@@ -3544,6 +4052,22 @@ var ServiceCommands = class {
     }
     return { ready: false, lastProbeError };
   }
+  resolveStartupTimeoutMs(overrideTimeoutMs) {
+    const fallback = process.platform === "win32" ? 28e3 : 33e3;
+    const envRaw = process.env.NEXTCLAW_START_TIMEOUT_MS?.trim();
+    const envValue = envRaw ? Number(envRaw) : Number.NaN;
+    const fromEnv = Number.isFinite(envValue) && envValue > 0 ? Math.floor(envValue) : null;
+    const fromOverride = Number.isFinite(overrideTimeoutMs) && Number(overrideTimeoutMs) > 0 ? Math.floor(Number(overrideTimeoutMs)) : null;
+    const resolved = fromOverride ?? fromEnv ?? fallback;
+    return Math.max(3e3, resolved);
+  }
+  appendStartupStage(logPath, message) {
+    try {
+      appendFileSync(logPath, `[${(/* @__PURE__ */ new Date()).toISOString()}] [startup] ${message}
+`, "utf-8");
+    } catch {
+    }
+  }
   async probeHealthEndpoint(healthUrl) {
     let parsed;
     try {
@@ -3651,11 +4175,10 @@ var ServiceCommands = class {
     console.log(`  - Check status: ${APP_NAME2} status`);
     console.log(`  - If you need to stop the service, run: ${APP_NAME2} stop`);
   }
-  startUiIfEnabled(uiConfig, uiStaticDir, cronService, runtimePool) {
+  startUiIfEnabled(uiConfig, uiStaticDir, cronService, runtimePool, sessionManager) {
     if (!uiConfig.enabled) {
       return;
     }
-    const activeTurnRuns = /* @__PURE__ */ new Map();
     const resolveStopCapability = (params) => runtimePool.supportsTurnAbort({
       sessionKey: params.sessionKey,
       agentId: params.agentId,
@@ -3665,7 +4188,7 @@ var ServiceCommands = class {
     });
     const resolveChatTurnParams = (params) => {
       const sessionKey = typeof params.sessionKey === "string" && params.sessionKey.trim().length > 0 ? params.sessionKey.trim() : `ui:${Date.now().toString(36)}:${Math.random().toString(36).slice(2, 8)}`;
-      const inferredAgentId = typeof params.agentId === "string" && params.agentId.trim().length > 0 ? params.agentId.trim() : parseAgentScopedSessionKey2(sessionKey)?.agentId;
+      const inferredAgentId = typeof params.agentId === "string" && params.agentId.trim().length > 0 ? params.agentId.trim() : parseAgentScopedSessionKey3(sessionKey)?.agentId;
       const model = typeof params.model === "string" && params.model.trim().length > 0 ? params.model.trim() : void 0;
       const metadata = params.metadata && typeof params.metadata === "object" && !Array.isArray(params.metadata) ? { ...params.metadata } : {};
       if (model) {
@@ -3688,6 +4211,14 @@ var ServiceCommands = class {
       ...params.inferredAgentId ? { agentId: params.inferredAgentId } : {},
       ...params.model ? { model: params.model } : {}
     });
+    let publishUiEvent = null;
+    const runCoordinator = new UiChatRunCoordinator({
+      runtimePool,
+      sessionManager,
+      onRunUpdated: (run) => {
+        publishUiEvent?.({ type: "run.updated", payload: { run } });
+      }
+    });
     const uiServer = startUiServer({
       host: uiConfig.host,
       port: uiConfig.port,
@@ -3737,153 +4268,32 @@ var ServiceCommands = class {
             model: resolved.model
           });
         },
-        stopTurn: async (params) => {
-          const runId = typeof params.runId === "string" ? params.runId.trim() : "";
-          if (!runId) {
-            return {
-              stopped: false,
-              runId: "",
-              reason: "runId is required"
-            };
-          }
-          const active = activeTurnRuns.get(runId);
-          if (!active) {
-            return {
-              stopped: false,
-              runId,
-              ...typeof params.sessionKey === "string" && params.sessionKey.trim().length > 0 ? { sessionKey: params.sessionKey.trim() } : {},
-              reason: "run not found or already completed"
-            };
-          }
-          const requestedSessionKey = typeof params.sessionKey === "string" ? params.sessionKey.trim() : "";
-          if (requestedSessionKey && requestedSessionKey !== active.sessionKey) {
-            return {
-              stopped: false,
-              runId,
-              sessionKey: active.sessionKey,
-              reason: "session key mismatch"
-            };
+        startTurnRun: async (params) => {
+          return runCoordinator.startRun(params);
+        },
+        listRuns: async (params) => {
+          return runCoordinator.listRuns(params);
+        },
+        getRun: async (params) => {
+          return runCoordinator.getRun(params);
+        },
+        streamRun: async function* (params) {
+          for await (const event of runCoordinator.streamRun(params)) {
+            yield event;
           }
-          active.controller.abort(new Error("chat turn stopped by user"));
-          return {
-            stopped: true,
-            runId,
-            sessionKey: active.sessionKey
-          };
+        },
+        stopTurn: async (params) => {
+          return await runCoordinator.stopRun(params);
         },
         processTurnStream: async function* (params) {
-          const resolved = resolveChatTurnParams(params);
-          const runId = resolved.runId ?? `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-          const stopCapability = resolveStopCapability({
-            sessionKey: resolved.sessionKey,
-            agentId: resolved.inferredAgentId,
-            channel: resolved.channel,
-            chatId: resolved.chatId,
-            metadata: resolved.metadata
-          });
-          const controller = stopCapability.supported ? new AbortController() : null;
-          if (controller) {
-            activeTurnRuns.set(runId, {
-              controller,
-              sessionKey: resolved.sessionKey,
-              ...resolved.inferredAgentId ? { agentId: resolved.inferredAgentId } : {}
-            });
-          }
-          const queue = [];
-          const assistantDeltaParts = [];
-          let waiter = null;
-          const push = (event) => {
-            queue.push(event);
-            const currentWaiter = waiter;
-            waiter = null;
-            currentWaiter?.();
-          };
-          const run = runtimePool.processDirect({
-            content: params.message,
-            sessionKey: resolved.sessionKey,
-            channel: resolved.channel,
-            chatId: resolved.chatId,
-            agentId: resolved.inferredAgentId,
-            metadata: resolved.metadata,
-            ...controller ? { abortSignal: controller.signal } : {},
-            onAssistantDelta: (delta) => {
-              if (typeof delta !== "string" || delta.length === 0) {
-                return;
-              }
-              assistantDeltaParts.push(delta);
-              push({ type: "delta", delta });
-            },
-            onSessionEvent: (event) => {
-              const raw = event.data?.message;
-              const messageRecord = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : null;
-              const message = messageRecord && typeof messageRecord.role === "string" ? {
-                role: messageRecord.role,
-                content: messageRecord.content,
-                timestamp: typeof messageRecord.timestamp === "string" ? messageRecord.timestamp : event.timestamp,
-                ...typeof messageRecord.name === "string" ? { name: messageRecord.name } : {},
-                ...typeof messageRecord.tool_call_id === "string" ? { tool_call_id: messageRecord.tool_call_id } : {},
-                ...Array.isArray(messageRecord.tool_calls) ? { tool_calls: messageRecord.tool_calls } : {},
-                ...typeof messageRecord.reasoning_content === "string" ? { reasoning_content: messageRecord.reasoning_content } : {}
-              } : void 0;
-              push({
-                type: "session_event",
-                event: {
-                  seq: event.seq,
-                  type: event.type,
-                  timestamp: event.timestamp,
-                  ...message ? { message } : {}
-                }
-              });
-            }
-          }).then((reply) => {
-            push({
-              type: "final",
-              result: buildTurnResult({
-                reply,
-                sessionKey: resolved.sessionKey,
-                inferredAgentId: resolved.inferredAgentId,
-                model: resolved.model
-              })
-            });
-          }).catch((error) => {
-            if ((controller?.signal.aborted ?? false) || isAbortError(error)) {
-              const partialReply = assistantDeltaParts.join("");
-              push({
-                type: "final",
-                result: buildTurnResult({
-                  reply: partialReply,
-                  sessionKey: resolved.sessionKey,
-                  inferredAgentId: resolved.inferredAgentId,
-                  model: resolved.model
-                })
-              });
-              return;
-            }
-            push({ type: "error", error: String(error) });
-          }).finally(() => {
-            activeTurnRuns.delete(runId);
-          });
-          while (true) {
-            if (queue.length === 0) {
-              await new Promise((resolve10) => {
-                waiter = resolve10;
-              });
-            }
-            while (queue.length > 0) {
-              const event = queue.shift();
-              if (!event) {
-                continue;
-              }
-              yield event;
-              if (event.type === "final" || event.type === "error") {
-                await run;
-                return;
-              }
-            }
+          const run = runCoordinator.startRun(params);
+          for await (const event of runCoordinator.streamRun({ runId: run.runId })) {
+            yield event;
           }
         }
       }
     });
+    publishUiEvent = uiServer.publish;
     const uiUrl = `http://${uiServer.host}:${uiServer.port}`;
     console.log(`\u2713 UI API: ${uiUrl}/api`);
     if (uiStaticDir) {
@@ -3940,17 +4350,17 @@ var ServiceCommands = class {
     const workspace = getWorkspacePath5(loadConfig6().agents.defaults.workspace);
     const skillName = this.resolveGitSkillName(params.skill, source);
     const destination = this.resolveSkillInstallPath(workspace, params.installPath, skillName);
-    const destinationSkillFile = join4(destination, "SKILL.md");
-    if (existsSync7(destinationSkillFile) && !params.force) {
+    const destinationSkillFile = join5(destination, "SKILL.md");
+    if (existsSync8(destinationSkillFile) && !params.force) {
       return {
         message: `${skillName} is already installed`,
         output: destination
       };
     }
-    if (existsSync7(destination) && !params.force) {
+    if (existsSync8(destination) && !params.force) {
       throw new Error(`Skill install path already exists: ${destination} (use force to overwrite)`);
     }
-    if (existsSync7(destination) && params.force) {
+    if (existsSync8(destination) && params.force) {
       rmSync3(destination, { recursive: true, force: true });
     }
     const skildArgs = ["--yes", "skild", "install", source, "--target", "agents", "--local", "--json", "--skill", skillName];
@@ -3985,11 +4395,11 @@ var ServiceCommands = class {
       throw new Error("skild returned null json payload even after force reinstall");
     }
     const installDir = typeof payload.installDir === "string" ? payload.installDir.trim() : "";
-    const installSkillFile = installDir ? join4(installDir, "SKILL.md") : "";
-    if (!installDir || !existsSync7(installSkillFile)) {
+    const installSkillFile = installDir ? join5(installDir, "SKILL.md") : "";
+    if (!installDir || !existsSync8(installSkillFile)) {
       throw new Error(`skild install did not produce a valid skill directory for ${skillName}`);
     }
-    mkdirSync3(dirname(destination), { recursive: true });
+    mkdirSync4(dirname(destination), { recursive: true });
     if (resolve7(installDir) !== resolve7(destination)) {
       cpSync(installDir, destination, { recursive: true, force: true });
     }
@@ -4020,9 +4430,9 @@ var ServiceCommands = class {
   }
   async uninstallMarketplaceSkill(slug) {
     const workspace = getWorkspacePath5(loadConfig6().agents.defaults.workspace);
-    const targetDir = join4(workspace, "skills", slug);
-    const skildDir = join4(workspace, ".agents", "skills", slug);
-    const existingTargets = [targetDir, skildDir].filter((path) => existsSync7(path));
+    const targetDir = join5(workspace, "skills", slug);
+    const skildDir = join5(workspace, ".agents", "skills", slug);
+    const existingTargets = [targetDir, skildDir].filter((path) => existsSync8(path));
     if (existingTargets.length === 0) {
       throw new Error(`Skill not installed in workspace: ${slug}`);
     }
@@ -4036,9 +4446,9 @@ var ServiceCommands = class {
   }
   installBuiltinMarketplaceSkill(slug, force) {
     const workspace = getWorkspacePath5(loadConfig6().agents.defaults.workspace);
-    const destination = join4(workspace, "skills", slug);
-    const destinationSkillFile = join4(destination, "SKILL.md");
-    if (existsSync7(destinationSkillFile) && !force) {
+    const destination = join5(workspace, "skills", slug);
+    const destinationSkillFile = join5(destination, "SKILL.md");
+    if (existsSync8(destinationSkillFile) && !force) {
       return {
         message: `${slug} is already installed`,
         output: destination
@@ -4047,7 +4457,7 @@ var ServiceCommands = class {
     const loader = createSkillsLoader(workspace);
     const builtin = (loader?.listSkills(false) ?? []).find((skill) => skill.name === slug && skill.source === "builtin");
     if (!builtin) {
-      if (existsSync7(destinationSkillFile)) {
+      if (existsSync8(destinationSkillFile)) {
         return {
           message: `${slug} is already installed`,
           output: destination
@@ -4055,7 +4465,7 @@ var ServiceCommands = class {
       }
       return null;
     }
-    mkdirSync3(join4(workspace, "skills"), { recursive: true });
+    mkdirSync4(join5(workspace, "skills"), { recursive: true });
     cpSync(dirname(builtin.path), destination, { recursive: true, force: true });
     return {
       message: `Installed skill: ${slug}`,
@@ -4082,7 +4492,7 @@ var ServiceCommands = class {
     return skillName;
   }
   resolveSkillInstallPath(workspace, installPath, skillName) {
-    const requested = typeof installPath === "string" && installPath.trim().length > 0 ? installPath.trim() : join4("skills", skillName);
+    const requested = typeof installPath === "string" && installPath.trim().length > 0 ? installPath.trim() : join5("skills", skillName);
     if (isAbsolute2(requested)) {
       throw new Error("installPath must be relative to workspace");
     }
@@ -4197,11 +4607,11 @@ ${stderr}`.trim();
 };
 
 // src/cli/workspace.ts
-import { cpSync as cpSync2, existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync6, readdirSync, rmSync as rmSync4, writeFileSync as writeFileSync3 } from "fs";
+import { cpSync as cpSync2, existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync7, readdirSync as readdirSync2, rmSync as rmSync4, writeFileSync as writeFileSync4 } from "fs";
 import { createRequire } from "module";
-import { dirname as dirname2, join as join5, resolve as resolve8 } from "path";
+import { dirname as dirname2, join as join6, resolve as resolve8 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import { APP_NAME as APP_NAME3, getDataDir as getDataDir6 } from "@nextclaw/core";
+import { APP_NAME as APP_NAME3, getDataDir as getDataDir7 } from "@nextclaw/core";
 import { spawnSync as spawnSync4 } from "child_process";
 var WorkspaceManager = class {
   constructor(logo) {
@@ -4229,30 +4639,30 @@ var WorkspaceManager = class {
       { source: "memory/MEMORY.md", target: "memory/MEMORY.md" }
     ];
     for (const entry of templateFiles) {
-      const filePath = join5(workspace, entry.target);
-      if (!force && existsSync8(filePath)) {
+      const filePath = join6(workspace, entry.target);
+      if (!force && existsSync9(filePath)) {
         continue;
       }
-      const templatePath = join5(templateDir, entry.source);
-      if (!existsSync8(templatePath)) {
+      const templatePath = join6(templateDir, entry.source);
+      if (!existsSync9(templatePath)) {
         console.warn(`Warning: Template file missing: ${templatePath}`);
         continue;
       }
-      const raw = readFileSync6(templatePath, "utf-8");
+      const raw = readFileSync7(templatePath, "utf-8");
       const content = raw.replace(/\$\{APP_NAME\}/g, APP_NAME3);
-      mkdirSync4(dirname2(filePath), { recursive: true });
-      writeFileSync3(filePath, content);
+      mkdirSync5(dirname2(filePath), { recursive: true });
+      writeFileSync4(filePath, content);
       created.push(entry.target);
     }
-    const memoryDir = join5(workspace, "memory");
-    if (!existsSync8(memoryDir)) {
-      mkdirSync4(memoryDir, { recursive: true });
-      created.push(join5("memory", ""));
+    const memoryDir = join6(workspace, "memory");
+    if (!existsSync9(memoryDir)) {
+      mkdirSync5(memoryDir, { recursive: true });
+      created.push(join6("memory", ""));
     }
-    const skillsDir = join5(workspace, "skills");
-    if (!existsSync8(skillsDir)) {
-      mkdirSync4(skillsDir, { recursive: true });
-      created.push(join5("skills", ""));
+    const skillsDir = join6(workspace, "skills");
+    if (!existsSync9(skillsDir)) {
+      mkdirSync5(skillsDir, { recursive: true });
+      created.push(join6("skills", ""));
     }
     const seeded = this.seedBuiltinSkills(skillsDir, { force });
     if (seeded > 0) {
@@ -4267,16 +4677,16 @@ var WorkspaceManager = class {
     }
     const force = Boolean(options.force);
     let seeded = 0;
-    for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+    for (const entry of readdirSync2(sourceDir, { withFileTypes: true })) {
       if (!entry.isDirectory()) {
         continue;
       }
-      const src = join5(sourceDir, entry.name);
-      if (!existsSync8(join5(src, "SKILL.md"))) {
+      const src = join6(sourceDir, entry.name);
+      if (!existsSync9(join6(src, "SKILL.md"))) {
         continue;
       }
-      const dest = join5(targetDir, entry.name);
-      if (!force && existsSync8(dest)) {
+      const dest = join6(targetDir, entry.name);
+      if (!force && existsSync9(dest)) {
         continue;
       }
       cpSync2(src, dest, { recursive: true, force: true });
@@ -4289,12 +4699,12 @@ var WorkspaceManager = class {
       const require2 = createRequire(import.meta.url);
       const entry = require2.resolve("@nextclaw/core");
       const pkgRoot = resolve8(dirname2(entry), "..");
-      const distSkills = join5(pkgRoot, "dist", "skills");
-      if (existsSync8(distSkills)) {
+      const distSkills = join6(pkgRoot, "dist", "skills");
+      if (existsSync9(distSkills)) {
         return distSkills;
       }
-      const srcSkills = join5(pkgRoot, "src", "agent", "skills");
-      if (existsSync8(srcSkills)) {
+      const srcSkills = join6(pkgRoot, "src", "agent", "skills");
+      if (existsSync9(srcSkills)) {
         return srcSkills;
       }
       return null;
@@ -4309,17 +4719,17 @@ var WorkspaceManager = class {
     }
     const cliDir = resolve8(fileURLToPath3(new URL(".", import.meta.url)));
     const pkgRoot = resolve8(cliDir, "..", "..");
-    const candidates = [join5(pkgRoot, "templates")];
+    const candidates = [join6(pkgRoot, "templates")];
     for (const candidate of candidates) {
-      if (existsSync8(candidate)) {
+      if (existsSync9(candidate)) {
         return candidate;
       }
     }
     return null;
   }
   getBridgeDir() {
-    const userBridge = join5(getDataDir6(), "bridge");
-    if (existsSync8(join5(userBridge, "dist", "index.js"))) {
+    const userBridge = join6(getDataDir7(), "bridge");
+    if (existsSync9(join6(userBridge, "dist", "index.js"))) {
       return userBridge;
     }
     if (!which("npm")) {
@@ -4328,12 +4738,12 @@ var WorkspaceManager = class {
     }
     const cliDir = resolve8(fileURLToPath3(new URL(".", import.meta.url)));
     const pkgRoot = resolve8(cliDir, "..", "..");
-    const pkgBridge = join5(pkgRoot, "bridge");
-    const srcBridge = join5(pkgRoot, "..", "..", "bridge");
+    const pkgBridge = join6(pkgRoot, "bridge");
+    const srcBridge = join6(pkgRoot, "..", "..", "bridge");
     let source = null;
-    if (existsSync8(join5(pkgBridge, "package.json"))) {
+    if (existsSync9(join6(pkgBridge, "package.json"))) {
       source = pkgBridge;
-    } else if (existsSync8(join5(srcBridge, "package.json"))) {
+    } else if (existsSync9(join6(srcBridge, "package.json"))) {
       source = srcBridge;
     }
     if (!source) {
@@ -4341,8 +4751,8 @@ var WorkspaceManager = class {
       process.exit(1);
     }
     console.log(`${this.logo} Setting up bridge...`);
-    mkdirSync4(resolve8(userBridge, ".."), { recursive: true });
-    if (existsSync8(userBridge)) {
+    mkdirSync5(resolve8(userBridge, ".."), { recursive: true });
+    if (existsSync9(userBridge)) {
       rmSync4(userBridge, { recursive: true, force: true });
     }
     cpSync2(source, userBridge, {
@@ -4471,7 +4881,7 @@ var CliRuntime = class {
     const delayMs = typeof params.delayMs === "number" && Number.isFinite(params.delayMs) ? Math.max(0, Math.floor(params.delayMs)) : 100;
     const cliPath = process.env.NEXTCLAW_SELF_RELAUNCH_CLI?.trim() || fileURLToPath4(new URL("./index.js", import.meta.url));
     const startArgs = [cliPath, "start", "--ui-port", String(uiPort)];
-    const serviceStatePath = resolve9(getDataDir7(), "run", "service.json");
+    const serviceStatePath = resolve9(getDataDir8(), "run", "service.json");
     const helperScript = [
       'const { spawnSync } = require("node:child_process");',
       'const { readFileSync } = require("node:fs");',
@@ -4601,16 +5011,16 @@ var CliRuntime = class {
     const force = Boolean(options.force);
     const configPath = getConfigPath4();
     let createdConfig = false;
-    if (!existsSync9(configPath)) {
+    if (!existsSync10(configPath)) {
       const config3 = ConfigSchema2.parse({});
       saveConfig6(config3);
       createdConfig = true;
     }
     const config2 = loadConfig7();
     const workspaceSetting = config2.agents.defaults.workspace;
-    const workspacePath = !workspaceSetting || workspaceSetting === DEFAULT_WORKSPACE_PATH ? join6(getDataDir7(), DEFAULT_WORKSPACE_DIR) : expandHome2(workspaceSetting);
-    const workspaceExisted = existsSync9(workspacePath);
-    mkdirSync5(workspacePath, { recursive: true });
+    const workspacePath = !workspaceSetting || workspaceSetting === DEFAULT_WORKSPACE_PATH ? join7(getDataDir8(), DEFAULT_WORKSPACE_DIR) : expandHome2(workspaceSetting);
+    const workspaceExisted = existsSync10(workspacePath);
+    mkdirSync6(workspacePath, { recursive: true });
     const templateResult = this.workspaceManager.createWorkspaceTemplates(
       workspacePath,
       { force }
@@ -4669,6 +5079,7 @@ ${this.logo} ${APP_NAME4} is ready! (${source})`);
     });
   }
   async start(opts) {
+    const startupTimeoutMs = this.parseStartTimeoutMs(opts.startTimeout);
     await this.init({ source: "start", auto: true });
     const uiOverrides = {
       enabled: true,
@@ -4680,7 +5091,8 @@ ${this.logo} ${APP_NAME4} is ready! (${source})`);
     }
     await this.serviceCommands.startService({
       uiOverrides,
-      open: Boolean(opts.open)
+      open: Boolean(opts.open),
+      startupTimeoutMs
     });
   }
   async restart(opts) {
@@ -4711,6 +5123,17 @@ ${this.logo} ${APP_NAME4} is ready! (${source})`);
       open: Boolean(opts.open)
     });
   }
+  parseStartTimeoutMs(value) {
+    if (value === void 0) {
+      return void 0;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      console.error("Invalid --start-timeout value. Provide milliseconds (e.g. 45000).");
+      process.exit(1);
+    }
+    return Math.floor(parsed);
+  }
   async stop() {
     await this.serviceCommands.stopService();
   }
@@ -4784,10 +5207,10 @@ ${this.logo} ${APP_NAME4} is ready! (${source})`);
         `${this.logo} Interactive mode (type exit or Ctrl+C to quit)
 `
       );
-      const historyFile = join6(getDataDir7(), "history", "cli_history");
+      const historyFile = join7(getDataDir8(), "history", "cli_history");
       const historyDir = resolve9(historyFile, "..");
-      mkdirSync5(historyDir, { recursive: true });
-      const history = existsSync9(historyFile) ? readFileSync7(historyFile, "utf-8").split("\n").filter(Boolean) : [];
+      mkdirSync6(historyDir, { recursive: true });
+      const history = existsSync10(historyFile) ? readFileSync8(historyFile, "utf-8").split("\n").filter(Boolean) : [];
       const rl = createInterface2({
         input: process.stdin,
         output: process.stdout
@@ -4796,7 +5219,7 @@ ${this.logo} ${APP_NAME4} is ready! (${source})`);
         const merged = history.concat(
           rl.history ?? []
         );
-        writeFileSync4(historyFile, merged.join("\n"));
+        writeFileSync5(historyFile, merged.join("\n"));
         process.exit(0);
       });
       let running = true;
@@ -4972,8 +5395,8 @@ program.command("onboard").description(`Initialize ${APP_NAME5} configuration an
 program.command("init").description(`Initialize ${APP_NAME5} configuration and workspace`).option("-f, --force", "Overwrite existing template files").action(async (opts) => runtime.init({ force: Boolean(opts.force) }));
 program.command("gateway").description(`Start the ${APP_NAME5} gateway`).option("-p, --port <port>", "Gateway port", "18790").option("-v, --verbose", "Verbose output", false).option("--ui", "Enable UI server", false).option("--ui-port <port>", "UI port").option("--ui-open", "Open browser when UI starts", false).action(async (opts) => runtime.gateway(opts));
 program.command("ui").description(`Start the ${APP_NAME5} UI with gateway`).option("--port <port>", "UI port").option("--no-open", "Disable opening browser").action(async (opts) => runtime.ui(opts));
-program.command("start").description(`Start the ${APP_NAME5} gateway + UI in the background`).option("--ui-port <port>", "UI port").option("--open", "Open browser after start", false).action(async (opts) => runtime.start(opts));
-program.command("restart").description(`Restart the ${APP_NAME5} background service`).option("--ui-port <port>", "UI port").option("--open", "Open browser after restart", false).action(async (opts) => runtime.restart(opts));
+program.command("start").description(`Start the ${APP_NAME5} gateway + UI in the background`).option("--ui-port <port>", "UI port").option("--start-timeout <ms>", "Maximum wait time for startup readiness in milliseconds").option("--open", "Open browser after start", false).action(async (opts) => runtime.start(opts));
+program.command("restart").description(`Restart the ${APP_NAME5} background service`).option("--ui-port <port>", "UI port").option("--start-timeout <ms>", "Maximum wait time for startup readiness in milliseconds").option("--open", "Open browser after restart", false).action(async (opts) => runtime.restart(opts));
 program.command("serve").description(`Run the ${APP_NAME5} gateway + UI in the foreground`).option("--ui-port <port>", "UI port").option("--open", "Open browser after start", false).action(async (opts) => runtime.serve(opts));
 program.command("stop").description(`Stop the ${APP_NAME5} background service`).action(async () => runtime.stop());
 program.command("agent").description("Interact with the agent directly").option("-m, --message <message>", "Message to send to the agent").option("-s, --session <session>", "Session ID", "cli:default").option("--model <model>", "Session model override for this run").option("--no-markdown", "Disable Markdown rendering").action(async (opts) => runtime.agent(opts));