dsh-llm-workbuddy 0.1.3 → 0.1.5

package/README.md

@@ -92,33 +92,53 @@ CLI 会把依赖写进 profile 并把 `dsh-llm-workbuddy` 追加到 `dsh.profile
 
 ## 安装代理（先决条件，第三方）
 
-插件只提供模型路由与登录；真正的协议转换由 **workbuddy2api** 完成。请单独安装并
-启动它（以 127.0.0.1:8787 为例）：
+插件只提供模型路由与登录；真正的协议转换由 **workbuddy2api**（第三方开源项目）完成。
+它**不在本插件包里**，需要单独安装并启动在 `127.0.0.1:8787`。分两种情况：
+
+### 全新机器 / 标准安装（任何能跑 Python 的机器）
+
+别人或你自己在**新机器**上用 npm 版插件时，按以下 3 步装代理：
 
 ```sh
-# 1. 安装 uv（本机 Python 工具）
+# 1. 安装 uv（本机 Python 工具，若已装可跳过）
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
 # 2. 拉取 workbuddy2api 主分支源码
 git clone https://github.com/hawklithm/workbuddy2api.git
 cd workbuddy2api
 
-# 3. 启动代理（先完成下方「登录」后再请求）
+# 3. 启动代理（监听 127.0.0.1:8787；先完成下方「登录」后再真正调用模型）
 uv run python -u -m codebuddy_proxy --desensitize \
   --session-file ~/.codebuddy-session.json \
   --log-file ~/.codebuddy-proxy.jsonl
-# 监听 http://127.0.0.1:8787
 ```
 
-> 仓库根目录也有 `start-workbuddy.sh` 脚本（面向仓库本地开发），发布版插件不依赖它。
+> 之后任何时候想重启代理，就在 `workbuddy2api` 目录里重跑上面第 3 条命令。
+> 若提示 `address already in use`，先停掉旧代理：
+> `lsof -tiTCP:8787 -sTCP:LISTEN | xargs kill`，再重跑。
+
+### 本仓库本地开发（可选快捷方式）
 
-验证：
+仓库根目录提供 `start-workbuddy.sh`，它会用仓库固定的 `main` 分支源码 + 本地
+`.tools/uv` 工具链 + 仓库内的 `.workbuddy/session.json` 启动代理。它**不随 npm
+包发布**，仅面向本仓库开发时方便：
+
+```sh
+cd /path/to/dsh-workbuddy
+./start-workbuddy.sh
+```
+
+### 验证代理是否真的能用
 
 ```sh
 curl http://127.0.0.1:8787/health    # {"status":"ok","authenticated":true,...}
 curl http://127.0.0.1:8787/v1/models # 模型列表（含 glm-5.2 / deepseek-v4-pro ...）
 ```
 
+> ⚠️ `/health` 只证明**代理进程活着**，不能证明模型能真正出字（代理进程指向旧
+> 路径/文件缺失时 `/health` 仍返回 `authenticated: true`，但所有模型请求 500）。
+> 想确认"模型真能用"，用右下角胶囊的 **🔍 诊断** 按钮，它会真实发一次模型请求。
+
 > 登录态过期时 `authenticated` 变回 `false`，重跑登录即可，代理无需重启
 > （会话按请求读取）。
 
@@ -174,6 +194,7 @@ Web 登录后终端脚本也读得到同一份会话。
 |---|---|
 | `GET /api/workbuddy/status` | 读取会话文件（默认 `~/.codebuddy-session.json`，或配置的 `sessionFile`）的 `auth.expiresAt` 判断会话是否有效，并 `fetch` 代理 `/health` 判断 `proxyUp`；返回 JSON：`{ sessionFile, authenticated, expiresAt, account, proxyUp, tokenValid, loginScriptAvailable }`；非 GET 返回 405 |
 | `POST /api/workbuddy/login` | 若已有有效会话则直接返回 `alreadyLoggedIn`；否则用系统 `python3` `spawn` 包内 `login_workbuddy.py --session-file <sessionFile>`，从子进程 stdout 解析出 `authUrl` 立即返回 `{ authUrl, pending:true }`（设备流在后台继续，前端轮询 status 感知完成）；非 POST 返回 405 |
+| `POST /api/workbuddy/diagnose` | **一键诊断**：真实探测健康状态，返回 `{ ok, session, health, chat, loginScriptAvailable, restartCommand }`。与 `/status` 不同，它除了探 `/health`，还会**真实发一次最小模型请求**（`chat.chatWorking`），能戳穿"胶囊显示成功但模型全 500"的假象；`ok:false` 时附带 `restartCommand`（自动区分本地 monorepo 布局与标准安装）；非 POST 返回 405 |
 
 > 会话文件与登录脚本路径的解析顺序：
 > 1. 配置里显式指定的 `sessionFile` / `loginScript`；
@@ -186,10 +207,36 @@ Web 登录后终端脚本也读得到同一份会话。
 - 启动时在 `document.body` 末尾挂一个 `position:fixed` 的胶囊（右下角）。
 - 每 **5 秒** `GET /api/workbuddy/status`；点「登录」后加快到每 **2 秒**轮询、
   最多 30 次，直到 `authenticated:true`。
+- 胶囊里有个 **🔍 诊断** 按钮：点它 `POST /api/workbuddy/diagnose`，弹出一个面板
+  显示**真实健康状态**（登录、会话文件、代理进程、登录令牌、模型能否出字），
+  发现问题时附带**可复制的重启命令**（一键复制到终端执行）。
 - 状态映射：
   - `authenticated && proxyUp` → 🟢 绿，显示 `WorkBuddy · <昵称>`
   - 否则 → 🔴 红，显示「登录」按钮；`proxyUp` 为 false 时额外提示 `代理未运行`
 
+> **关于 UI 挂载位置（临时做法说明）**
+>
+> 当前状态胶囊用 `position:fixed` 直接注入 `document.body`。DSH 官方的 UI
+> 组合机制是 **slot 系统**（`@deepseek-ai/dsh-client-ui-slots`，`ctx.slots.register`
+> 注册 React 组件进声明的 slot）。按官方「组合优先、不要假设/覆盖其他插件内部实现」
+> 的原则，理想做法是注册进官方 slot，而非直接改产品外壳。
+>
+> 评估结论：**当前 shell 声明的 slot 里没有专门的「右下角状态位」**；最接近的
+> `sidebar.footer.action`、`conversation.session.header.actions`、
+> `conversation.input.overlay` 都是 **React 组件位**，迁移意味着要把本插件从
+> 「零依赖原生 JS」改造成 **React + 构建流程**，并依赖 shell 暴露 `ctx.slots`
+> 服务。因此现阶段保留 DOM 注入（机制允许），**待官方 shell 提供合适的状态胶囊
+> slot 后再迁移**。以下是已知的迁移路径（供后续参考）：
+>
+> ```js
+> ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
+>   name: "sidebar.footer.action",
+>   id: "workbuddy-status",
+>   locale: NS,
+>   inject: () => ({ /* 轮询句柄 / 登录回调 */ })
+> }, WorkBuddyStatusPill /* React 组件 */));
+> ```
+
 ### 为什么不需要构建
 
 DSH 的 `dsh.client` 机制只要求 `package.json` 里：
@@ -239,6 +286,7 @@ DSH 的 `dsh.client` 机制只要求 `package.json` 里：
 | 右下角没有胶囊 | `dsh web` 没重启加载新 bundle → 重启 `dsh web`；或 `curl /plugins/dsh-llm-workbuddy/client.js` 应返回 200 |
 | 胶囊一直 `…`（加载中） | `GET /api/workbuddy/status` 失败 → 确认 `dsh web` 在跑、端口正确 |
 | 胶囊红 + `代理未运行` | workbuddy2api 代理没起或挂了 → 按「安装代理」章节启动 |
+| 胶囊显示登录成功但模型用不了 | 典型的"代理进程活着但指向旧路径/文件缺失"假象（`/health` 仍显示 ok）。点胶囊 **🔍 诊断**，看 `模型出字` 是否失败；按面板给出的重启命令重启代理 |
 | 点「登录」没反应 / 按钮灰 | `loginScriptAvailable:false` → 包内 `login_workbuddy.py` 缺失或系统无 `python3`；检查安装 |
 | 新标签页打开后登录完成，胶囊仍是红 | 会话文件（默认 `~/.codebuddy-session.json`）未刷新或 `expiresAt` 已过期 → 刷新页面或重跑登录 |
 | 启动 `dsh web` 报 `EPERM ... cordis.yml` | `.dsh` 所在系统卷受保护（`/System/Volumes/Data` 带 `protect`）。解决：`sudo chown -R $(whoami) /Users/jiyunyang/.dsh`，或 `export DSH_HOME=$HOME/dsh-home` 后重新 `dsh plugin --profile web add` 并把插件链接进新 home |
@@ -261,8 +309,8 @@ DSH 的 `dsh.client` 机制只要求 `package.json` 里：
 
 | 路径 | 作用 |
 |---|---|
-| `lib/index.js` | Cordis 插件主体：LLM 适配器 `WorkBuddyAdapter` + `/api/workbuddy/*` 路由注册 |
-| `lib/client.js` | 零依赖浏览器小部件（状态胶囊 + 登录流程），被 `dsh.client` 注入 |
+| `lib/index.js` | Cordis 插件主体：LLM 适配器 `WorkBuddyAdapter` + `/api/workbuddy/*` 路由（status / login / **diagnose**） |
+| `lib/client.js` | 零依赖浏览器小部件（状态胶囊 + 登录流程 + **🔍 诊断**），被 `dsh.client` 注入 |
 | `login_workbuddy.py` | 设备流登录脚本（随包发布，被后端路由用系统 `python3` spawn） |
 | `cordis.patch.yml` | 本包的 Cordis bundle 挂载声明（`id: llm-workbuddy`） |
 | `package.json` | 包元数据、`dsh.client` 浏览器入口声明、`llm-workbuddy` peer 依赖 |

package/lib/client.js

@@ -105,11 +105,15 @@ function runWidget() {
       html += '<button class="wb-btn" id="wb-login"' + disabled + ">" +
         (busy ? "登录中…" : "登录") + "</button>";
     }
+    // 诊断按钮始终显示，便于随时自查真实健康状态。
+    html += '<button class="wb-btn wb-diagnose" id="wb-diagnose" title="一键诊断">🔍</button>';
     if (!status.proxyUp) html += '<span class="wb-warn">代理未运行</span>';
     html += "</div>";
     host.innerHTML = html;
     var btn = host.querySelector("#wb-login");
     if (btn) btn.addEventListener("click", onLogin);
+    var dg = host.querySelector("#wb-diagnose");
+    if (dg) dg.addEventListener("click", onDiagnose);
   }
 
   function refresh() {
@@ -151,6 +155,63 @@ function runWidget() {
       });
   }
 
+  /** 一键诊断：真实探测代理健康，必要时给出可复制的重启命令。 */
+  function onDiagnose() {
+    var panel = document.getElementById("wb-diagnose-panel");
+    if (panel) { panel.remove(); return; }
+    var el = document.createElement("div");
+    el.id = "wb-diagnose-panel";
+    el.style.cssText =
+      "position:fixed;right:12px;bottom:44px;z-index:2147483647;width:340px;max-height:340px;overflow:auto;" +
+      "background:#0f172a;color:#e2e8f0;border:1px solid #334155;border-radius:8px;" +
+      "padding:10px;font:12px/1.5 system-ui,sans-serif;box-shadow:0 6px 20px rgba(0,0,0,.5);";
+    el.innerHTML = '<div class="wb-dg-title" style="font-weight:700;margin-bottom:6px">WorkBuddy 诊断中…</div>' +
+      '<div class="wb-dg-body" style="white-space:pre-wrap;word-break:break-word;color:#94a3b8">正在探测…</div>';
+    document.body.appendChild(el);
+
+    fetch("/api/workbuddy/diagnose", { method: "POST" })
+      .then(function (r) { return r.json(); })
+      .then(function (d) {
+        if (!d) throw new Error("空响应");
+        var title = d.ok ? "✅ 一切正常" : "⚠️ 发现问题";
+        var lines = [];
+        lines.push("登录状态: " + (d.session && d.session.authenticated ? "有效" : "无效"));
+        lines.push("会话文件: " + (d.session && d.session.file ? "存在" : "缺失"));
+        lines.push("代理进程: " + (d.health && d.health.proxyUp ? "在运行" : "未运行"));
+        lines.push("登录令牌: " + (d.health && d.health.tokenValid ? "有效" : "无效"));
+        lines.push("模型出字: " + (d.chat && d.chat.chatWorking ? "正常" : "失败"));
+        if (d.chat && d.chat.chatError) lines.push("出字错误: " + d.chat.chatError);
+        var html = '<div class="wb-dg-title" style="font-weight:700;margin-bottom:6px">' + title + '</div>' +
+          '<div class="wb-dg-body" style="white-space:pre-wrap;word-break:break-word">' + lines.map(esc).join("\n") + "</div>";
+        if (!d.ok && d.restartCommand) {
+          html += '<div style="margin-top:8px;font-weight:700">重启命令（复制到终端执行）：</div>' +
+            '<pre style="background:#1e293b;border-radius:6px;padding:8px;font-size:11px;overflow:auto;white-space:pre-wrap">' +
+            esc(d.restartCommand) + "</pre>" +
+            '<button class="wb-btn" id="wb-copy-cmd">复制重启命令</button>';
+        }
+        el.innerHTML = html;
+        var copy = document.getElementById("wb-copy-cmd");
+        if (copy) {
+          copy.addEventListener("click", function () {
+            navigator.clipboard.writeText(d.restartCommand).then(function () {
+              copy.textContent = "已复制 ✓";
+              setTimeout(function () { copy.textContent = "复制重启命令"; }, 1500);
+            });
+          });
+        }
+      })
+      .catch(function (err) {
+        el.innerHTML = '<div class="wb-dg-title" style="font-weight:700;color:#f87171">诊断失败</div>' +
+          '<div class="wb-dg-body">' + esc(String(err && err.message || err)) + "</div>";
+      });
+  }
+
+  function esc(s) {
+    return String(s == null ? "" : s).replace(/[&<>"']/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c];
+    });
+  }
+
   refresh();
   timer = setInterval(refresh, POLL_MS);
 }

package/lib/index.js

@@ -762,84 +762,192 @@ async function probeProxy(baseURL) {
 }
 
 /**
- * Register `GET /api/workbuddy/status` and `POST /api/workbuddy/login` on the
- * DSH web server. The login route spawns `login_workbuddy.py`, parses the
- * device-flow `authUrl` it prints to stdout, and returns it so the browser
- * can open it in a new tab. The widget then polls `/status` until the session
- * file appears and reports `authenticated: true`.
+ * Probe whether the proxy can actually complete a chat completion, not just
+ * answer `/health`. `/health` reflects the proxy process alone — it stays
+ * `authenticated: true` even when the process points at a deleted/old path
+ * and every model request fails with `[Errno 2] No such file or directory`.
+ * Sending one minimal request is the only probe that catches that class of
+ * "capsule shows green but models are all down" false positive.
+ * @returns `{ chatWorking, chatError? }` where `chatWorking` is true only
+ * when the proxy returned a non-streamed completion.
+ */
+async function probeChatWorking(baseURL) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15000);
+  try {
+    const endpoint = `${baseURL.replace(/\/v1\/?$/, "")}/v1/chat/completions`;
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        model: "hy3",
+        messages: [{ role: "user", content: "ping" }],
+        max_tokens: 4,
+        stream: false,
+      }),
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      return { chatWorking: false, chatError: `HTTP ${response.status}${text ? `: ${text.slice(0, 200)}` : ""}` };
+    }
+    const body = await response.json().catch(() => null);
+    const content = body?.choices?.[0]?.message?.content;
+    if (typeof content === "string" && content.length > 0) {
+      return { chatWorking: true };
+    }
+    return { chatWorking: false, chatError: "代理返回了空响应" };
+  } catch (error) {
+    return { chatWorking: false, chatError: String(error?.message ?? error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The restart command shown by the diagnose route. It adapts to two layouts:
+ * - Local monorepo dev: the plugin sits inside a `dsh-workbuddy/` checkout with
+ *   `start-workbuddy.sh` two levels up — use the workspace-local script.
+ * - Standard install (any other machine): no `start-workbuddy.sh`, so show the
+ *   upstream README command for running the workbuddy2api proxy via uv.
+ */
+function diagnoseRestartCommand() {
+  const workspaceRoot = resolve(PLUGIN_DIR, "..", "..");
+  const localScript = resolve(workspaceRoot, "start-workbuddy.sh");
+  if (existsSync(localScript)) {
+    return [
+      "# 检测到本机 monorepo 布局（dsh-workbuddy/），用仓库脚本重启代理",
+      "# 停掉旧代理（若 8787 被占用）",
+      "lsof -tiTCP:8787 -sTCP:LISTEN | xargs kill",
+      "",
+      "# 重启代理（脚本路径自动定位到本仓库）",
+      `cd ${workspaceRoot} && ./start-workbuddy.sh`,
+    ].join("\n");
+  }
+  return [
+    "# 用 workbuddy2api 代理（标准安装）重启：",
+    "# 停掉旧代理（若 8787 被占用）",
+    "lsof -tiTCP:8787 -sTCP:LISTEN | xargs kill",
+    "",
+    "# 拉取并运行代理（详见 README「安装代理」）",
+    "git clone https://github.com/hawklithm/workbuddy2api.git && cd workbuddy2api",
+    "uv run python -u -m codebuddy_proxy --desensitize \\",
+    "  --session-file ~/.codebuddy-session.json --log-file ~/.codebuddy-proxy.jsonl",
+  ].join("\n");
+}
+
+/**
+ * Register `GET /api/workbuddy/status`, `POST /api/workbuddy/login`, and
+ * `POST /api/workbuddy/diagnose` on the DSH web server. The login route spawns
+ * `login_workbuddy.py`, parses the device-flow `authUrl` it prints to stdout,
+ * and returns it so the browser can open it in a new tab. The widget then
+ * polls `/status` until the session file appears and reports
+ * `authenticated: true`.
  */
 function registerWorkbuddyRoutes(ctx, config) {
-  // Probe the optional webServer service. In a headless profile it is absent
-  // and we skip the HTTP surface entirely — the adapter (registered in apply)
-  // still works. Because `webServer` is not in `inject`, this must be a
-  // runtime probe, not a dereference.
-  const webServer = ctx.get("webServer");
-  if (webServer === undefined) return;
-  const baseURL = config_baseURL();
-  const { sessionFile, loginScript } = resolveLoginPaths(config);
-  // The register() call returns a disposer. Wrapping it in ctx.effect ties it
-  // to the plugin fiber so config hot-edit / reload cleans the routes up
-  // instead of leaking them (a leaked route makes a duplicate re-register
-  // throw). Method filtering must be done inside the handler — the route API
-  // only accepts `{ kind, path, handler }`.
-  ctx.effect(() => webServer.register({
-    kind: "exact",
-    path: "/api/workbuddy/status",
-    async handler(req, res) {
-      if (req.method !== "GET") {
-        res.writeHead(405, { "content-type": "application/json" });
-        res.end(JSON.stringify({ error: "method not allowed" }));
-        return;
-      }
-      const session = readSessionStatus(sessionFile);
-      const proxy = await probeProxy(baseURL);
-      res.writeHead(200, { "content-type": "application/json" });
-      res.end(JSON.stringify({
-        ...session,
-        ...proxy,
-        loginScriptAvailable: existsSync(loginScript),
-      }));
-    },
-  }));
-  ctx.effect(() => webServer.register({
-    kind: "exact",
-    path: "/api/workbuddy/login",
-    async handler(req, res) {
-      if (req.method !== "POST") {
-        res.writeHead(405, { "content-type": "application/json" });
-        res.end(JSON.stringify({ error: "method not allowed" }));
-        return;
-      }
-      if (!existsSync(loginScript)) {
-        res.writeHead(503, { "content-type": "application/json" });
-        res.end(JSON.stringify({ error: "login_workbuddy.py not found" }));
-        return;
-      }
-      // Existing session is fine; no need to re-run the flow.
-      const existing = readSessionStatus(sessionFile);
-      if (existing.authenticated) {
+  // Delay registration until the webServer service exists. The plugin keeps
+  // `webServer` OUT of `inject` so headless profiles (no HTTP surface) still
+  // load — but a synchronous `ctx.get("webServer")` probe at apply time races
+  // the webserver plugin's own mount and can observe the service before it is
+  // provided, silently dropping the routes. `ctx.inject` runs this callback
+  // only once webServer is available, and skips it entirely when the service
+  // never appears (headless), preserving the original intent.
+  ctx.inject(["webServer"], (webCtx) => {
+    const webServer = webCtx.webServer;
+    const baseURL = config_baseURL();
+    const { sessionFile, loginScript } = resolveLoginPaths(config);
+    // The register() call returns a disposer. Wrapping it in ctx.effect ties
+    // it to the plugin fiber so config hot-edit / reload cleans the routes up
+    // instead of leaking them (a leaked route makes a duplicate re-register
+    // throw). Method filtering must be done inside the handler — the route API
+    // only accepts `{ kind, path, handler }`.
+    webCtx.effect(() => webServer.register({
+      kind: "exact",
+      path: "/api/workbuddy/status",
+      async handler(req, res) {
+        if (req.method !== "GET") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "method not allowed" }));
+          return;
+        }
+        const session = readSessionStatus(sessionFile);
+        const proxy = await probeProxy(baseURL);
         res.writeHead(200, { "content-type": "application/json" });
-        res.end(JSON.stringify({ alreadyLoggedIn: true, authUrl: null, ...existing }));
-        return;
-      }
-      // login_workbuddy.py is dependency-free (stdlib only), so we invoke it
-      // directly with the system Python — no uv runtime required.
-      const args = ["-u", loginScript, "--session-file", sessionFile];
-      const child = spawn("python3", args, { env: { ...process.env, PYTHONUNBUFFERED: "1" } });
-      let stdout = "";
-      let authUrl = null;
-      child.stdout.on("data", (chunk) => {
-        stdout += chunk.toString();
-        const m = stdout.match(/https?:\/\/\S+/);
-        if (m && authUrl === null) authUrl = m[0];
-      });
-      child.stderr.on("data", () => {});
-      // The device flow blocks until login or timeout; we hand back the URL
-      // immediately and let the widget poll /status for completion.
-      res.writeHead(200, { "content-type": "application/json" });
-      res.end(JSON.stringify({ authUrl, pending: true }));
-    },
-  }));
+        res.end(JSON.stringify({
+          ...session,
+          ...proxy,
+          loginScriptAvailable: existsSync(loginScript),
+        }));
+      },
+    }));
+    webCtx.effect(() => webServer.register({
+      kind: "exact",
+      path: "/api/workbuddy/login",
+      async handler(req, res) {
+        if (req.method !== "POST") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "method not allowed" }));
+          return;
+        }
+        if (!existsSync(loginScript)) {
+          res.writeHead(503, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "login_workbuddy.py not found" }));
+          return;
+        }
+        // Existing session is fine; no need to re-run the flow.
+        const existing = readSessionStatus(sessionFile);
+        if (existing.authenticated) {
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify({ alreadyLoggedIn: true, authUrl: null, ...existing }));
+          return;
+        }
+        // login_workbuddy.py is dependency-free (stdlib only), so we invoke it
+        // directly with the system Python — no uv runtime required.
+        const args = ["-u", loginScript, "--session-file", sessionFile];
+        const child = spawn("python3", args, { env: { ...process.env, PYTHONUNBUFFERED: "1" } });
+        let stdout = "";
+        let authUrl = null;
+        child.stdout.on("data", (chunk) => {
+          stdout += chunk.toString();
+          const m = stdout.match(/https?:\/\/\S+/);
+          if (m && authUrl === null) authUrl = m[0];
+        });
+        child.stderr.on("data", () => {});
+        // The device flow blocks until login or timeout; we hand back the URL
+        // immediately and let the widget poll /status for completion.
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ authUrl, pending: true }));
+      },
+    }));
+    webCtx.effect(() => webServer.register({
+      kind: "exact",
+      path: "/api/workbuddy/diagnose",
+      async handler(req, res) {
+        if (req.method !== "POST") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "method not allowed" }));
+          return;
+        }
+        // Real health: probe /health AND actually complete a chat. /health
+        // alone stays green even when the proxy points at a deleted path and
+        // every model request 500s — the exact "capsule green but models dead"
+        // false positive the diagnose button exists to surface.
+        const session = readSessionStatus(sessionFile);
+        const health = await probeProxy(baseURL);
+        const chat = await probeChatWorking(baseURL);
+        const ok = Boolean(health.proxyUp && health.tokenValid && session.authenticated && chat.chatWorking);
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({
+          ok,
+          session: { file: session.sessionFile, authenticated: session.authenticated, expiresAt: session.expiresAt },
+          health,
+          chat,
+          loginScriptAvailable: existsSync(loginScript),
+          restartCommand: ok ? null : diagnoseRestartCommand(),
+        }));
+      },
+    }));
+  });
 }
 
 /** Lazily resolve the configured proxy base URL for the health probe. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-llm-workbuddy",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "WorkBuddy (via the local workbuddy2api proxy) LLM provider adapter for DeepSeek Harness, with a Web login-status widget",
   "type": "module",
   "main": "lib/index.js",