chore: v2.8.18 — pasted file-manager copies attach by path locally, copy/IME/stale-reply fixes, react-router 7, full OpenAPI

fix(chat): a file-manager copy pasted on a local browser attaches by its own path
Chrome gives a PASTE of a file manager's copy (Ctrl+C in Nautilus, Ctrl+V in the chat) the files and their paths as plain text, but no text/uri-list — only a drag carries that — so localCandidates found no path and every such file was uploaded, and refused past the upload limit. Plain-text paths (or file:// lines) whose names match the pasted files one for one are now candidates too; sameFilesHere still has the server confirm each is the same file (size) on this machine, so server mode and remote browsers upload as before. The prompt box also attaches a file:// text paste with no file by path, as the terminal already did (copiedFilePaths moved to promptAttach).
2026-10-22 13:58:46 +07:00 · 2026-10-22 13:47:17 +07:00 · 2026-10-22 12:17:18 +07:00 · 2026-10-22 12:17:18 +07:00
52 changed files with 8641 additions and 1665 deletions
@@ -1,6 +1,6 @@
 # Claude Code Working Guide

-_Last synced: v2.8.17 (2026-10-22) — every AI tool's login profiles (Claude, Codex, Oh My Pi) in one Settings → AI tools → Profiles section, linked to the account pool._ A change that makes any statement in this file, `AGENTS.md`, or a README wrong — a moved path, a new or changed extension point, a retired rule — updates that file in the same change-set and bumps this marker. **Bump = replace the version/date and a ≤ 1-line summary; never append a changelog here** — details belong in the commit message and `docs/`, because this whole file is loaded into every session.
+_Last synced: v2.8.18 (2026-10-22) — a pasted file-manager copy attaches by path on a local browser; OpenAPI covers every route; config writes same-origin._ A change that makes any statement in this file, `AGENTS.md`, or a README wrong — a moved path, a new or changed extension point, a retired rule — updates that file in the same change-set and bumps this marker. **Bump = replace the version/date and a ≤ 1-line summary; never append a changelog here** — details belong in the commit message and `docs/`, because this whole file is loaded into every session.

 ## Project mission
 - Maintain a reliable local-first dashboard for Claude Code session monitoring.
@@ -2845,12 +2845,12 @@ const COMMAND_GROUPS = [
      ],
      [
        "server",
-        "setup|off|status [--hostname name] [--admin name]",
+        "setup|install-system|tools|off|status [--hostname name] [--admin name]",
        "Server mode: logins for a shared dashboard (docs/SERVER-MODE.md)",
      ],
      [
        "users",
-        "list|add|passwd|role|disable|enable|assign|audit [name]",
+        "list|add|passwd|role|disable|enable|provision|assign|audit [name]",
        "Server mode's accounts (add: --role admin|analyst|developer)",
      ],
      [
@@ -3812,8 +3812,8 @@ const COMMANDS = (() => {
 const SUBCOMMANDS = {
  alerts: ["ack", "ack-all"],
  service: ["install", "uninstall", "status"],
-  server: ["setup", "off", "status"],
-  users: ["list", "add", "passwd", "role", "disable", "enable", "assign", "audit"],
+  server: ["setup", "install-system", "tools", "off", "status"],
+  users: ["list", "add", "passwd", "role", "disable", "enable", "provision", "assign", "audit"],
  accounts: ["list", "add", "remove", "pin", "unpin"],
  pricing: ["set", "delete", "reset"],
  webhooks: ["test"],
@@ -3905,7 +3905,7 @@ async function newPassword(label) {
  return first;
 }

-/** `agenthub server setup|off|status` — turn server mode on or off. */
+/** `agenthub server setup|install-system|tools|off|status` — turn server mode on or off. */
 async function cmdServer(sub, flags) {
  const { settingsEnv, auth } = serverAuth();
  const file = settingsEnv.settingsFilePath();
@@ -4062,7 +4062,7 @@ async function installSystem(flags, settingsEnv) {
    throw new Error("run this as the account that runs the dashboard, not as root (it uses sudo)");
  }
  const which = (bin) =>
-    spawnSync("sh", ["-c", `command -v ${bin}`], { encoding: "utf8" }).stdout.trim();
+    spawnSync("sh", ["-c", 'command -v "$1"', "sh", bin], { encoding: "utf8" }).stdout.trim();
  const host = os.userInfo().username;
  const { getDataDir } = require(path.join(REPO_ROOT, "server", "lib", "claude-home.js"));
  const data = getDataDir();
@@ -29,7 +29,7 @@
        "react-dom": "^18.3.1",
        "react-i18next": "^17.0.4",
        "react-markdown": "^10.1.0",
-        "react-router-dom": "^6.28.2",
+        "react-router-dom": "^7.18.4",
        "remark-gfm": "^4.0.1"
      },
      "devDependencies": {
@@ -1251,15 +1251,6 @@
        "node": ">= 8"
      }
    },
-    "node_modules/@remix-run/router": {
-      "version": "1.23.4",
-      "resolved": "https://registry.npmjs.org/@remix-run/router/-/router-1.23.4.tgz",
-      "integrity": "sha512-q7j5geK7xs3UJSdm9/iytUNclBnLmYx1EnSeCFXHPeutdqgIMeFeHtUZgS3EhlKxdBEAu8OwtJCwmLrEzpSs7Q==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=14.0.0"
-      }
-    },
    "node_modules/@rolldown/pluginutils": {
      "version": "1.0.0-beta.27",
      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz",
@@ -2740,6 +2731,18 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/cookie": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz",
+      "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
    "node_modules/crelt": {
      "version": "1.0.7",
      "resolved": "https://registry.npmjs.org/crelt/-/crelt-1.0.7.tgz",
@@ -5472,35 +5475,39 @@
      }
    },
    "node_modules/react-router": {
-      "version": "6.30.6",
-      "resolved": "https://registry.npmjs.org/react-router/-/react-router-6.30.6.tgz",
-      "integrity": "sha512-5HfK7k5im7LTOB0EqCQmfvy4C13G92Ssj1VTmouTK3AJvyjKTnFuCV0vcMAD/JS+JC4DvDIBRrlAeJIFjh5VWg==",
-      "license": "MIT",
+      "version": "7.18.4",
+      "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.18.4.tgz",
+      "integrity": "sha512-PUPQcMhMGRAslLcvtlPz/kmzBEWPhLdgLFrL7pLNepBL6dX0lWj4WD2cUYVgYCuT3jxvghYFg81cDTj44DhetQ==",
      "dependencies": {
-        "@remix-run/router": "1.23.4"
+        "cookie": "^1.0.1",
+        "set-cookie-parser": "^2.6.0"
      },
      "engines": {
-        "node": ">=14.0.0"
+        "node": ">=20.0.0"
      },
      "peerDependencies": {
-        "react": ">=16.8"
+        "react": ">=18",
+        "react-dom": ">=18"
+      },
+      "peerDependenciesMeta": {
+        "react-dom": {
+          "optional": true
+        }
      }
    },
    "node_modules/react-router-dom": {
-      "version": "6.30.6",
-      "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-6.30.6.tgz",
-      "integrity": "sha512-0RHKZz7wwffvkU+2MFVT2NnjK44ssLEV+m0CAJaS2Ksmorrwj7WxH00jO0SOCW26/tINUnJHToXblDs33I38YQ==",
-      "license": "MIT",
+      "version": "7.18.4",
+      "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-7.18.4.tgz",
+      "integrity": "sha512-yrfmJHIpDG7taCpqKjT1G5B6q3O2K+RN8/fgNf0lTjCwiPbQ0ei6vXX9ZjQR+7ld8Tr7Z5xmyMnZ8YJrphWQUw==",
      "dependencies": {
-        "@remix-run/router": "1.23.4",
-        "react-router": "6.30.6"
+        "react-router": "7.18.4"
      },
      "engines": {
-        "node": ">=14.0.0"
+        "node": ">=20.0.0"
      },
      "peerDependencies": {
-        "react": ">=16.8",
-        "react-dom": ">=16.8"
+        "react": ">=18",
+        "react-dom": ">=18"
      }
    },
    "node_modules/read-cache": {
@@ -5766,6 +5773,11 @@
        "semver": "bin/semver.js"
      }
    },
+    "node_modules/set-cookie-parser": {
+      "version": "2.7.2",
+      "resolved": "https://registry.npmjs.org/set-cookie-parser/-/set-cookie-parser-2.7.2.tgz",
+      "integrity": "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw=="
+    },
    "node_modules/siginfo": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
@@ -32,7 +32,7 @@
    "react-dom": "^18.3.1",
    "react-i18next": "^17.0.4",
    "react-markdown": "^10.1.0",
-    "react-router-dom": "^6.28.2",
+    "react-router-dom": "^7.18.4",
    "remark-gfm": "^4.0.1"
  },
  "devDependencies": {
@@ -4,12 +4,14 @@
 * Escape closes it. Rendered into `document.body`, so no pane, its stacking
 * layer or a header drawn over a pane can cover it — opened from inside a
 * pane's Chat view, a `fixed` overlay would otherwise stay in that pane's
- * layer, under anything stacked above it.
+ * layer, under anything stacked above it. `useDialog` takes the focus while it
+ * is open and gives it back, and its Escape closes only this, the top dialog.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

-import { useEffect } from "react";
+import { useRef } from "react";
 import { createPortal } from "react-dom";
+import { useDialog } from "../hooks/useDialog";

 export function ImageLightbox({
  src,
@@ -20,18 +22,18 @@ export function ImageLightbox({
  alt: string;
  onClose: () => void;
 }) {
-  useEffect(() => {
-    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
-    document.addEventListener("keydown", onKey);
-    return () => document.removeEventListener("keydown", onKey);
-  }, [onClose]);
+  const panel = useRef<HTMLDivElement>(null);
+  useDialog(true, panel, onClose);
  return createPortal(
    <div
+      ref={panel}
+      tabIndex={-1}
      role="dialog"
+      aria-modal="true"
      aria-label={alt}
      data-testid="image-lightbox"
      onClick={onClose}
-      className="fixed inset-0 z-[200] flex cursor-zoom-out items-center justify-center bg-black/60 p-8"
+      className="fixed inset-0 z-[200] flex cursor-zoom-out items-center justify-center bg-black/60 p-8 outline-none"
    >
      <img
        src={src}
@@ -82,6 +82,7 @@ import { api, type ImportResult, type ImportBackupResult } from "../lib/api";
 import { eventBus } from "../lib/eventBus";
 import type { WSMessage, ImportProgressMessage } from "../lib/types";
 import { PathPickButton } from "./PathPickButton";
+import { copyText } from "../lib/clipboard";

 type Mode = "rescan" | "path" | "upload" | "backup";

@@ -247,13 +248,9 @@ export function ImportHistory() {

  const copyArchiveCmd = async () => {
    if (!guide) return;
-    try {
-      await navigator.clipboard.writeText(guide.archive_command);
-      setCopied(true);
-      setTimeout(() => setCopied(false), 1500);
-    } catch {
-      /* clipboard unavailable */
-    }
+    if (!(await copyText(guide.archive_command, true))) return;
+    setCopied(true);
+    setTimeout(() => setCopied(false), 1500);
  };

  const progressText = (() => {
@@ -88,6 +88,7 @@ import { isRemoteDataRefreshMessage } from "../lib/remoteDataEvents";
 import { useDataScope } from "../lib/dataScope";
 import type { ScopeMode } from "../lib/dataScope";
 import { PathPickButton } from "./PathPickButton";
+import { copyText } from "../lib/clipboard";

 /** Data-scope choices in display order (the radio group's arrow-key order). */
 const SCOPE_MODES: ScopeMode[] = ["all", "local", "selected"];
@@ -863,7 +864,7 @@ export function RemoteSources() {
                  : t("remoteSources.enable", "Enable")}
              </MenuItem>
              <MenuItem onSelect={pick(openEdit)}>{t("common:edit", "Edit")}</MenuItem>
-              <MenuItem onSelect={pick((s) => void navigator.clipboard.writeText(s.host))}>
+              <MenuItem onSelect={pick((s) => void copyText(s.host))}>
                {t("rowMenu.copyHost")}
              </MenuItem>
              <MenuSeparator />
@@ -24,6 +24,7 @@ import {
 import { useTranslation } from "react-i18next";
 import { subjectLabel, type AttentionItem, type SagiStatus, type SagiSubject } from "./brain";
 import { PET_NAME_MAX } from "./prefs";
+import { isSubmitEnter } from "../../lib/keys";

 /** How many sessions the "Needs you" list shows before pointing at Sessions. */
 const ATTENTION_SHOWN = 4;
@@ -70,7 +71,7 @@ export function PetNameButton({
      onChange={(e) => setRenaming(e.target.value)}
      onBlur={save}
      onKeyDown={(e) => {
-        if (e.key === "Enter") {
+        if (isSubmitEnter(e)) {
          e.preventDefault();
          save();
        } else if (e.key === "Escape") {
@@ -14,6 +14,7 @@ import { api } from "../lib/api";
 import { ConfirmModal } from "./ConfirmModal";
 import { Checkbox } from "./Checkbox";
 import { CopyButton } from "./event-views/primitives";
+import { copyText } from "../lib/clipboard";

 export function snapshotUrl(token: string): string {
  return `${window.location.origin}/snapshot/${token}`;
@@ -33,7 +34,7 @@ export function SnapshotButton({ sessionId }: { sessionId: string }) {
    try {
      const { snapshot } = await api.snapshots.create(sessionId, { filePaths: redact });
      setToken(snapshot.token);
-      navigator.clipboard?.writeText(snapshotUrl(snapshot.token)).catch(() => undefined);
+      void copyText(snapshotUrl(snapshot.token));
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
    } finally {
@@ -238,7 +238,7 @@ describe("StatusBar", () => {
    expect(work).toHaveTextContent("5h95%Resets in 41m");
    expect(work).toHaveTextContent("Week32%");
    expect(personal).toHaveTextContent("home@example.com · Sign-in expired");
-    expect(personal).toHaveTextContent("Check quota in Claude Code → Profiles");
+    expect(personal).toHaveTextContent("Check quota in Settings → AI tools → Profiles");
    expect(personal).not.toHaveTextContent("in use");
    expect(codex).toHaveTextContent("dev@example.com");
    expect(codex).toHaveTextContent("Sign-in expired");
@@ -103,6 +103,7 @@
 import { useState } from "react";
 import { useTranslation } from "react-i18next";
 import { Copy, Check } from "lucide-react";
+import { copyText } from "../../lib/clipboard";

 // ───────────────────────── Copy button ─────────────────────────

@@ -111,13 +112,9 @@ export function CopyButton({ text }: { text: string }) {
  const [copied, setCopied] = useState(false);

  async function copy() {
-    try {
-      await navigator.clipboard.writeText(text);
-      setCopied(true);
-      setTimeout(() => setCopied(false), 1500);
-    } catch {
-      // Clipboard API can fail in insecure contexts - silently ignore.
-    }
+    if (!(await copyText(text, true))) return;
+    setCopied(true);
+    setTimeout(() => setCopied(false), 1500);
  }

  return (
@@ -92,6 +92,7 @@ import { formatBytes } from "../../lib/format";
 import { copyText } from "../../lib/clipboard";
 import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "../ContextMenu";
 import { CloneHereDialog } from "./CloneHereDialog";
+import { isSubmitEnter } from "../../lib/keys";

 /** One upload batch at most (the server caps one file the same). */
 export const FX_BATCH_MAX_BYTES = 500 * 1024 * 1024;
@@ -1987,7 +1988,7 @@ function InlineName({
      onDoubleClick={(e) => e.stopPropagation()}
      onKeyDown={(e) => {
        e.stopPropagation();
-        if (e.key === "Enter") onDone();
+        if (isSubmitEnter(e)) onDone();
        if (e.key === "Escape") onCancel();
      }}
      onBlur={onDone}
@@ -1063,6 +1063,9 @@ export function LaneChangesPanel({
  const [historyLoading, setHistoryLoading] = useState(false);
  useEffect(() => {
    if (mode !== "history") return;
+    // A reply for the previous ref/file/page lands after the next request
+    // started: drop it, or it overwrites the list the user is looking at.
+    let live = true;
    setHistoryLoading(true);
    void api.lanes
      .gitLog(target, {
@@ -1070,16 +1073,23 @@ export function LaneChangesPanel({
        ...(historyRef ? { ref: historyRef } : {}),
        ...(historyFile ? { file: historyFile } : {}),
      })
-      .then(forLane(laneId, (r) => setCommits(r.commits)))
-      .catch((err) => setError(err instanceof Error ? err.message : String(err)))
-      .finally(() => laneNow.current === laneId && setHistoryLoading(false));
+      .then(forLane(laneId, (r) => live && setCommits(r.commits)))
+      .catch((err) => live && setError(err instanceof Error ? err.message : String(err)))
+      .finally(() => live && laneNow.current === laneId && setHistoryLoading(false));
+    return () => {
+      live = false;
+    };
  }, [mode, laneId, reread, historyLimit, historyRef, historyFile]);
  useEffect(() => {
    if (mode !== "history") return;
+    let live = true;
    void api.lanes
      .gitBranches(target)
-      .then(forLane(laneId, (r) => setHistoryBranches(r.branches)))
-      .catch(() => setHistoryBranches([]));
+      .then(forLane(laneId, (r) => live && setHistoryBranches(r.branches)))
+      .catch(() => live && setHistoryBranches([]));
+    return () => {
+      live = false;
+    };
  }, [mode, laneId, reread]);

  // Re-run when a lane switch empties the cache too: the full-width sidebar
@@ -1173,24 +1183,33 @@ export function LaneChangesPanel({
  // own fetch — and only while the viewer is actually showing it.
  useEffect(() => {
    if (mode !== "file" || !(whole || editable) || !openFile) return;
+    // Opening file B before file A's read came back must not show (and let the
+    // editor save) A's text under B's header.
+    let live = true;
    void api.lanes
      .gitFile(target, openFile, range === "commit" && sha ? sha : "work")
      .then(
-        forLane(laneId, (r) =>
-          setText(
-            r.available
-              ? {
-                  path: r.path,
-                  lines: r.lines,
-                  truncated: r.truncated,
-                  binary: r.binary,
-                  sha: r.sha,
-                }
-              : null
-          )
+        forLane(
+          laneId,
+          (r) =>
+            live &&
+            setText(
+              r.available
+                ? {
+                    path: r.path,
+                    lines: r.lines,
+                    truncated: r.truncated,
+                    binary: r.binary,
+                    sha: r.sha,
+                  }
+                : null
+            )
        )
      )
-      .catch((err) => setError(err instanceof Error ? err.message : String(err)));
+      .catch((err) => live && setError(err instanceof Error ? err.message : String(err)));
+    return () => {
+      live = false;
+    };
  }, [mode, whole, editable, openFile, laneId, range, sha]);
  // The editor's original side, read beside the working file. A file that is
  // not there (new since) diffs against nothing: every line is added.
@@ -1198,10 +1217,17 @@ export function LaneChangesPanel({
  useEffect(() => {
    if (mode !== "file" || !(whole || editable) || !openFile || range === "commit") return;
    const rev = range === "branch" && mergeBase ? mergeBase : "HEAD";
+    let live = true;
    void api.lanes.gitFile(target, openFile, rev).then(
-      forLane(laneId, (r) => setBaseText(r.available && !r.binary ? r.lines.join("\n") : "")),
-      forLane(laneId, () => setBaseText(""))
+      forLane(
+        laneId,
+        (r) => live && setBaseText(r.available && !r.binary ? r.lines.join("\n") : "")
+      ),
+      forLane(laneId, () => live && setBaseText(""))
    );
+    return () => {
+      live = false;
+    };
  }, [mode, whole, editable, openFile, laneId, range, mergeBase]);

  useEffect(() => {
@@ -70,6 +70,7 @@ import {
  ATTACH_MIME,
  addAttachments,
  claudeMention,
+  copiedFilePaths,
  droppedAttachments,
  droppedSkill,
  droppedText,
@@ -452,6 +453,14 @@ export function PromptEditor({
    });
    return true;
  };
+  /** A file manager's copy pasted with no file beside it, only `file://`
+   *  text: attached by those paths, as the terminal pastes them. */
+  const pastedLocalFiles = (dt: DataTransfer | null | undefined) => {
+    const paths = isLocalBrowser() ? copiedFilePaths(dt) : null;
+    if (!paths) return false;
+    onImagesChange((prev) => addAttachments(prev, paths.map(localAttachment)));
+    return true;
+  };
  /** Dropped or pasted files: by their own paths when the browser is on the
   *  dashboard's machine and the server finds the same files there (a file
   *  manager hands over `file://` paths beside the bytes), else uploaded. */
@@ -675,6 +684,7 @@ export function PromptEditor({
          onKeyDown={handleKeyDown}
          onPaste={(e) => {
            if (attachDropped(e.clipboardData, e.clipboardData?.files)) e.preventDefault();
+            else if (pastedLocalFiles(e.clipboardData)) e.preventDefault();
            else {
              // A very long paste goes in as a text file, like Claude Desktop:
              // the prompt then carries its path, never the text (#68: a CLI's
@@ -863,7 +873,7 @@ export function CwdAutocomplete({
    } else if (e.key === "ArrowUp") {
      e.preventDefault();
      setActive((a) => Math.max(0, a - 1));
-    } else if (e.key === "Enter") {
+    } else if (isSubmitEnter(e)) {
      if (open && flat[active]) {
        e.preventDefault();
        choose(flat[active]);
@@ -65,14 +65,10 @@ import { useTheme } from "../../hooks/useTheme";
 import { terminalThemeFor } from "../../lib/terminalTheme";
 import { api } from "../../lib/api";
 import { writeClipboard } from "../../lib/clipboard";
-import {
-  MENU_CURSOR_ROW,
-  notePaneFocus,
-  notePaneOutput,
-  registerPane,
-} from "../../lib/panePaste";
+import { MENU_CURSOR_ROW, notePaneFocus, notePaneOutput, registerPane } from "../../lib/panePaste";
 import {
  claudePastes,
+  copiedFilePaths,
  droppedFilePaths,
  isLocalBrowser,
  localCandidates,
@@ -160,15 +156,6 @@ const hasFiles = (e: DragEvent) => Array.from(e.dataTransfer.types).includes("Fi
 const hasText = (e: DragEvent) =>
  !hasFiles(e) && Array.from(e.dataTransfer.types).includes("text/plain");

-/** The `file://` paths a paste carries as text — a file manager's copy — or
- *  null: its uri-list, else its plain text when every line is one. */
-function copiedFilePaths(dt: DataTransfer | null): string[] | null {
-  const text = dt?.getData("text/plain") ?? "";
-  if (droppedFilePaths(dt)) return droppedFilePaths(dt);
-  if (!/^file:\/\//.test(text.trim())) return null;
-  return droppedFilePaths({ getData: () => text } as unknown as DataTransfer);
-}
-
 interface TerminalViewProps {
  runId: string;
  wsBaseUrl: string;
@@ -31,6 +31,7 @@ import { formatDateTime } from "../../lib/format";
 import { toast } from "../../lib/toast";
 import { confirmDialog } from "../../lib/confirm";
 import { isSubmitEnter } from "../../lib/keys";
+import { useSpin } from "../../hooks/useSpin";
 import { useAuth } from "../AuthGate";
 import { ROLE_BADGE } from "../users/UserEditDialog";
 import { UserAvatar } from "../users/UserAvatar";
@@ -68,19 +69,23 @@ export function AccountSettings() {
  );
  const load = useCallback(() => {
    setLoadError(null);
-    api.me
+    return api.me
      .account()
      .then(apply)
      .catch((e: Error) => setLoadError(e.message));
  }, [apply]);
-  useEffect(load, [load]);
+  useEffect(() => {
+    void load();
+  }, [load]);
+  const [retrying, retry] = useSpin(load);

  if (loadError) {
    return (
      <div role="alert" className="card flex items-center gap-3 p-4 text-sm text-status-danger">
        <span className="flex-1">{t("account.loadFailed", { message: loadError })}</span>
-        <button type="button" className="btn-ghost text-xs" onClick={load}>
-          <RefreshCw className="h-3.5 w-3.5" /> {t("common:retry")}
+        <button type="button" className="btn-ghost text-xs" onClick={retry} disabled={retrying}>
+          <RefreshCw className={`h-3.5 w-3.5${retrying ? " animate-spin" : ""}`} />{" "}
+          {t("common:retry")}
        </button>
      </div>
    );
@@ -17,6 +17,7 @@ import { FileUp } from "lucide-react";
 import { useTranslation } from "react-i18next";
 import { api, type AgentInstructionsView } from "../../lib/api";
 import { useAiTools } from "../../hooks/useAiTools";
+import { useSpin } from "../../hooks/useSpin";
 import { AiToolIcon } from "../AiToolIcon";
 import { toast } from "../../lib/toast";
 import { SettingsSection } from "./SettingsRow";
@@ -41,13 +42,16 @@ export function AgentInstructionsSettings() {

  const load = () => {
    setLoadError(null);
-    api.me
+    return api.me
      .instructions()
      .then(apply)
      .catch((err) => setLoadError(err instanceof Error ? err.message : String(err)));
  };

-  useEffect(load, []);
+  useEffect(() => {
+    void load();
+  }, []);
+  const [retrying, retry] = useSpin(load);

  async function save() {
    setSaving(true);
@@ -123,7 +127,12 @@ export function AgentInstructionsSettings() {
              <span className="truncate">
                {t("agentInstructions.loadFailed", { message: loadError })}
              </span>
-              <button type="button" className="btn-ghost shrink-0 text-xs" onClick={load}>
+              <button
+                type="button"
+                className="btn-ghost shrink-0 text-xs"
+                onClick={retry}
+                disabled={retrying}
+              >
                {t("common:retry")}
              </button>
            </p>
@@ -29,6 +29,7 @@ import { AiToolIcon } from "../AiToolIcon";
 import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "../ContextMenu";
 import { api, type AiTool, type AiToolJob } from "../../lib/api";
 import { usePermissions } from "../AuthGate";
+import { copyText } from "../../lib/clipboard";

 type Confirm = { kind: "install" | "update"; tool: AiTool } | { kind: "update-all" };

@@ -374,9 +375,7 @@ export function AiToolsSettings({
            {ctx.menu.item.path && (
              <>
                {isAdmin && <MenuSeparator />}
-                <MenuItem
-                  onSelect={pick((tool) => void navigator.clipboard.writeText(tool.path ?? ""))}
-                >
+                <MenuItem onSelect={pick((tool) => void copyText(tool.path ?? ""))}>
                  {t("rowMenu.copyPath")}
                </MenuItem>
              </>
@@ -16,8 +16,7 @@ import { api } from "../../lib/api";
 import type { PushTokenStatus } from "../../lib/api";
 import { ConfirmModal } from "../ConfirmModal";
 import { SettingsSection } from "./SettingsRow";
-
-const copyText = (text: string) => navigator.clipboard?.writeText(text).catch(() => undefined);
+import { copyText } from "../../lib/clipboard";

 /** The forwarder for the pushing machine; `origin` is how it reaches this dashboard. */
 function forwarder(origin: string) {
@@ -19,6 +19,7 @@ import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "../Context
 import { CopyButton } from "../event-views/primitives";
 import { snapshotUrl } from "../SnapshotButton";
 import { SettingsSection } from "./SettingsRow";
+import { copyText } from "../../lib/clipboard";

 export function SnapshotSettings() {
  const { t } = useTranslation("settings");
@@ -116,9 +117,7 @@ export function SnapshotSettings() {
          <MenuItem onSelect={pick((s) => navigate(`/snapshot/${s.token}`))}>
            {t("snapshots.open")}
          </MenuItem>
-          <MenuItem
-            onSelect={pick((s) => void navigator.clipboard?.writeText(snapshotUrl(s.token)))}
-          >
+          <MenuItem onSelect={pick((s) => void copyText(snapshotUrl(s.token)))}>
            {t("snapshots.copyLink")}
          </MenuItem>
          <MenuSeparator />
@@ -17,6 +17,7 @@ import { api } from "../../lib/api";
 import { useLiveRefresh } from "../../hooks/useLiveRefresh";
 import { laneChangeMatcher } from "../../lib/laneChange";
 import type { PipelineStats } from "../../lib/types";
+import { copyText } from "../../lib/clipboard";

 /** Percentage of `n` out of `total`, 0 when nothing was recorded. */
 function pct(n: number, total: number): number {
@@ -160,7 +161,7 @@ export function LanePipelinePanel({
                    type="button"
                    data-testid={`pipeline-stat-command-${n.id}`}
                    title={t("lanes.copyCommand", { command: n.command })}
-                    onClick={() => void navigator.clipboard?.writeText(n.command || "")}
+                    onClick={() => void copyText(n.command || "")}
                    className="block max-w-full truncate font-mono text-[10px] text-fg-muted hover:text-accent"
                  >
                    {n.command}
@@ -3,7 +3,7 @@
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
 import { describe, expect, it } from "vitest";
-import { claudePastes } from "../promptAttach";
+import { claudePastes, copiedFilePaths, localCandidates } from "../promptAttach";

 describe("claudePastes", () => {
  it("pastes each image as its bare path and the other files as one @ mention paste", () => {
@@ -18,3 +18,46 @@ describe("claudePastes", () => {
    ]);
  });
 });
+
+/** A clipboard as the browser hands it to a paste handler. */
+const clip = (data: Record<string, string>) =>
+  ({ getData: (t: string) => data[t] ?? "" }) as unknown as DataTransfer;
+const file = (name: string) => new File(["x"], name);
+
+describe("localCandidates (a file manager's copy, pasted)", () => {
+  it("takes the plain-text paths when their names match the pasted files", () => {
+    expect(window.location.hostname).toBe("localhost");
+    const dt = clip({ "text/plain": "/home/u/Videos/big.mp4\n/home/u/b c.pdf\n" });
+    expect(localCandidates(dt, [file("b c.pdf"), file("big.mp4")])).toEqual([
+      "/home/u/Videos/big.mp4",
+      "/home/u/b c.pdf",
+    ]);
+  });
+
+  it("takes file:// lines too, decoded", () => {
+    const dt = clip({ "text/plain": "file:///home/u/a%20b.zip" });
+    expect(localCandidates(dt, [file("a b.zip")])).toEqual(["/home/u/a b.zip"]);
+  });
+
+  it("refuses text that does not name exactly the pasted files", () => {
+    expect(localCandidates(clip({ "text/plain": "/etc/passwd" }), [file("big.mp4")])).toBeNull();
+    expect(localCandidates(clip({ "text/plain": "hello" }), [file("hello")])).toBeNull();
+    expect(
+      localCandidates(clip({ "text/plain": "/a/x.txt" }), [file("x.txt"), file("y.txt")])
+    ).toBeNull();
+  });
+
+  it("prefers a uri-list (a drag) as before", () => {
+    const dt = clip({ "text/uri-list": "file:///tmp/z.bin", "text/plain": "/other/z.bin" });
+    expect(localCandidates(dt, [file("z.bin")])).toEqual(["/tmp/z.bin"]);
+  });
+});
+
+describe("copiedFilePaths (no file beside the text)", () => {
+  it("takes file:// text, never bare absolute paths, which stay text to paste", () => {
+    expect(copiedFilePaths(clip({ "text/plain": "file:///home/u/a.txt" }))).toEqual([
+      "/home/u/a.txt",
+    ]);
+    expect(copiedFilePaths(clip({ "text/plain": "/home/u/a.txt" }))).toBeNull();
+  });
+});
@@ -7,7 +7,8 @@
 * last day (`recentUploads`, kept in this browser), and `claudeMention`, the
 * `@` form a file is handed to `claude` in, and what a browser on the
 * dashboard's own machine attaches by path instead of uploading
- * (`localCandidates`, checked by the server in `sameFilesHere` —
+ * (`localCandidates` — a drag's uri-list, or the plain-text paths a pasted
+ * file-manager copy carries —, checked by the server in `sameFilesHere` —
 * `POST /api/run/local-paths` —, `localAttachment`). An attachment is a path
 * sent with the prompt; that check is the one call here to the server.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
@@ -85,7 +86,47 @@ export function localCandidates(
 ): string[] | null {
  if (!isLocalBrowser()) return null;
  const paths = droppedFilePaths(dt);
-  return paths && paths.length === files.length ? paths : null;
+  if (paths) return paths.length === files.length ? paths : null;
+  // A PASTE of a file manager's copy has no uri-list: Chrome hands over the
+  // files and the paths as plain text only. Kept only when the names match
+  // the files one for one — `sameFilesHere` then checks the sizes.
+  const copied = textFilePaths(dt);
+  if (!copied || copied.length !== files.length) return null;
+  const base = (p: string) => p.split(/[\\/]/).pop() ?? "";
+  const want = files.map((f) => f.name).sort();
+  const have = copied.map(base).sort();
+  return have.every((n, i) => n === want[i]) ? copied : null;
+}
+
+/** A paste's plain text as absolute paths — every non-empty line a `file://`
+ *  URI or an absolute path (a file manager's copy) — else null. */
+function textFilePaths(dt: DataTransfer | null | undefined): string[] | null {
+  let lines: string[];
+  try {
+    lines = (dt?.getData("text/plain") ?? "")
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+  if (lines.length === 0) return null;
+  if (lines.every((l) => l.startsWith("file://"))) {
+    return droppedFilePaths({ getData: () => lines.join("\n") } as unknown as DataTransfer);
+  }
+  return lines.every((l) => /^(\/|[A-Za-z]:[\\/])/.test(l)) ? lines : null;
+}
+
+/** The `file://` paths a paste carries as text with no file beside it — a
+ *  file manager's copy, as some browsers paste it — or null: its uri-list,
+ *  else its plain text when every line is one. Plain absolute paths are NOT
+ *  taken here: with no file to compare against, they are text to paste. */
+export function copiedFilePaths(dt: DataTransfer | null | undefined): string[] | null {
+  const uris = droppedFilePaths(dt);
+  if (uris) return uris;
+  const text = dt?.getData("text/plain") ?? "";
+  if (!/^file:\/\//.test(text.trim())) return null;
+  return textFilePaths(dt);
 }

 /** Whether `paths` are the dropped `files` as the dashboard's machine sees
@@ -243,14 +243,19 @@ export function AiToolConfig({ toolId }: { toolId: string }) {
  const [lanes, setLanes] = useState<Lane[]>([]);

  useEffect(() => {
+    // Switching tabs quickly must not show the previous tool's numbers.
+    let cancelled = false;
    api.aiTools
      .usage(toolId)
-      .then(setUsage)
-      .catch(() => setUsage(null));
+      .then((u) => !cancelled && setUsage(u))
+      .catch(() => !cancelled && setUsage(null));
    api.lanes
      .list()
-      .then((r) => setLanes(r.lanes.filter((l) => l.tool === toolId)))
-      .catch(() => setLanes([]));
+      .then((r) => !cancelled && setLanes(r.lanes.filter((l) => l.tool === toolId)))
+      .catch(() => !cancelled && setLanes([]));
+    return () => {
+      cancelled = true;
+    };
  }, [toolId]);

  if (!tool) return null;
@@ -159,6 +159,7 @@ import type {
  CcSettingsSource,
  CcStatusline,
 } from "../lib/api";
+import { isSubmitEnter } from "../lib/keys";

 /** How an inline editor reports unsaved edits to the page. */
 type OnDirty = (id: string, dirty: boolean) => void;
@@ -1795,7 +1796,7 @@ function PluginsPanel({
            value={input}
            onChange={(e) => setInput(e.target.value)}
            onKeyDown={(e) => {
-              if (e.key === "Enter") void submit();
+              if (isSubmitEnter(e)) void submit();
            }}
            placeholder={t("manage.installPlaceholder")}
            aria-label={t("manage.installTitle")}
@@ -2328,7 +2329,7 @@ function McpPanel({
            value={commandLine}
            onChange={(e) => setCommandLine(e.target.value)}
            onKeyDown={(e) => {
-              if (e.key === "Enter") void submit();
+              if (isSubmitEnter(e)) void submit();
            }}
            placeholder={t("manage.addMcpCommandPlaceholder")}
            aria-label={t("mcp.command")}
@@ -2339,7 +2340,7 @@ function McpPanel({
            value={url}
            onChange={(e) => setUrl(e.target.value)}
            onKeyDown={(e) => {
-              if (e.key === "Enter") void submit();
+              if (isSubmitEnter(e)) void submit();
            }}
            placeholder={t("manage.addMcpUrlPlaceholder")}
            aria-label={t("mcp.url")}
@@ -4214,7 +4215,7 @@ function MarketplacesPanel({
            value={source}
            onChange={(e) => setSource(e.target.value)}
            onKeyDown={(e) => {
-              if (e.key === "Enter") void add();
+              if (isSubmitEnter(e)) void add();
            }}
            placeholder={t("manage.addMarketplacePlaceholder")}
            aria-label={t("manage.addMarketplaceTitle")}
@@ -95,6 +95,7 @@ import type {
  CodexScope,
  CodexSkill,
 } from "../lib/api";
+import { isSubmitEnter } from "../lib/keys";

 type TabKey = "overview" | "skills" | "agents" | "rules" | "memory" | "config" | "mcp" | "plugins";

@@ -1630,7 +1631,7 @@ function PluginsPanel({
              value={spec}
              onChange={(e) => setSpec(e.target.value)}
              onKeyDown={(e) => {
-                if (e.key === "Enter") void submitPlugin();
+                if (isSubmitEnter(e)) void submitPlugin();
              }}
              placeholder={t("plugins.installPlaceholder")}
              aria-label={t("plugins.installTitle")}
@@ -1710,7 +1711,7 @@ function PluginsPanel({
              value={mktUrl}
              onChange={(e) => setMktUrl(e.target.value)}
              onKeyDown={(e) => {
-                if (e.key === "Enter") void submitMarketplace();
+                if (isSubmitEnter(e)) void submitMarketplace();
              }}
              placeholder={t("plugins.addMarketplacePlaceholder")}
              aria-label={t("plugins.addMarketplaceTitle")}
@@ -1092,7 +1092,7 @@ function AnalyticsTab() {
        >
          <AlertCircle className="w-4 h-4 flex-shrink-0" />
          <span className="flex-1 min-w-0">{loadError}</span>
-          <button onClick={load} className="btn-ghost text-xs">
+          <button onClick={refresh} disabled={spinning} className="btn-ghost text-xs">
            {t("common:retry")}
          </button>
        </div>
@@ -3133,7 +3133,7 @@ export function Dashboard() {
              <span className="flex-1 min-w-0">
                {t("failedLoad")}: {error}
              </span>
-              <button onClick={load} className="btn-ghost text-xs">
+              <button onClick={refresh} disabled={spinning} className="btn-ghost text-xs">
                {t("common:retry")}
              </button>
            </div>
@@ -561,7 +561,7 @@ export function Sessions({ embedded = false }: { embedded?: boolean } = {}) {
          <span className="flex-1 min-w-0">
            {t("failedList")}: {error}
          </span>
-          <button onClick={load} className="btn-ghost text-xs">
+          <button onClick={refresh} disabled={spinning} className="btn-ghost text-xs">
            {t("common:retry")}
          </button>
        </div>
@@ -120,6 +120,7 @@ import { toast } from "../lib/toast";
 import { useDialog } from "../hooks/useDialog";
 import { useSpin } from "../hooks/useSpin";
 import { exportPrefs, importPrefs } from "../lib/prefsBackup";
+import { isSubmitEnter } from "../lib/keys";

 /** The fewest milliseconds between two activity-driven `/settings/info` reads:
 *  it COUNTs whole tables, and hooks fire many times a second while sessions run. */
@@ -1335,7 +1336,7 @@ function ClearDataDialog({
            value={typed}
            onChange={(e) => setTyped(e.target.value)}
            onKeyDown={(e) => {
-              if (e.key === "Enter" && ok && !busy) onConfirm();
+              if (isSubmitEnter(e) && ok && !busy) onConfirm();
            }}
            autoComplete="off"
            className="input mt-1 w-full font-mono text-sm"
@@ -85,6 +85,7 @@ import { AiToolIcon } from "../components/AiToolIcon";
 import { toast } from "../lib/toast";
 import { useAuth, usePermissions } from "../components/AuthGate";
 import { PageTabs } from "../components/PageTabs";
+import { isSubmitEnter } from "../lib/keys";

 const GROUPS = ["general", "agents", "data"] as const;
 type Group = (typeof GROUPS)[number];
@@ -515,7 +516,7 @@ export function SettingsHub({ section }: { section?: string } = {}) {
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        onKeyDown={(e) => {
-          if (e.key === "Enter" && results[0]) navigate(hrefOf(results[0]), nav);
+          if (isSubmitEnter(e) && results[0]) navigate(hrefOf(results[0]), nav);
          if (e.key === "Escape") setQuery("");
        }}
        placeholder={t("search.placeholder")}
@@ -1105,10 +1105,18 @@ export function Workspace() {
      setFeatures([]);
      return;
    }
+    let cancelled = false;
    api.lanes.features
      .list(currentLane.id)
-      .then((data) => setFeatures(data.features))
-      .catch(() => setFeatures([]));
+      .then((data) => {
+        if (!cancelled) setFeatures(data.features);
+      })
+      .catch(() => {
+        if (!cancelled) setFeatures([]);
+      });
+    return () => {
+      cancelled = true;
+    };
  }, [currentLane?.id]);

  // Fetch the archived snapshot when the picker selects one — read-only, never
@@ -1138,10 +1146,18 @@ export function Workspace() {
      setProofFeatures([]);
      return;
    }
+    let cancelled = false;
    api.lanes.proof
      .list(currentLane.id)
-      .then((data) => setProofFeatures(data.features))
-      .catch(() => setProofFeatures([]));
+      .then((data) => {
+        if (!cancelled) setProofFeatures(data.features);
+      })
+      .catch(() => {
+        if (!cancelled) setProofFeatures([]);
+      });
+    return () => {
+      cancelled = true;
+    };
  }, [currentLane?.id, viewedFeatureSlug]);

  // Resolve the active feature slug: either the user-selected one, or the lane's active_feature_id
@@ -798,6 +798,7 @@ exports[`screen snapshots > Claude Config 1`] = `
        >
          <a
            class="inline-flex items-center gap-2 rounded-lg border border-border bg-surface-2 px-3 py-1.5 text-xs font-medium text-fg-secondary hover:bg-surface-3 transition-colors"
+            data-discover="true"
            href="/settings/agents#tool-profiles"
          >
            <svg
@@ -2806,6 +2807,7 @@ exports[`screen snapshots > Claude Config 1`] = `
        </div>
        <a
          class="btn-ghost shrink-0 text-xs"
+          data-discover="true"
          href="/settings/pricing#pricing-claude"
        >
          Open Pricing
@@ -3222,6 +3224,7 @@ exports[`screen snapshots > Dashboard 1`] = `
      >
        <a
          class="card p-5 block hover:bg-surface-4/40 transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-accent"
+          data-discover="true"
          href="/sessions"
        >
          <div
@@ -3475,6 +3478,7 @@ exports[`screen snapshots > Dashboard 1`] = `
        </div>
        <a
          class="card p-5 block hover:bg-surface-4/40 transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-accent"
+          data-discover="true"
          href="/sessions?view=events"
        >
          <div
@@ -5408,6 +5412,7 @@ exports[`screen snapshots > Dashboard 1`] = `
               
              <a
                class="text-accent hover:underline"
+                data-discover="true"
                href="/settings/notifications"
              >
                Add one in Settings → Notifications
@@ -7239,7 +7244,7 @@ exports[`screen snapshots > Settings — about 1`] = `
                <span
                  class="text-status-warning/90"
                >
-                  UI build v2.8.17 (rebuild client to match)
+                  UI build v2.8.18 (rebuild client to match)
                </span>
              </p>
            </div>
@@ -11059,6 +11064,7 @@ exports[`screen snapshots > Workflows 1`] = `
            </div>
            <a
              class="text-fg-muted hover:text-violet-700 dark:hover:text-violet-400 transition-colors flex-shrink-0"
+              data-discover="true"
              href="/sessions/sess-1"
              title="Open parent session"
            >
@@ -22,6 +22,10 @@ Complete REST API and WebSocket documentation for Agent Dashboard.
  - [Remote Data Sources](#remote-data-sources)
  - [Query Explorer](#query-explorer)
  - [Scheduled reports](#scheduled-reports)
+  - [Webhooks](#webhooks)
+  - [Web Push](#web-push)
+  - [Updates](#updates)
+  - [Import history](#import-history)
 - [WebSocket API](#websocket-api)
 - [Error Handling](#error-handling)
 - [Rate Limiting](#rate-limiting)
@@ -327,6 +331,25 @@ by one, 0.5 s as one batch.
 GET  /api/homes                                   { homes: [{ id: "me" | <username>, label, readOnly, dir? }] }
 GET  /api/homes/:who/fs/list|trash|zip|download   as the workspace routes above
 POST /api/homes/:who/fs/mkdir|newfile|rename|move|copy|delete|upload|trash/restore|trash/purge
+GET  /api/homes/trash                             { items, errors, keepDays } — every Trash the caller may open (below)
+```
+
+One line per route, for searching (bodies and answers as the workspace routes above; `copy` takes `fromLane` instead of `fromHome`, `trash/restore` and `trash/purge` also take `store`):
+
+```
+GET  /api/homes/:who/fs/download?path=
+GET  /api/homes/:who/fs/zip?p=<path>&p=…
+GET  /api/homes/:who/fs/trash
+POST /api/homes/:who/fs/newfile
+POST /api/homes/:who/fs/rename
+POST /api/homes/:who/fs/move
+POST /api/homes/:who/fs/copy
+POST /api/homes/:who/fs/delete
+POST /api/homes/:who/fs/trash/restore
+POST /api/homes/:who/fs/trash/purge
+POST /api/homes/:who/fs/upload?path=&conflict=
+POST /api/homes/:who/fs/upload-check
+POST /api/homes/:who/fs/upload-batch?dir=&conflict=
 ```

 The same File Explorer on a user's HOME (`server/lib/homes.js`): under S3 their
@@ -549,6 +572,14 @@ Error `409 ENOCWD` is returned when the workspace's folder no longer exists (or

 Error `409 ERUNLIVE` is returned if the workspace already has a live run; stop it first with the `stop` action. The same code and status come back when the workspace's tmux pane is already running an agent while a `prompt` or `resumeSessionId` was sent — that argv cannot be typed over a live agent, so the request is refused instead of answered 200 with nothing done. A start that asks for neither still adopts the existing pane silently.

+#### Other workspace actions
+
+```http
+POST /api/lanes/:id/:action
+```
+
+The one control route behind `start` (above), `stop`, `message`, `clear`, `reset`, `remove` and `purge` (same-origin). Any other `:action` is `400 EBADACTION`, an unknown workspace `404 ENOLANE`. `reset`, `remove` and `purge` are destructive and need `{ "confirm": true }` (`400 ECONFIRM`) — see below.
+
 #### Preflight a destructive workspace action

 ```http
@@ -1274,6 +1305,33 @@ anything is spawned, and `args` travels as an array of strings straight into
 argv — neither is ever joined into a command string. An unknown name returns
 `400 ENOHOOK` with the allowed list; a workspace with no slot returns `409 ENOSLOT`.

+#### Scaffold a profile, sync MCP servers, read an integration
+
+```http
+POST /api/lanes/:id/profile/init
+POST /api/lanes/:id/mcp/sync
+GET  /api/lanes/:id/integrations/:name
+```
+
+`profile/init` (same-origin) detects a Node.js project in the workspace's OWN folder and scaffolds `.agenthub/profile/` there — the HTTP twin of `agenthub lanes profile init`. `{ force?: true }` overwrites; answers `{ scaffolded: true, written, todos }`, or `{ scaffolded: false, reason }` (200) when no Node.js project is found; `400 EPROFILEEXISTS` without `force`. `mcp/sync` (same-origin) copies the source repo's `mcpServers` from `~/.claude.json` into `<workspace>/.mcp.json` (paths relocated) and seeds Playwright profiles → `{ servers, profilesSeeded }`; `400 ENOMCPCONFIG` when the source has none. Never automatic — a session calls it. `integrations/:name` → `{ enabled }`, read from `.agenthub/profile/integrations.env`. All three `404 ENOLANE` for an unknown workspace; under S3 the two writes refuse a member's folder the way the runtime routes do.
+
+#### CI status and base sync
+
+```http
+GET  /api/lanes/:id/ci/status?ref=<branch|sha>
+POST /api/lanes/:id/sync-base
+```
+
+`ci/status` is ONE snapshot of GitHub Actions for `ref` through `gh` in the workspace's folder — not a poll loop: `{ state: "pending"|"success"|"failure", ref, checks: [{ name, conclusion, url }] }`; `400 EBADREF` without `ref`. `sync-base` (same-origin, under the workspace lock, needs the workspace profile) merges the profile's base branch INTO the workspace's branch behind a migration-number collision preflight: body `{ mode?: "check"|"merge"|"continue" (default merge), branch? }`. Every documented outcome — clean, a collision, a conflict left in place — is a 200 with `code` 0/4/5; only a malformed request, a missing profile or an out-of-order `continue` answers an `error`. It never writes the stage.
+
+#### Housekeeping
+
+```http
+POST /api/lanes/gc
+```
+
+Same-origin, admin only (`403 EADMIN` for a developer or analyst — it is machine-wide). Reaps orphaned Playwright MCP processes under `LANES_ROOT` and caps oversized logs under `LANES_ROOT/.state/`. `{ dryRun?: true }` reports without acting. Answers `{ reaped, capped }`.
+
 #### Tail a workspace's log

 ```http
@@ -1564,6 +1622,17 @@ Both `GET /api/workflows` and `/skill-usage` also take `from=YYYY-MM-DD&to=YYYY-
 query failure.


+#### Workflow-tool runs
+
+```http
+GET /api/workflows/runs?status=&session_id=&limit=&offset=
+GET /api/workflows/runs/:runId
+GET /api/workflows/session/:id
+```
+
+`runs` lists the fleets the Claude Code **Workflow** tool launched, ingested from their on-disk journals (`server/lib/workflow-ingest.js`): `{ runs, total, counts, limit, offset }`, newest first, `phases`/`progress` parsed into arrays, `counts` per status; `status` (omit or `all` for every one) or `session_id` filters, `limit` 1–1000 (default 50). A developer sees only runs of their own sessions. `runs/:runId` → `{ workflow, agents, events }` — the run, its inner agents and their events (oldest first, at most 5000); `404 WORKFLOW_NOT_FOUND`. `session/:id` is the session drill-in of the Workflow analytics page: `{ session, tree, toolTimeline, swimLanes, events }` (the agent tree, every tool call in order, one swim lane per agent, the first 500 events); `404` for an unknown session.
+
+
 ### Locks

 Cross-workspace named locks (`server/lib/named-lock.js`) — the OTHER axis from a
@@ -1772,6 +1841,16 @@ classDiagram

 ---

+#### Create Session
+
+```http
+POST /api/sessions
+```
+
+Body `{ id, name?, cwd?, model?, metadata? }` (`id` required, else `400 INVALID_INPUT`). An existing id answers `200 { session, created: false }` unchanged; a new one is inserted `active` and broadcast as `session_created` → `201 { session, created: true }`. Sessions normally come from hooks; in server mode a developer or analyst is refused (`403 EADMIN`).
+
+---
+
 #### Update Session

 ```http
@@ -1961,53 +2040,24 @@ curl http://localhost:4820/api/sessions/sess_abc123/stats

 ---

-#### Get Session Agents
+#### Session transcripts

 ```http
-GET /api/sessions/:id/agents
+GET /api/sessions/:id/transcripts
+GET /api/sessions/:id/transcript?agent_id=&run_id=&limit=&after=&before=&offset=
 ```

-Returns all agents for a session.
+`transcripts` lists the session's conversation files — the main one first, then each subagent's and compaction's — as `{ transcripts: [{ id, name, type: "main"|"subagent"|"compaction", subagent_type?, db_agent_id, … }] }`; `db_agent_id` links an entry to its `agents` row (`null` when none matches). A Codex, Antigravity, Cursor, omp or OpenCode session lists its own tool's journal instead.

-**Path Parameters:**
+`transcript` reads one of them as structured messages: no `agent_id` = the main conversation, `agent_id` (+ `run_id` for a Workflow-tool agent) = a subagent's — each one plain name, never a path. `limit` defaults to 50 (max 200); `after=<line>` returns only messages past that JSONL line (the chat's tail), `before=<line>` the page before it (history), `offset` is the legacy pager. Answers `{ messages, total, has_more, last_line, first_line }` (empty when the file is gone). The live file under the Claude projects folder is preferred, else the snapshot taken at import. `404 NOT_FOUND` for an unknown session.

-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | string | Session ID |
+---

-**Example Request:**
+#### Get Session Agents

-```bash
-curl http://localhost:4820/api/sessions/sess_abc123/agents
-```
+There is no `/api/sessions/:id/agents` route: a session's agents come with `GET /api/sessions/:id` (its `agents` array) or from `GET /api/agents?session_id=<id>` (see [Agents](#agents)).

-**Example Response:**
-
-```json
-{
-  "agents": [
-    {
-      "id": "sess_abc123-main",
-      "session_id": "sess_abc123",
-      "name": "Main Agent - my-project",
-      "type": "main",
-      "subagent_type": null,
-      "status": "idle",
-      "current_tool": null,
-      "task": null,
-      "started_at": "2024-03-18T12:00:00Z",
-      "ended_at": null,
-      "updated_at": "2024-03-18T12:05:00Z",
-      "parent_agent_id": null,
-      "awaiting_input_since": "2024-03-18T12:05:00Z",
-      "awaiting_reason": "stop",
-      "cost": 0
-    }
-  ]
-}
-```
-
-> **Note on `cost`** — `/api/agents` and `/api/sessions/:id/agents` attach a `cost` (USD) to each agent: the agent's **own** cost, computed server-side from the per-agent token buckets stored in `agents.metadata.tokens` and priced at the current pricing rules (at the agent's start date, so promo/standard cutovers apply — see [Pricing](#pricing)). It is `0` for main agents (whose cost is the session total, reported by `/api/pricing/cost/:sessionId`), for compaction pseudo-agents, and for any subagent whose transcript is unavailable. This lets a subagent card show only what that subagent spent instead of the whole session's total.
+> **Note on `cost`** — `/api/agents` and `GET /api/sessions/:id` (its `agents`) attach a `cost` (USD) to each agent: the agent's **own** cost, computed server-side from the per-agent token buckets stored in `agents.metadata.tokens` and priced at the current pricing rules (at the agent's start date, so promo/standard cutovers apply — see [Pricing](#pricing)). It is `0` for main agents (whose cost is the session total, reported by `/api/pricing/cost/:sessionId`), for compaction pseudo-agents, and for any subagent whose transcript is unavailable. This lets a subagent card show only what that subagent spent instead of the whole session's total.

 > **Note on `status` vs Waiting** — agents are persisted with one of `idle | connected | working | completed | error`. The yellow **Waiting** badge surfaced in the dashboard is a UI overlay derived from `awaiting_input_since` being non-null on a non-terminal agent (typically `idle` after a `Stop`, or `connected` right after `SessionStart`). Filter `?status=idle` on `/api/agents` and inspect `awaiting_input_since` to enumerate currently-waiting main agents.

@@ -2071,54 +2121,18 @@ curl http://localhost:4820/api/agents/agent_xyz789

 ---

-#### Get Agent Tools
+#### Create or update an agent

 ```http
-GET /api/agents/:id/tools
+POST  /api/agents
+PATCH /api/agents/:id
 ```

-Returns tool executions for an agent.
+`POST` body `{ id, session_id, name, type?, subagent_type?, status?, task?, parent_agent_id?, metadata? }` (`id`, `session_id`, `name` required, else `400 INVALID_INPUT`): an existing id answers `200 { agent, created: false }` (`404 ENOTFOUND` when it is another user's in server mode); a new one is inserted (`type` default `main`, `status` default `waiting`), broadcast as `agent_created` → `201 { agent, created: true }`. `PATCH` takes any of `name`, `status`, `task`, `current_tool`, `ended_at`, `metadata` and answers `{ agent }`; `404 NOT_FOUND` for an unknown id. Agents normally come from hooks.

-**Path Parameters:**
+#### Tool Execution Flow

-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | string | Agent ID |
-
-**Example Request:**
-
-```bash
-curl http://localhost:4820/api/agents/agent_xyz789/tools
-```
-
-**Example Response:**
-
-```json
-{
-  "tools": [
-    {
-      "id": 1,
-      "agent_id": "agent_xyz789",
-      "tool_name": "bash",
-      "duration_ms": 1234,
-      "success": 1,
-      "error_message": null,
-      "created_at": "2024-03-18T12:01:00Z"
-    },
-    {
-      "id": 2,
-      "agent_id": "agent_xyz789",
-      "tool_name": "view",
-      "duration_ms": 45,
-      "success": 1,
-      "error_message": null,
-      "created_at": "2024-03-18T12:02:00Z"
-    }
-  ]
-}
-```
-
-**Tool Execution Flow:**
+Tool calls are recorded as `PreToolUse`/`PostToolUse` events, not as a separate table — read them with `GET /api/events?agent_id=<id>` or `?tool_name=<name>`.

 ```mermaid
 sequenceDiagram
@@ -2129,13 +2143,13 @@ sequenceDiagram
    participant DB as Database
    
    Agent->>PreHook: Tool about to execute
-    PreHook->>DB: Set current_tool
+    PreHook->>DB: Store PreToolUse event, set current_tool
    
    Agent->>Tool: Execute (bash, view, etc.)
    Tool-->>Agent: Result
    
    Agent->>PostHook: Tool completed
-    PostHook->>DB: Create tool_execution record
+    PostHook->>DB: Store PostToolUse event
    PostHook->>DB: Clear current_tool
    PostHook->>DB: Update token counts + cost
 ```
@@ -2154,6 +2168,16 @@ Returns `{ events, limit, offset, total }`, newest first, filtered by `event_typ

 ---

+#### Event filter values
+
+```http
+GET /api/events/facets
+```
+
+`{ event_types, tool_names }` — the distinct values in the events table, sorted, for the Events page's filters (a developer's: only their own sessions' events).
+
+---
+
 ### Data cleanup

 #### Clean up old data
@@ -2198,50 +2222,57 @@ POST /api/settings/uninstall

 Settings → System's **Uninstall AgentHub** (same-origin only). Body `{ "confirm": true }` — anything else is `400 ECONFIRM`; in server mode `403 ESERVERMODE` (a shared dashboard is removed with `agenthub uninstall` on the host). Spawns `scripts/uninstall.js --yes` detached and answers `202 { ok: true, log }` at once; the worker then stops this server and removes everything `agenthub uninstall --yes` does (see [CLI.md](CLI.md)), the database included. `log` is `$TMPDIR/agenthub-uninstall-<uid>.log`, the only record left afterwards.

+#### Clear, re-import, export and restore data
+
+```http
+POST /api/settings/clear-data
+POST /api/settings/reimport
+GET  /api/settings/export
+POST /api/settings/import
+POST /api/settings/reset-pricing
+```
+
+`clear-data` deletes every session, agent, event, token row, workflow run, fired alert and webhook delivery in one transaction (alert rules, webhook targets, pricing, snapshots and reports survive) → `{ ok: true, cleared: <table counts before> }`. `reimport` re-reads the Claude projects folder (`importAllSessions`) → `{ ok: true, imported, skipped, errors, … }`; `500 IMPORT_FAILED`. `export` streams one JSON attachment (`agent-monitor-export-<date>.json`: `format`, `version`, `exported_at`, `sessions`, `agents`, `events`, `token_usage`, `workflows`, `dashboard_runs`, `alert_rules`, `model_pricing`), events written in pages so a large database never sits in memory. `import` (same-origin) restores such a file sent as multipart `file` (≤ 512 MB, else `413 FILE_TOO_LARGE`): non-destructive — a session already here is skipped whole — → `{ ok: true, source, format, …counts }`; `400 NO_FILE` / `BAD_UPLOAD` / `INVALID_FORMAT`. `reset-pricing` reseeds the default model prices (and intro rates), then waits up to 3 s for the automatic price sync → `{ ok: true, pricing }`; `{ scope: "claude" }` resets only the `claude-…` rows. All five are admin-only in server mode, and `export` is staff-only.
+
+#### Hooks for Claude Code, Codex and Antigravity
+
+```http
+POST   /api/settings/reinstall-hooks
+GET    /api/settings/codex-hooks
+POST   /api/settings/codex-hooks
+DELETE /api/settings/codex-hooks
+GET    /api/settings/antigravity-hooks
+POST   /api/settings/antigravity-hooks
+DELETE /api/settings/antigravity-hooks
+```
+
+`reinstall-hooks` rewrites AgentHub's hooks in Claude Code's `settings.json` → `{ ok, hooks }` (`500 HOOK_INSTALL_FAILED`). `codex-hooks` reads, installs (or reinstalls) and removes AgentHub's entries in `$CODEX_HOME/hooks.json` (`server/lib/codex-hooks.js`); every answer is the status `{ supported, path, script, readable, installed, trusted, events: { <Event>: { installed, trusted } }, error? }` — `trusted` is read from Codex's own `config.toml`, which AgentHub never writes. `antigravity-hooks` does the same for the named hook `agenthub` in `~/.gemini/config/hooks.json` (status `{ supported, path, script, readable, installed, enabled, events }`). Only on a click; the writes are same-origin; `400 EBADJSON` / `EUNSUPPORTED` / `EFOREIGN` (a forwarder script that is not AgentHub's), else `500 ESAVE`.
+
+#### Privacy
+
+```http
+GET /api/settings/privacy
+PUT /api/settings/privacy
+```
+
+`{ redact_secrets, ignore_cwd, env_owned: { redact_secrets, ignore_cwd } }` — opt-in redaction of secrets in stored payloads, and the folders whose hooks are dropped (`server/lib/privacy.js`). `PUT` (same-origin) takes either field (`redact_secrets` boolean, `ignore_cwd` a list of absolute folders) and answers `{ ok: true, …state }`; `400 INVALID_INPUT` / `EBADPATH` (not absolute, a filesystem root, over 100 entries), `409 EENVOWNED` when the environment sets it, `500 ESAVE`.
+
+#### Push ingest token
+
+```http
+GET    /api/settings/push-token
+POST   /api/settings/push-token
+DELETE /api/settings/push-token
+```
+
+The token for [`POST /api/hooks/ingest-batch`](#push-ingest-post-apihooksingest-batch). `GET` → `{ enabled, env_owned }` — never the token. `POST` (same-origin) makes a new one (the old one stops working) and returns it THIS ONCE: `{ ok: true, token, enabled, env_owned }`; `DELETE` turns push ingest off → `{ ok: true, enabled: false, env_owned }`. `409 EENVOWNED` when `AGENTHUB_PUSH_TOKEN_SHA256` comes from the environment.
+
+
 ---

 ### Tools

-#### List All Tools
-
-```http
-GET /api/tools
-```
-
-Returns all tool executions across all sessions.
-
-**Query Parameters:**
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `limit` | integer | 100 | Max tools to return |
-| `tool_name` | string | - | Filter by tool name |
-| `success` | boolean | - | Filter by success status |
-
-**Example Request:**
-
-```bash
-curl http://localhost:4820/api/tools?limit=50&tool_name=bash
-```
-
-**Example Response:**
-
-```json
-{
-  "tools": [
-    {
-      "id": 1,
-      "agent_id": "agent_xyz789",
-      "tool_name": "bash",
-      "duration_ms": 1234,
-      "success": 1,
-      "error_message": null,
-      "created_at": "2024-03-18T12:01:00Z"
-    }
-  ],
-  "total": 156
-}
-```
+There is no `/api/tools` route. Per-tool counts come from `GET /api/sessions/:id/stats` (`tools_used`, `tool_call_count`) and `GET /api/events/facets`; individual calls from `GET /api/events?tool_name=<name>`.

 ---

@@ -2290,6 +2321,27 @@ A ready-made Prometheus config, recording rules and three Grafana boards built o

 ---

+#### Overview counts
+
+```http
+GET /api/stats?tz_offset=&sources=&tool=
+```
+
+The Dashboard's header numbers: the overview counts (sessions, agents, events…), `events_today` (in the local day of `tz_offset`, the browser's `getTimezoneOffset()`), `ws_connections`, `agents_by_status` and `sessions_by_status` (`{ <status>: count }`). `sources`/`tool` narrow it like `/api/sessions`; a malformed `tool` is `400 INVALID_INPUT`.
+
+#### Health and API docs
+
+```http
+GET /api/health
+GET /api/openapi.json
+GET /api/redoc
+GET /api/redoc/redoc.standalone.js
+```
+
+`health` → `{ status: "ok", version, timestamp }`, exempt from every login. `openapi.json` is this API's OpenAPI 3.0 document (also browsable at `/api/docs`, Swagger UI); `redoc` renders it with ReDoc, whose script `redoc.standalone.js` is served locally (no CDN).
+
+---
+
 ### Pricing

 #### List Pricing Rules
@@ -2535,41 +2587,28 @@ POST /api/alerts/rules/preview

 ### Notifications

-#### Get Session Notifications
+Notifications are not stored per session and have no REST read. Hook `Notification` events land in the events table (`GET /api/events?session_id=<id>&event_type=Notification`), and the dashboard's alerts feed is [`GET /api/alerts`](#alerts-feed).
+#### Alert rules

 ```http
-GET /api/sessions/:id/notifications
+GET    /api/alerts/rules
+POST   /api/alerts/rules
+PATCH  /api/alerts/rules/:id
+DELETE /api/alerts/rules/:id
 ```

-Returns notifications for a session.
+`GET` → `{ rules: [{ id, name, rule_type, config, enabled, cooldown_seconds, … }] }` (`config` parsed). `POST` body `{ name, rule_type, config, enabled?, cooldown_seconds? }`: `rule_type` is one of `event_pattern`, `inactivity`, `status_duration`, `token_threshold`, `cost_threshold`, `budget`, and `config` is validated for it (`validateRuleConfig`); `cooldown_seconds` defaults to 300 → `201 { rule }`. `PATCH` takes `name`, `config` (checked against the stored type — `rule_type` is immutable), `enabled`, `cooldown_seconds` → `{ rule }`. `DELETE` → `{ ok: true }`, its fired alerts cascading away. `400 INVALID_INPUT`, `404 NOT_FOUND`. In server mode rules are staff-only and their writes admin-only. See [Spend Budgets](#spend-budgets) for `budget` and the read-only preview.

-**Path Parameters:**
+#### Alerts feed

-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | string | Session ID |
-
-**Example Request:**
-
-```bash
-curl http://localhost:4820/api/sessions/sess_abc123/notifications
+```http
+GET  /api/alerts?unacked=true&limit=&offset=
+POST /api/alerts/:id/ack
+POST /api/alerts/ack-all
 ```

-**Example Response:**
+`GET` → `{ alerts, total, unacked, limit, offset }`, newest first (`limit` 1–200, default 50; `unacked=true` only the unacknowledged). A developer's feed is their own sessions' alerts (one with no session — a budget — is staff-only); an analyst's rows carry `can_ack`. `:id/ack` acknowledges one (`:id` numeric) → `{ alert }`, broadcast as `alert_updated`; `404 NOT_FOUND`. `ack-all` → `{ ok: true, acknowledged }` (a developer's or analyst's: their own sessions' only).

-```json
-{
-  "notifications": [
-    {
-      "id": 1,
-      "session_id": "sess_abc123",
-      "notification_type": "backgroundTaskComplete",
-      "message": "Explore agent completed",
-      "created_at": "2024-03-18T12:05:00Z"
-    }
-  ]
-}
-```

 ### Remote Data Sources

@@ -2895,6 +2934,7 @@ POST   /api/run/:id/permission-mode   {mode} → Shift+Tab steps, each read back
 POST   /api/run                       Start/attach run — Body: { laneId, cwd?, model?, permissionMode?, effort?, resumeSessionId?, initialPrompt?, sandbox?, approval?, resumeLast?, bypass? }
 GET    /api/run/:id                   Run handle (returns live run state)
 DELETE /api/run/:id[?archive=1]       Kill the pane → {ok}. `archive=1` (the UI's Stop) also archives the session it held → {ok, archived: <session id> | null}; without it (Sleep, the CLI) the session stays listed to resume
+DELETE /api/run/history/:id          Forget one CLOSED Terminal tab (`tool = 'shell'`) from the history now → {removed}; 409 ERUNLIVE while open, 404 ENOTFOUND for any other row
 ```

 `:id` must be a workspace pane name, `agenthub-lane-<n>`; anything else answers 404 without reaching tmux, so these two routes can never touch a tmux session the dashboard did not start.
@@ -3145,6 +3185,53 @@ POST   /api/settings/compact       { confirm: true } → 202 — started (or alr
 Settings → Data → **Session cleanup** (`server/lib/db-retention.js`). Automatic retention is OFF unless `days` (1–3650, `AGENTHUB_RETENTION_DAYS` in the settings file) is set; nothing is deleted by default. When set, the hourly maintenance (`DASHBOARD_DB_MAINTAIN_MS`) purges finished (completed/error/abandoned) sessions that started more than `days` ago — the same rule and the same deletion (`purgeSessionIds`: events, agents, token usage, the session) as `POST /api/settings/cleanup` with `purge_days` — 25 sessions per transaction with a yield between, at most 5000 per run. A new database is created with `auto_vacuum = INCREMENTAL`, an existing one up to 32 MB is converted by a VACUUM at startup; the same hourly run then returns free pages to the OS (`incremental_vacuum`, in 1024-page slices, at most 65536 pages per run) once more than 1024 are free. A larger, older database is converted only by **Compact**: a full VACUUM in a worker thread followed by a TRUNCATE checkpoint — it holds the write lock while it runs (tens of seconds on a GB-size file), so hooks wait meanwhile; it runs only on a click. In server mode both writes are an admin's (`/settings` is in `ADMIN_WRITE_PREFIXES`).
 ---

+### Webhooks
+
+```http
+GET    /api/webhooks/providers
+GET    /api/webhooks
+POST   /api/webhooks
+PATCH  /api/webhooks/:id
+DELETE /api/webhooks/:id
+POST   /api/webhooks/:id/test
+GET    /api/webhooks/:id/deliveries?limit=&offset=
+```
+
+Where fired alerts are delivered (`server/lib/webhook-providers.js`). `providers` → `{ providers }`, the catalog with each provider's fields (secrets flagged). A target is answered REDACTED: `{ id, name, type, enabled, url_preview (masked), has_secret, headers (values redacted, generic family only), config (secret fields as ••••), rule_ids, created_at, updated_at, last_delivery }`. `POST` body `{ name, type, url?, enabled?, secret?, headers?, rule_ids?, config? }` — `type` one of the catalog ids (`slack`, `discord`, `teams`, `google_chat`, `mattermost`, `rocketchat`, `telegram`, `pagerduty`, `opsgenie`, `splunk_oncall`, `zapier`, `make`, `pipedream`, `generic`); `url` is required for providers that need one; `secret`/`headers` apply to the generic family only; `rule_ids` limits it to those alert rules (omit = all) → `201 { target }`. `PATCH` changes only the keys present (`config` is merged over the stored one, so a secret need not be re-sent) → `{ target }`. `DELETE` → `{ ok: true }` (its delivery log cascades). `test` sends a synthetic alert and always answers 200 `{ ok, status, attempts, error }`. `deliveries` → `{ deliveries, limit, offset }` (`limit` 1–200, default 20). `400 INVALID_INPUT`, `404 NOT_FOUND`. Staff-only in server mode, writes admin-only.
+
+### Web Push
+
+```http
+GET    /api/push/vapid-public-key
+POST   /api/push/subscribe
+DELETE /api/push/subscribe
+POST   /api/push/send
+```
+
+`vapid-public-key` → `{ publicKey }` for `PushManager.subscribe`. `subscribe` stores a browser subscription `{ endpoint, keys: { p256dh, auth } }` (upsert by `endpoint`; in server mode tagged with the user) → `{ ok: true }`; `DELETE` takes `{ endpoint }` in the BODY (a user removes only their own) → `{ ok: true }`. `send` `{ title, body, url? }` pushes to every subscription (in server mode: the caller's own) and fires a native notification in the desktop app → `{ ok: true, native, pushed, failed }`. `400` with `{ error: { message } }` on a missing field.
+
+### Updates
+
+```http
+GET  /api/updates/status
+POST /api/updates/check
+POST /api/updates/apply
+```
+
+Release-based update detection (`server/lib/update-check.js`). `status` and `check` answer the same object — `{ git_repo, update_available, install_kind: "checkout"|"plugin", local_version, latest_release, latest_release_url, latest_release_notes, release_check, commits_behind, commits_behind_release, manual_command, situation, last_plugin_update, repo_root, … }` (`repo_root` is `null` for a developer); `check` also broadcasts it as `update_status`. `apply` (admin-only in server mode) picks its mode by install kind, never from the request: a fast-forwardable checkout merges the release `--ff-only`, rebuilds, answers `{ …, applied: true }` and then restarts the server; a plugin-cache install with a newer release hands off to the detached plugin-update chain → `{ …, applied: true, mode: "plugin" }`. Nothing to apply is `409 UPDATE_NOT_APPLICABLE` (`reason`: `up_to_date`, `plugin_managed`, `not_fast_forwardable`). `500 UPDATE_STATUS_FAILED` / `UPDATE_CHECK_FAILED` / `UPDATE_APPLY_FAILED`.
+
+### Import history
+
+```http
+GET  /api/import/guide
+POST /api/import/rescan
+POST /api/import/scan-path
+POST /api/import/upload
+```
+
+Bring Claude Code history in (Settings → Import). `guide` → `{ platform, default_projects_dir, default_projects_dir_display, default_projects_dir_exists, default_projects_dir_stats: { projects, jsonl_files }, archive_command, supported_extensions, max_upload_bytes, max_upload_files, steps }`. `rescan` re-reads the default projects folder → `{ ok: true, source: "default", … }`. `scan-path` `{ path }` (absolute, `~` expanded, a directory) imports from it → `{ ok: true, source: "path", path, imported, skipped, backfilled, errors, sessions_seen, files_scanned }`; `400 INVALID_INPUT` / `PATH_NOT_FOUND` / `NOT_A_DIRECTORY`. `upload` takes multipart `files` (`.jsonl`, `.meta.json`, `.zip`, `.tar`, `.tar.gz`, `.tgz`, `.gz`; up to `AGENTHUB_IMPORT_MAX_FILES` = 2000 files and `AGENTHUB_IMPORT_MAX_BYTES` = 1 GB), extracts archives into a private temp dir and imports → `{ ok: true, source: "upload", files_received, rejected_files, entries_extracted, entries_skipped, …counts }`; `400 NO_FILES` / `NO_JSONL`, `413` when an archive passes the extraction limits. Imports are idempotent, and progress is broadcast as `import.progress`. Staff-only in server mode, admin-only to run; `500 IMPORT_FAILED`.
+
+
 ## WebSocket API

 ### Connection
@@ -109,7 +109,7 @@ The CLI talks to the local dashboard server — **API-backed commands require it
 | `agenthub server tools` | One Linux user per account: publish this install's scripts and every installed AI tool under `/opt/agenthub` (`tools/bin/<command>`), where every account's pane runs them. The server also does this at start and after each install or update. Prints each tool's shared copy, or why it could not be shared |
 | `agenthub server off` / `agenthub server status` | Back to local mode (accounts kept) / show the mode and account count |
 | `agenthub accounts list\|add <name>\|remove <name>` | The **Claude account pool**: new Claude sessions spread over these accounts (each a `claude setup-token` token, typed hidden or read from stdin). `list` shows live panes, $ and tokens in the last 5 h / 7 d, and quota. With `--tool codex` the same for the **Codex account pool**: `add <name> --tool codex --api-key` (key typed hidden or on stdin) or `--from <dir>` (a `codex login` home or its `auth.json`). `pin <account> <user>` / `unpin <user>` (add `--tool codex` for Codex) switches one user's sessions to that account (a Claude login goes into their home at once, running sessions follow without a restart) (server mode; `list` shows a `pinned` column). See [SERVER-MODE.md](SERVER-MODE.md#claude-account-pool) |
-| `agenthub users list\|add <name> [--role admin\|analyst\|member]\|passwd <name>\|role <name> <role>\|disable <name>\|enable <name>\|provision <name>\|--all\|assign <workspace id> <name>\|audit [--limit N]` | Server mode's accounts, written straight to the database. Once `install-system` ran, `add` first creates the Linux user `ah-<name>`; a name must then be lower case: a letter, then up to 28 letters, digits, `_` or `-`. `disable`/`enable` lock or unlock that Linux user too, and `provision` gives users made earlier their Linux user (idempotent); `assign` gives a workspace made before server mode an owner; `audit` lists admin/analyst reads of members' sessions. Inside a dashboard pane in server mode, every command acts as the workspace's owner through the pane's `AGENTHUB_PANE_TOKEN`. A password is typed hidden twice, or read from the first line of stdin |
+| `agenthub users list\|add <name> [--role admin\|analyst\|developer]\|passwd <name>\|role <name> <role>\|disable <name>\|enable <name>\|provision <name>\|--all\|assign <workspace id> <name>\|audit [--limit N]` | Server mode's accounts, written straight to the database. Once `install-system` ran, `add` first creates the Linux user `ah-<name>`; a name must then be lower case: a letter, then up to 28 letters, digits, `_` or `-`. `disable`/`enable` lock or unlock that Linux user too, and `provision` gives users made earlier their Linux user (idempotent); `assign` gives a workspace made before server mode an owner; `audit` lists admin/analyst reads of developers' sessions. Inside a dashboard pane in server mode, every command acts as the workspace's owner through the pane's `AGENTHUB_PANE_TOKEN`. A password is typed hidden twice, or read from the first line of stdin |

 ### Interactive REPL

@@ -273,7 +273,7 @@ Omit `<id>` and the command addresses the workspace owning the current directory

 Resolution order, shared by every cwd-resolving command: `--workspace` (old name `--lane`)/leading id → `AGENTHUB_LANE_ID` (exported into every tmux pane the dashboard starts) → `--tool <id>`, else the harness's marker (`CLAUDECODE` means claude; Codex has no equivalent marker, so a codex session outside a dashboard pane passes `--tool codex`) → the workspace owning the directory. One directory can back a `claude` workspace and a `codex` workspace at once, so when two candidates remain the command fails and names both instead of picking one — see [Which workspace a CLI command addresses](LANES.md#which-workspace-a-cli-command-addresses).

-Because a workspace's services are fully detached, restarting the dashboard (or `agenthub update`) never stops a running stack.
+Because a workspace's services are fully detached, restarting the dashboard (or applying an update — `agenthub update-check` reports one, the dashboard's Update button applies it) never stops a running stack.

 ### Integrations

@@ -619,7 +619,7 @@ Server mode's accounts ([SERVER-MODE.md](SERVER-MODE.md), `server/lib/auth.js`).

 | Table | Columns |
 | --- | --- |
-| `users` | `id`, `username` (unique, case-insensitive), `role` (`admin`\|`analyst`\|`member`), `password_hash` (`scrypt$<salt>$<hash>`), `disabled`, `created_at` |
+| `users` | `id`, `username` (unique, case-insensitive), `role` (`admin`\|`analyst`\|`developer` — `member` before, migrated on start), `password_hash` (`scrypt$<salt>$<hash>`), `disabled`, `created_at` |
 | `auth_sessions` | `token_hash` (SHA-256 of the cookie token, PK), `user_id` → `users.id` (cascade), `created_at`, `expires_at` (30 days) |
 | `account_pins` | `user_id` → `users.id` (cascade), `tool` (`claude`\|`codex`), `account` (a pool account's name), `pinned_at`; PK (`user_id`, `tool`) — an admin's pin of a user to one pool account (`server/lib/account-pins.js`) |

@@ -107,7 +107,7 @@ Internal build — all rights reserved.
  Prometheus rules + Grafana boards for `/api/metrics`
  (`docker-compose.monitoring.yml`, [docs/MONITORING.md](MONITORING.md)).
 - **Server mode for a shared dashboard** (`agenthub server setup`): a login on
-  every page and API call, with admin / member / analyst roles. It is off by
+  every page and API call, with admin / developer / analyst roles. It is off by
  default, and a local install does not change. It is login only, without
  per-user isolation yet ([docs/SERVER-MODE.md](SERVER-MODE.md)).

@@ -43,7 +43,7 @@ graph TB
 |----------|-------------|----------|
 | [client/README.md](../client/README.md) | React frontend architecture, components, state management | Frontend developers |
 | [server/README.md](../server/README.md) | Express backend, database, WebSocket, API | Backend developers |
-| [API.md](./API.md) | REST API endpoints (sessions, agents, events, stats, analytics, hooks, pricing, workflows, settings, import history, **cc-config**, **run**), WebSocket protocol (including `run_stream` / `run_status` / `run_input_ack` for the Run page) | Integration developers |
+| [API.md](./API.md) | REST API endpoints (sessions, agents, events, stats, analytics, hooks, pricing, workflows, settings, import history, **cc-config**, **run**), WebSocket protocol (JSON broadcast messages, plus the binary `/ws-pty/:runId` terminal stream of a lane pane) | Integration developers |
 | [SERVER-MODE.md](./SERVER-MODE.md) | Server mode: logins and roles for a dashboard shared over the web (`agenthub server setup`), reverse proxy setup | Operators |
 | [DATABASE.md](./DATABASE.md) | SQLite schema, queries, performance | Database administrators |
 | [HOOKS.md](./HOOKS.md) | Claude Code hook system integration | Hook developers |
@@ -1,12 +1,12 @@
 {
  "name": "agenthub",
-  "version": "2.8.17",
+  "version": "2.8.18",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "agenthub",
-      "version": "2.8.17",
+      "version": "2.8.18",
      "hasInstallScript": true,
      "license": "UNLICENSED",
      "dependencies": {
@@ -1,6 +1,6 @@
 {
  "name": "agenthub",
-  "version": "2.8.17",
+  "version": "2.8.18",
  "bin": {
    "agenthub": "bin/agenthub.js"
  },
@@ -94,7 +94,6 @@ const EXPECTED_API_PATHS = [
  "/api/run/files",
  "/api/run/binary",
  "/api/run/{id}",
-  "/api/run/{id}/message",
  "/api/webhooks",
  "/api/webhooks/providers",
  "/api/webhooks/{id}",
@@ -1215,4 +1215,15 @@ describe("/api/cc-config", () => {
    assert.equal(status, 400);
    assert.equal(body.error.code, "EBADARG");
  });
+
+  it("refuses a write from a foreign origin before it reaches the CLI", async () => {
+    for (const p of ["/api/cc-config/mcp/add", "/api/cc-config/plugins/install"]) {
+      const { status } = await fetchJson(p, {
+        method: "POST",
+        body: { name: "x", command: "true", plugin: "x@y" },
+        headers: { Origin: "https://evil.example" },
+      });
+      assert.equal(status, 403, p);
+    }
+  });
 });
@@ -20,6 +20,11 @@ const misc = require("./openapi-extra/misc");
 const auth = require("./openapi-extra/auth");
 const files = require("./openapi-extra/files");
 const artifacts = require("./openapi-extra/artifacts");
+// Routes the spec had missed (audit 2026-10-22): new path keys only — a key
+// that already existed got its missing method in place instead.
+const lanesMore = require("./openapi-extra/lanes-more");
+const toolsMore = require("./openapi-extra/tools-more");
+const opsMore = require("./openapi-extra/ops-more");
 // Enriched overrides of already-documented endpoints — same operationId, tags,
 // and request/response `$ref` schemas as the base, with added examples and
 // richer descriptions. Listed last so they win the merge.
@@ -58,6 +63,9 @@ module.exports = combine(
  auth,
  files,
  artifacts,
+  lanesMore,
+  toolsMore,
+  opsMore,
  overrideSessionsAgents,
  overrideCore,
  overridePricingAlerts,
@@ -1903,6 +1903,65 @@ const paths = {
        },
      },
    },
+    patch: {
+      tags: ["CcConfig"],
+      summary: "Merge keys into one settings layer",
+      description:
+        'Sets and/or unsets dotted keys (`set: {"hooks.PreToolUse": [...]}`, `unset: ["model"]`) in one settings.json layer. The file is re-read unredacted and only the named keys change; a value containing the `<redacted>` placeholder is refused (`EREDACTED`). The project layers resolve against the SERVER\'s cwd, never `?cwd=`. An existing file is backed up first. Broadcasts `cc_config_changed`. Admin-only in server mode.',
+      operationId: "ccConfigPatchSettings",
+      requestBody: {
+        required: true,
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              required: ["scope"],
+              properties: {
+                scope: { type: "string", enum: ["user", "project", "project-local"] },
+                set: { type: "object", additionalProperties: true },
+                unset: { type: "array", items: { type: "string" } },
+              },
+            },
+          },
+        },
+      },
+      responses: {
+        200: {
+          description: "Written (or nothing changed).",
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  path: { type: "string" },
+                  backupPath: { type: "string", nullable: true },
+                  created: { type: "boolean" },
+                  changed: { type: "array", items: { type: "string" } },
+                },
+              },
+            },
+          },
+        },
+        400: {
+          description: "`EBADSCOPE`, `EBADCONTENT` (nothing to change) or `EREDACTED`.",
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } },
+          },
+        },
+        409: {
+          description: "`EBADJSON` — the file on disk is not a JSON object; fix it by hand.",
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } },
+          },
+        },
+        413: {
+          description: "`ETOOLARGE`.",
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } },
+          },
+        },
+      },
+    },
  },

  "/api/cc-config/memory": {
@@ -0,0 +1,762 @@
+/**
+ * @file OpenAPI fragment for the workspace (lane) routes the base spec and
+ * server/openapi-extra/lanes.js did not cover: the lane list and create, the
+ * folder browser, pipeline/feature/stage reads and declarations, proof
+ * screenshots, the MCP/profile/integration/CI/sync-base runtime primitives,
+ * removing a session's worktree, housekeeping (`/gc`), a workspace's own
+ * context (server/routes/lane-sources.js: instructions, extra folders,
+ * context files, memory), plus the cross-lane named locks (/api/locks) and
+ * the project tree (/api/projects). Exports `{ tags, schemas, paths }` for
+ * server/openapi-extra.js. Every /api/lanes path is also served under
+ * /api/workspaces by the same handlers.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const tags = [
+  {
+    name: "Locks",
+    description:
+      "Cross-lane named locks (server/lib/named-lock.js). Single-shot — the server never waits for a lock; `agenthub lock acquire` owns the polling loop.",
+  },
+  {
+    name: "Projects",
+    description:
+      "Workspaces grouped by the git repository they belong to, with that repository's worktrees (server/lib/projects.js).",
+  },
+];
+
+const idParam = { name: "id", in: "path", required: true, schema: { type: "integer" } };
+const json = (schema) => ({ content: { "application/json": { schema } } });
+const obj = { type: "object", additionalProperties: true };
+const notFound = { description: "ENOLANE — workspace not found." };
+const crossOrigin = { description: "The browser request was not same-origin." };
+const s3Refused = {
+  description:
+    "Same-origin refusal, or EMEMBERLANE (S3: not offered for a workspace in a member's folder — the runtime layer runs as the dashboard's own account).",
+};
+
+const SOURCES_VIEW = {
+  type: "object",
+  description: "A workspace's own context, as the Context panel shows it.",
+  properties: {
+    instructions: {
+      type: "string",
+      description: "The workspace's instructions (`''` when unset).",
+    },
+    supported: {
+      type: "boolean",
+      description: "Whether the workspace's tool takes instructions and sources (Claude, Codex).",
+    },
+    maxFileBytes: { type: "integer", example: 10485760 },
+    maxInstructions: { type: "integer", example: 16000 },
+    sources: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "integer" },
+          kind: { type: "string", enum: ["folder", "file"] },
+          path: { type: "string" },
+          name: { type: "string" },
+          size: { type: "integer", nullable: true },
+          added_at: { type: "string", format: "date-time" },
+          missing: { type: "boolean", description: "The path no longer exists on disk." },
+        },
+      },
+    },
+  },
+};
+
+const sourcesErrors = {
+  400: { description: "EBADFIELD, EBADPATH, ETOOMANY, EUNSUPPORTED or another validation code." },
+  403: {
+    description: "EBADORIGIN (not same-origin) or EFOLDER (outside the caller's own folder).",
+  },
+  404: { description: "ENOLANE, or ENOSOURCE for an unknown source id." },
+};
+
+const paths = {
+  "/api/lanes": {
+    get: {
+      tags: ["Lanes"],
+      summary: "List workspaces with live counts",
+      description:
+        "Every workspace the caller may see (server mode: a developer only their own), each as the full lane payload (stage, pipeline nodes, liveness, run state). One `tmux list-sessions` answers every lane's run. Working-copy facts are NOT here — see `GET /api/lanes/{id}/git`.",
+      operationId: "listLanes",
+      responses: {
+        200: {
+          description: "The lanes and their counts.",
+          ...json({
+            type: "object",
+            properties: {
+              lanes: { type: "array", items: obj },
+              counts: {
+                type: "object",
+                properties: {
+                  total: { type: "integer" },
+                  running: { type: "integer" },
+                  needs_you: { type: "integer" },
+                  dead: { type: "integer" },
+                },
+              },
+            },
+          }),
+        },
+      },
+    },
+    post: {
+      tags: ["Lanes"],
+      summary: "Create a workspace for an existing folder",
+      description:
+        "Inserts a lane row (owner = the caller, never from the body) and broadcasts `lane_update`. A non-admin may only name a folder inside their own (EFOLDER), never one another user's workspace owns (EOWNED). Uniqueness is per (cwd, tool). Same-origin only.",
+      operationId: "createLane",
+      requestBody: {
+        required: true,
+        ...json({
+          type: "object",
+          required: ["cwd"],
+          properties: {
+            cwd: { type: "string", description: "Absolute folder path." },
+            title: { type: "string" },
+            branch: { type: "string", nullable: true },
+            pipeline: { type: "string", default: "default" },
+            kind: { type: "string", enum: ["adopted", "managed"], default: "adopted" },
+            tool: { type: "string", default: "claude", description: "An AI Tools catalog id." },
+          },
+        }),
+      },
+      responses: {
+        201: { description: "`{lane}` — the new lane payload.", ...json(obj) },
+        400: {
+          description: "EBADCWD, EBADPIPELINE, EBADKIND, EBADFIELD, EBADTOOL or EDISABLED.",
+        },
+        403: { description: "EFOLDER, or not same-origin." },
+        409: {
+          description:
+            "EDUPCWD (a workspace already owns that cwd for this tool), EOWNED, EOWNERFOLDER or EMEMBERGONE.",
+        },
+      },
+    },
+  },
+  "/api/lanes/browse": {
+    get: {
+      tags: ["Lanes"],
+      summary: "List a server folder for the folder browser",
+      description:
+        "Read-only directory listing for the Add workspace dialogs (a browser cannot expose absolute paths from its own picker). Folders first; each entry carries `mtime` (ms) and, for a folder, `isGitRepo`. A developer browses only inside their own folder (by real path; EFOLDER), and never sees the dot entries at its top. An admin with their own Linux account (S3) starts in that home; `host=1` opens the host account's home instead.",
+      operationId: "browseLaneFolders",
+      parameters: [
+        {
+          name: "path",
+          in: "query",
+          schema: { type: "string" },
+          description: "Default: the caller's start home.",
+        },
+        {
+          name: "files",
+          in: "query",
+          schema: { type: "string", enum: ["1"] },
+          description: "List files too; `path` may then name a file (its folder opens).",
+        },
+        {
+          name: "hidden",
+          in: "query",
+          schema: { type: "string", enum: ["1"] },
+          description: "List dot entries too.",
+        },
+        {
+          name: "host",
+          in: "query",
+          schema: { type: "string", enum: ["1"] },
+          description: "S3 admin: open the host account's home.",
+        },
+      ],
+      responses: {
+        200: {
+          description:
+            "`{path, parent, entries:[{name, path, isGitRepo, file?, mtime}], home, hostHome?}` — `parent` is null at the top.",
+          ...json(obj),
+        },
+        400: { description: "ENOTFOUND (path does not exist) or ENOTADIR." },
+        403: { description: "EFOLDER — outside the caller's own folder." },
+      },
+    },
+  },
+  "/api/lanes/pipelines": {
+    get: {
+      tags: ["Lanes"],
+      summary: "List loaded pipeline templates",
+      description:
+        "Templates loaded from DASHBOARD_PIPELINES_DIR. AgentHub ships none, so this is empty unless a template was dropped in (pipelines are dormant).",
+      operationId: "listLanePipelines",
+      responses: { 200: { description: "`{pipelines:[…template]}`.", ...json(obj) } },
+    },
+  },
+  "/api/lanes/pipeline-stats": {
+    get: {
+      tags: ["Lanes"],
+      summary: "Per-node pass statistics across lanes and archived features",
+      description:
+        "Folds `lane_stage_events` into one verdict per (run, node): `entered`, `passed`, `failed`, `withEvidence` count declarations; `detected` counts nodes only inferred from hooks. Pipelines of in-scope lanes with no events appear at zero. The `lanes` list (picker) is never narrowed by `lane`. Server mode: a developer's aggregate covers their own workspaces.",
+      operationId: "lanePipelineStats",
+      parameters: [
+        {
+          name: "lane",
+          in: "query",
+          schema: { type: "string" },
+          description: "A lane id, or `all`/empty for every lane.",
+        },
+      ],
+      responses: {
+        200: {
+          description:
+            "`{pipelines:[{id, name, runs, nodes:[{id, label, icon, gate, command, entered, passed, withEvidence, failed, detected}]}], lanes:[{id, title, cwd}]}`, busiest pipeline first.",
+          ...json(obj),
+        },
+        400: { description: "EBADLANE — `lane` is not an id." },
+      },
+    },
+  },
+  "/api/lanes/gc": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Machine-wide lane housekeeping",
+      description:
+        "Kills orphaned (parent pid 1) Playwright-MCP process trees under LANES_ROOT and caps every hook log over 10 MB under `LANES_ROOT/.state/lane<N>/logs/` to its last 2 MB, in place. `dryRun: true` only reports. Admin only in server mode (EADMIN); same-origin.",
+      operationId: "laneHousekeeping",
+      requestBody: json({ type: "object", properties: { dryRun: { type: "boolean" } } }),
+      responses: {
+        200: {
+          description: "`{reaped:[pid], capped:[{path, sizeBefore}]}`.",
+          ...json(obj),
+        },
+        403: { description: "EADMIN, or not same-origin." },
+        500: { description: "The sweep failed." },
+      },
+    },
+  },
+  "/api/lanes/{id}/stage": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Declare a lane's stage",
+      description:
+        "The driving session's own claim of progress (`agenthub stage`). Clears detection columns on a real transition; a declaration on a node BEFORE the current one drops the stage records of every node ahead. The dashboard UI never calls this. With no pipeline template installed the lane has no stages (ENOPIPELINE). Broadcasts `lane_update`. Same-origin.",
+      operationId: "declareLaneStage",
+      parameters: [idParam],
+      requestBody: {
+        required: true,
+        ...json({
+          type: "object",
+          properties: {
+            stage: { type: "string", description: "A node id or alias of the lane's pipeline." },
+            status: { type: "string" },
+            evidence: { type: "string", nullable: true },
+            note: { type: "string" },
+            result: { type: "string", description: "`fail` marks the node failed." },
+          },
+        }),
+      },
+      responses: {
+        200: { description: "`{lane}`.", ...json(obj) },
+        400: {
+          description:
+            "ENOPIPELINE (no template installed) or EBADSTAGE (not a node of this pipeline; `error.stages` lists the valid ids).",
+        },
+        403: crossOrigin,
+        404: notFound,
+      },
+    },
+  },
+  "/api/lanes/{id}/features": {
+    get: {
+      tags: ["Lanes"],
+      summary: "List a lane's features",
+      description:
+        "Every feature the lane has activated, live or archived, each with its computed pipeline view (`pipeline_name`, `pipeline_nodes`, `progress`).",
+      operationId: "listLaneFeatures",
+      parameters: [idParam],
+      responses: { 200: { description: "`{features:[…]}`.", ...json(obj) }, 404: notFound },
+    },
+  },
+  "/api/lanes/{id}/features/{slug}": {
+    get: {
+      tags: ["Lanes"],
+      summary: "One feature of a lane",
+      description: "Including an archived feature's saved pipeline state.",
+      operationId: "getLaneFeature",
+      parameters: [
+        idParam,
+        { name: "slug", in: "path", required: true, schema: { type: "string" } },
+      ],
+      responses: {
+        200: { description: "`{feature}`.", ...json(obj) },
+        404: { description: "ENOLANE or ENOFEATURE." },
+      },
+    },
+  },
+  "/api/lanes/{id}/features/activate": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Switch the lane to a feature",
+      description:
+        "`agenthub feature activate`: archives the outgoing feature's pipeline and clears detection (a detection belongs to the feature that produced it), then makes `slug` the live feature. Broadcasts `lane_update`. Same-origin.",
+      operationId: "activateLaneFeature",
+      parameters: [idParam],
+      requestBody: {
+        required: true,
+        ...json({
+          type: "object",
+          required: ["slug"],
+          properties: { slug: { type: "string" }, title: { type: "string" } },
+        }),
+      },
+      responses: {
+        200: { description: "`{lane, feature}`.", ...json(obj) },
+        400: { description: "EBADSLUG." },
+        403: crossOrigin,
+        404: notFound,
+      },
+    },
+  },
+  "/api/lanes/{id}/proof": {
+    get: {
+      tags: ["Lanes"],
+      summary: "List a lane's proof screenshots",
+      description:
+        "Feature slugs under the lane's proof root (`.playwright-mcp/proof`), plus activated features with no proof yet; most recently touched first.",
+      operationId: "listLaneProof",
+      parameters: [idParam],
+      responses: {
+        200: {
+          description: "`{features:[{slug, groups:{<group>:[image]}, ticket_report, mtime}]}`.",
+          ...json(obj),
+        },
+        404: notFound,
+      },
+    },
+  },
+  "/api/lanes/{id}/proof/{slug}": {
+    delete: {
+      tags: ["Lanes"],
+      summary: "Delete proof screenshots",
+      description:
+        "Body `{group, images}` unlinks those images (and an emptied group dir); `{group}` removes the whole group; no body removes every group except `ticket/`. Containment-checked to the proof root. Same-origin; S3 guard.",
+      operationId: "deleteLaneProof",
+      parameters: [
+        idParam,
+        { name: "slug", in: "path", required: true, schema: { type: "string" } },
+      ],
+      requestBody: json({
+        type: "object",
+        properties: {
+          group: { type: "string" },
+          images: { type: "array", items: { type: "string" } },
+        },
+      }),
+      responses: {
+        200: { description: "`{deleted}` — number of files removed.", ...json(obj) },
+        400: { description: "EBADPATH." },
+        403: s3Refused,
+        404: { description: "ENOLANE or ENOFEATURE." },
+      },
+    },
+  },
+  "/api/lanes/{id}/proof/{slug}/{group}/{file}": {
+    get: {
+      tags: ["Lanes"],
+      summary: "Serve one proof file",
+      description:
+        "A proof image or the ticket's REPORT.html, containment-checked (no traversal or symlink escape, image/HTML extensions only). Plain-text `not found` otherwise.",
+      operationId: "getLaneProofFile",
+      parameters: [
+        idParam,
+        { name: "slug", in: "path", required: true, schema: { type: "string" } },
+        { name: "group", in: "path", required: true, schema: { type: "string" } },
+        { name: "file", in: "path", required: true, schema: { type: "string" } },
+      ],
+      responses: {
+        200: { description: "The file (`text/html`, `image/png` or `image/jpeg`)." },
+        404: { description: "Lane or file not found." },
+      },
+    },
+  },
+  "/api/lanes/{id}/proof-link": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Converge the lane's proof/ onto .playwright-mcp/proof",
+      description:
+        "Merges a real `proof/` dir into the canonical root and replaces it with a relative symlink; idempotent, never clobbers a stray file named `proof`. Never automatic (`agenthub lanes proof-link`). Same-origin; S3 guard.",
+      operationId: "linkLaneProof",
+      parameters: [idParam],
+      responses: {
+        200: { description: "`{linked}` — false when nothing changed.", ...json(obj) },
+        403: s3Refused,
+        404: notFound,
+      },
+    },
+  },
+  "/api/lanes/{id}/mcp/sync": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Give the lane its source repo's MCP servers",
+      description:
+        "Relocates the source repo's configured `mcpServers` (from ~/.claude.json) into `<lane>/.mcp.json` (git-excluded), pins Playwright's output dir, seeds Chromium profiles. Never touches permissions or settings.local.json. Same-origin; S3 guard.",
+      operationId: "syncLaneMcp",
+      parameters: [idParam],
+      responses: {
+        200: { description: "`{servers:[name], profilesSeeded:[name]}`.", ...json(obj) },
+        400: { description: "ENOMCPCONFIG — the source repo has no MCP config." },
+        403: s3Refused,
+        404: notFound,
+        500: { description: "ERUNTIME." },
+      },
+    },
+  },
+  "/api/lanes/{id}/profile/init": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Scaffold .agenthub/profile/ for a detected Node.js project",
+      description:
+        "Always targets the lane's own folder. No detectable Node.js project is a normal 200 (`scaffolded:false`). Same-origin; S3 guard.",
+      operationId: "initLaneProfile",
+      parameters: [idParam],
+      requestBody: json({
+        type: "object",
+        properties: { force: { type: "boolean", description: "Overwrite an existing profile." } },
+      }),
+      responses: {
+        200: {
+          description: "`{scaffolded:true, written, todos}` or `{scaffolded:false, reason}`.",
+          ...json(obj),
+        },
+        400: { description: "EPROFILEEXISTS (without `force`)." },
+        403: s3Refused,
+        404: notFound,
+      },
+    },
+  },
+  "/api/lanes/{id}/integrations/{name}": {
+    get: {
+      tags: ["Lanes"],
+      summary: "Whether a profile integration is enabled",
+      description:
+        "Reads `<NAME>_ENABLED` from `.agenthub/profile/integrations.env` in the lane folder or its source repo. Read-only.",
+      operationId: "laneIntegrationEnabled",
+      parameters: [
+        idParam,
+        {
+          name: "name",
+          in: "path",
+          required: true,
+          schema: { type: "string" },
+          example: "tracker",
+        },
+      ],
+      responses: { 200: { description: "`{enabled}`.", ...json(obj) }, 404: notFound },
+    },
+  },
+  "/api/lanes/{id}/ci/status": {
+    get: {
+      tags: ["Lanes"],
+      summary: "GitHub Actions status snapshot for a ref",
+      description:
+        "One `gh` read for a branch or sha in the lane's repo — not a poll loop; the caller owns any wait/retry. Read-only.",
+      operationId: "laneCiStatus",
+      parameters: [
+        idParam,
+        { name: "ref", in: "query", required: true, schema: { type: "string" } },
+      ],
+      responses: {
+        200: {
+          description: "`{state, ref, checks:[…]}` (`pending` with no checks yet).",
+          ...json(obj),
+        },
+        400: { description: "EBADREF — ref is required." },
+        404: notFound,
+        500: { description: "ERUNTIME (gh failed)." },
+      },
+    },
+  },
+  "/api/lanes/{id}/sync-base": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Merge the base branch into the feature branch (gated)",
+      description:
+        "The one sanctioned merge of the ship-feature pipeline: fetch, a migration-number collision preflight, then merge — under the lane lock, synchronously. Every documented outcome is 200 with `code`: 0 (ok; `check` adds `devDelta`/`overlap`), 4 (conflict left in place, `conflictedFiles`), 5 (migration collision, `collisions`). Requires a lane profile. Never writes stage/status/notes. Same-origin; S3 guard.",
+      operationId: "syncLaneBase",
+      parameters: [idParam],
+      requestBody: json({
+        type: "object",
+        properties: {
+          mode: { type: "string", enum: ["check", "merge", "continue"], default: "merge" },
+          branch: { type: "string" },
+        },
+      }),
+      responses: {
+        200: { description: "`{code, …}` as above.", ...json(obj) },
+        400: {
+          description:
+            "ENOPROFILE, EBADBRANCH, EUNRESOLVED, EMERGEUNCOMMITTED or another runtime input code.",
+        },
+        403: s3Refused,
+        404: notFound,
+        500: { description: "ERUNTIME." },
+      },
+    },
+  },
+  "/api/lanes/{id}/session-worktree/remove": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Remove a session's `claude --worktree` tree",
+      description:
+        "The one dashboard path that deletes a worktree: resolved from the session row (`sessionWorktree`), never a path. `git worktree remove` without `--force`, then `git branch -d` (never `-D`) when git agrees the branch is merged — else the branch is kept and reported. Refused while a live pane holds the session. Same-origin.",
+      operationId: "removeSessionWorktree",
+      parameters: [idParam],
+      requestBody: {
+        required: true,
+        ...json({
+          type: "object",
+          required: ["session", "confirm"],
+          properties: { session: { type: "string" }, confirm: { type: "boolean", enum: [true] } },
+        }),
+      },
+      responses: {
+        200: { description: "`{removed:true, branch, branchKept}`.", ...json(obj) },
+        400: { description: "ECONFIRM or ENOWORKTREE." },
+        403: crossOrigin,
+        404: notFound,
+        409: {
+          description:
+            "ELIVE (a pane holds the session), ELOCKED, or EGIT (git refused, e.g. a dirty tree).",
+        },
+      },
+    },
+  },
+  "/api/lanes/{id}/sources": {
+    get: {
+      tags: ["Lanes"],
+      summary: "A workspace's instructions, extra folders and context files",
+      operationId: "getLaneSources",
+      parameters: [idParam],
+      responses: {
+        200: { description: "The context view.", ...json(SOURCES_VIEW) },
+        404: notFound,
+      },
+    },
+  },
+  "/api/lanes/{id}/instructions": {
+    put: {
+      tags: ["Lanes"],
+      summary: "Set a workspace's instructions",
+      description:
+        "Stored on the lane row and given to every new Claude/Codex pane at spawn (never written into the repo). `null` clears. Capped at `maxInstructions`. Broadcasts `lane_update`. Same-origin.",
+      operationId: "setLaneInstructions",
+      parameters: [idParam],
+      requestBody: {
+        required: true,
+        ...json({
+          type: "object",
+          required: ["instructions"],
+          properties: { instructions: { type: "string", nullable: true } },
+        }),
+      },
+      responses: {
+        200: { description: "The context view.", ...json(SOURCES_VIEW) },
+        ...sourcesErrors,
+      },
+    },
+  },
+  "/api/lanes/{id}/sources/folder": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Add an extra folder",
+      description:
+        "An absolute, existing directory that is not (and does not contain) the OS home and is not the workspace's own folder. A developer may name only folders in their own (checked before the path is probed, and again on the real path). The folder stays the user's — AgentHub never deletes it. Same-origin.",
+      operationId: "addLaneSourceFolder",
+      parameters: [idParam],
+      requestBody: {
+        required: true,
+        ...json({ type: "object", required: ["path"], properties: { path: { type: "string" } } }),
+      },
+      responses: {
+        201: { description: "The context view.", ...json(SOURCES_VIEW) },
+        ...sourcesErrors,
+      },
+    },
+  },
+  "/api/lanes/{id}/sources/file": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Upload a context file",
+      description:
+        "Raw bytes (≤ 10 MB) with the name in the `X-File-Name` header (URI-encoded). Stored under `<data dir>/workspace-context/<lane id>/` under a name AgentHub derives. Same-origin.",
+      operationId: "addLaneSourceFile",
+      parameters: [
+        idParam,
+        { name: "X-File-Name", in: "header", required: true, schema: { type: "string" } },
+      ],
+      requestBody: {
+        required: true,
+        content: { "application/octet-stream": { schema: { type: "string", format: "binary" } } },
+      },
+      responses: {
+        201: { description: "The context view.", ...json(SOURCES_VIEW) },
+        ...sourcesErrors,
+        413: { description: "ETOOBIG — over 10 MB." },
+      },
+    },
+  },
+  "/api/lanes/{id}/sources/clone": {
+    post: {
+      tags: ["Lanes"],
+      summary: "Clone a repo as an extra folder",
+      description:
+        "Clones `url` (the `publish` URL allowlist; run as the folder's account with that account's own git identity) BESIDE the workspace folder — no path from the request — then adds it as an extra folder. The clone is the user's; removing the source never deletes it. Same-origin.",
+      operationId: "cloneLaneSource",
+      parameters: [idParam],
+      requestBody: {
+        required: true,
+        ...json({
+          type: "object",
+          required: ["url"],
+          properties: {
+            url: { type: "string" },
+            name: { type: "string", description: "Folder name; default derived from the URL." },
+            credentials: {
+              type: "object",
+              additionalProperties: true,
+              description: "A typed HTTPS login for this one clone.",
+            },
+          },
+        }),
+      },
+      responses: {
+        201: { description: "The context view plus `path` (the clone).", ...json(obj) },
+        400: {
+          description:
+            "EUNSUPPORTED (tool takes no extra folders), a URL/name refusal, or a source check (the clone stays, `path` names it).",
+        },
+        403: { description: "EFOLDER, or not same-origin." },
+        404: notFound,
+        409: {
+          description:
+            "EEXISTS (name taken), ECREDENTIALS / ESSHAUTH (the remote wants a login), ENOREPO, EOWNERFOLDER or EMEMBERGONE.",
+        },
+      },
+    },
+  },
+  "/api/lanes/{id}/sources/{sourceId}": {
+    delete: {
+      tags: ["Lanes"],
+      summary: "Remove an extra folder or context file",
+      description:
+        "Drops the row; for an uploaded file AgentHub also deletes its own stored copy. A folder on disk is never deleted. Same-origin.",
+      operationId: "removeLaneSource",
+      parameters: [
+        idParam,
+        { name: "sourceId", in: "path", required: true, schema: { type: "integer" } },
+      ],
+      responses: {
+        200: { description: "The context view.", ...json(SOURCES_VIEW) },
+        ...sourcesErrors,
+      },
+    },
+  },
+  "/api/lanes/{id}/memory": {
+    get: {
+      tags: ["Lanes"],
+      summary: "The memory files the workspace's agent already reads",
+      description:
+        "Read-only: the folder's CLAUDE.md / .claude/CLAUDE.md / CLAUDE.local.md / AGENTS.md and, for Claude, up to 50 `.md` files of its auto-memory dir `<CLAUDE_HOME>/projects/<encoded cwd>/memory/`. Every path derives from the lane row.",
+      operationId: "getLaneMemory",
+      parameters: [idParam],
+      responses: { 200: { description: "`{files:[…]}`.", ...json(obj) }, 404: notFound },
+    },
+  },
+  "/api/locks": {
+    get: {
+      tags: ["Locks"],
+      summary: "List held named locks",
+      description:
+        "Server mode: a developer sees only their own namespace, with the prefix stripped.",
+      operationId: "listLocks",
+      responses: {
+        200: { description: "`{locks:[{name, holder, since, ageSec}]}`.", ...json(obj) },
+      },
+    },
+  },
+  "/api/locks/{name}/acquire": {
+    post: {
+      tags: ["Locks"],
+      summary: "Try to take a named lock (never waits)",
+      description:
+        "Atomic mkdir under the locks root. A lock held longer than the max hold time is stale and broken. `name` is one plain name (no path). Same-origin.",
+      operationId: "acquireLock",
+      parameters: [{ name: "name", in: "path", required: true, schema: { type: "string" } }],
+      requestBody: {
+        required: true,
+        ...json({
+          type: "object",
+          required: ["holder"],
+          properties: { holder: { type: "string" } },
+        }),
+      },
+      responses: {
+        200: { description: "`{acquired:true}`.", ...json(obj) },
+        400: { description: "EBADNAME or EBADHOLDER." },
+        403: crossOrigin,
+        409: {
+          description: "`{acquired:false, holder, since, ageSec}` — held by someone else.",
+          ...json(obj),
+        },
+      },
+    },
+  },
+  "/api/locks/{name}/release": {
+    post: {
+      tags: ["Locks"],
+      summary: "Release a named lock",
+      description: "Only the recorded holder may release it. Same-origin.",
+      operationId: "releaseLock",
+      parameters: [{ name: "name", in: "path", required: true, schema: { type: "string" } }],
+      requestBody: {
+        required: true,
+        ...json({
+          type: "object",
+          required: ["holder"],
+          properties: { holder: { type: "string" } },
+        }),
+      },
+      responses: {
+        200: { description: "`{ok:true}`.", ...json(obj) },
+        400: { description: "EBADNAME or EBADHOLDER." },
+        403: crossOrigin,
+        404: { description: "ENOLOCK — not held." },
+        409: { description: "ENOTHOLDER — `error.currentHolder` names the owner." },
+      },
+    },
+  },
+  "/api/projects": {
+    get: {
+      tags: ["Projects"],
+      summary: "Workspaces grouped by git repository",
+      description:
+        "Each project: `{root, name, workspaces:[id], worktrees:[{path, branch, main, workspace_id, source?}]}` (`source` is `claude` for a `.claude/worktrees` tree, `agenthub` under LANES_ROOT); non-repo folders last as `Folders` (`root:null`). Roots and `git worktree list` are cached in memory (worktrees 30 s). Read on demand, never polled. Server mode: a developer's own workspaces, without worktrees another user's workspace sits on.",
+      operationId: "listProjects",
+      responses: { 200: { description: "`{projects:[…]}`.", ...json(obj) } },
+    },
+  },
+  "/api/projects/refresh": {
+    post: {
+      tags: ["Projects"],
+      summary: "Drop the project caches and list again",
+      operationId: "refreshProjects",
+      responses: {
+        200: { description: "`{projects:[…]}`.", ...json(obj) },
+        403: crossOrigin,
+      },
+    },
+  },
+};
+
+module.exports = { tags, schemas: {}, paths };
@@ -6,7 +6,8 @@
 * `LaneStageDetectionFields` schema for the stage-detection fields every lane
 * response carries, and the idempotent `POST /api/lanes/ensure` lookup the
 * Workspace page opens a directory with, and the Files tab's reads (tree,
- * quick-open, download — also in a folder that is not a git repo) and upload.
+ * quick-open, download — also in a folder that is not a git repo) and upload,
+ * one lane's GET/DELETE, and the editor's whole-file save.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

@@ -299,6 +300,30 @@ const paths = {
    },
  },
  "/api/lanes/{id}": {
+    get: {
+      tags: ["Lanes"],
+      summary: "One workspace",
+      description: "The same lane payload `GET /api/lanes` lists.",
+      operationId: "getLane",
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
+      responses: {
+        200: { description: "`{lane}`." },
+        404: { description: "ENOLANE — workspace not found." },
+      },
+    },
+    delete: {
+      tags: ["Lanes"],
+      summary: "Delete a workspace row",
+      description:
+        "Deletes the lane row only (its `lane_sources` rows cascade, and AgentHub's own copies of uploaded context files go with them). Stops nothing and never touches the folder, worktree or branch — `POST /api/lanes/{id}/remove` is the UI's path that also stops runs and stacks. Broadcasts `lane_update` with `{removed: id}`. Same-origin.",
+      operationId: "deleteLane",
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
+      responses: {
+        200: { description: "`{ok: true}`." },
+        403: { description: "The browser request was not same-origin." },
+        404: { description: "ENOLANE — workspace not found." },
+      },
+    },
    patch: {
      tags: ["Lanes"],
      summary: "Partially update a lane",
@@ -635,6 +660,37 @@ const paths = {
        404: { description: "Lane not found." },
      },
    },
+    put: {
+      tags: ["Lanes"],
+      summary: "Save one text file from the viewer's editor",
+      description:
+        "lane-file-write.js: the read path's guards (lane confinement, secret refusal) plus existing-text-file-only (never creates a file or touches a binary) and a `baseSha` stale check. Answers the file re-read at rev `work`, fresh `sha` included. Same-origin.",
+      operationId: "writeLaneFile",
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
+      requestBody: {
+        required: true,
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              required: ["path", "content", "baseSha"],
+              properties: {
+                path: { type: "string" },
+                content: { type: "string" },
+                baseSha: { type: "string", description: "The `sha` the file was opened at." },
+              },
+            },
+          },
+        },
+      },
+      responses: {
+        200: { description: "`{available: true, …}` — the same shape as the GET." },
+        400: { description: "EBADPATH, ENOFILE, EBADCONTENT, ETOOBIG or EBINARY." },
+        403: { description: "ESECRET or EFOREIGN, or not same-origin." },
+        404: { description: "Lane not found." },
+        409: { description: "ESTALE — the file changed since `baseSha`." },
+      },
+    },
  },
  "/api/lanes/{id}/git/blame": {
    get: {
@@ -0,0 +1,798 @@
+/**
+ * @file OpenAPI fragment for the AI-tool configuration routes the base spec
+ * and the other fragments left out: AI Proxy profiles (`/api/ai-proxies`, also
+ * mounted at the pre-rename `/api/ai-routers`), the non-Claude login profiles
+ * (`/api/tool-profiles`), a tool's catalog-listed config files, model list and
+ * usage (`/api/ai-tools/{id}/…`), the Claude plugin/marketplace CLI routes and
+ * project-memory bootstrap under `/api/cc-config` (plus its Codex twin), and
+ * AgentHub's own git credential store (`/api/git-credentials`). No operation
+ * here returns key material — profiles and credentials report `hasKey` /
+ * `hasToken` only. Exports `{ tags, schemas, paths }` for
+ * server/openapi-extra.js.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const tags = [
+  {
+    name: "AI Proxies",
+    description:
+      "AI Proxy profiles (endpoint + key + model) a new Claude/Codex session may name. Also mounted at /api/ai-routers. No route returns a key.",
+  },
+  {
+    name: "Tool Profiles",
+    description:
+      "Saved login profiles of the AI tools other than Claude Code (Codex, Oh My Pi). Identity metadata only, never a token.",
+  },
+  {
+    name: "Git Credentials",
+    description:
+      "AgentHub's own git credential store (one login per protocol + host). Passwords go in, never out.",
+  },
+];
+
+const err = { $ref: "#/components/schemas/ErrorResponse" };
+const json = (schema, description) => ({
+  description,
+  content: { "application/json": { schema } },
+});
+const errResp = (description) => json(err, description);
+const body = (schema, required = true) => ({
+  required,
+  content: { "application/json": { schema } },
+});
+
+const schemas = {
+  AiProxyProfile: {
+    type: "object",
+    description:
+      "The browser-safe view of a profile: every stored field except the key, plus `hasKey` and `scope`.",
+    properties: {
+      name: { type: "string", description: "Server-made slug; never changes once saved." },
+      label: { type: "string" },
+      baseUrl: { type: "string", description: "The proxy's ROOT (a trailing /v1 is dropped)." },
+      model: { type: "string" },
+      models: { type: "object", additionalProperties: { type: "string" } },
+      behavesAs: {
+        type: "string",
+        description: "User-chosen Claude model the proxy model acts as; empty when unset.",
+      },
+      savedAt: { type: "string", format: "date-time" },
+      builtin: { type: "boolean", description: "True only for the built-in `native` profile." },
+      scope: { type: "string", enum: ["shared", "personal"] },
+      hasKey: { type: "boolean" },
+    },
+  },
+  AiProxyWriteRequest: {
+    type: "object",
+    properties: {
+      label: { type: "string" },
+      baseUrl: { type: "string" },
+      apiKey: {
+        type: "string",
+        description: "Write-only. On PATCH an omitted/blank key keeps the stored one.",
+      },
+      model: { type: "string" },
+      models: { type: "object", additionalProperties: { type: "string" } },
+      behavesAs: { type: "string" },
+      scope: {
+        type: "string",
+        enum: ["shared", "personal"],
+        description:
+          "POST only (server mode). `shared` is admin-only; a non-admin always writes a personal profile.",
+      },
+    },
+  },
+  AiProxyTestResult: {
+    type: "object",
+    properties: {
+      ok: { type: "boolean" },
+      status: {
+        type: "integer",
+        nullable: true,
+        description: "HTTP status the proxy answered with; null when unreachable.",
+      },
+      message: {
+        type: "string",
+        description:
+          "The model id on success, else up to 300 chars of the proxy's reply or the transport error.",
+      },
+    },
+  },
+  ToolProfileIdentity: {
+    type: "object",
+    properties: {
+      kind: { type: "string" },
+      email: { type: "string", nullable: true },
+      detail: { type: "string", nullable: true },
+    },
+  },
+  ToolProfileItem: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      label: { type: "string" },
+      savedAt: { type: "integer", nullable: true, description: "Epoch ms." },
+      active: { type: "boolean", description: "This profile holds the login that is live now." },
+      kind: { type: "string" },
+      email: { type: "string", nullable: true },
+      detail: { type: "string", nullable: true },
+    },
+  },
+  ToolProfilesListResponse: {
+    type: "object",
+    properties: {
+      tools: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            tool: { type: "string", example: "codex" },
+            supported: { type: "boolean" },
+            reason: {
+              type: "string",
+              description: "Why the tool cannot be switched (supported: false).",
+            },
+            items: { type: "array", items: { $ref: "#/components/schemas/ToolProfileItem" } },
+            active: {
+              allOf: [{ $ref: "#/components/schemas/ToolProfileIdentity" }],
+              nullable: true,
+            },
+            error: { allOf: [{ $ref: "#/components/schemas/ErrorObject" }], nullable: true },
+          },
+        },
+      },
+    },
+  },
+  ToolProfileNameRequest: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "Profile name (`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,39}$`)." },
+      label: { type: "string", description: "PATCH only: the new display label." },
+    },
+  },
+  GitCredentialItem: {
+    type: "object",
+    properties: {
+      protocol: { type: "string", enum: ["http", "https"] },
+      host: { type: "string", example: "git.example.com" },
+      username: { type: "string" },
+      savedAt: { type: "string" },
+      hasToken: { type: "boolean", enum: [true] },
+    },
+  },
+  GitCredentialsListResponse: {
+    type: "object",
+    properties: {
+      items: { type: "array", items: { $ref: "#/components/schemas/GitCredentialItem" } },
+    },
+  },
+  CcConfigCliResult: {
+    type: "object",
+    description:
+      "A finished `claude plugin …` run. A non-zero exit answers 422 `ECLIEXIT` with `code`, `stdout`, `stderr` beside the error.",
+    properties: {
+      ok: { type: "boolean", enum: [true] },
+      stdout: { type: "string" },
+      stderr: { type: "string" },
+    },
+  },
+  ProjectMemoryCreateRequest: {
+    type: "object",
+    required: ["dir", "content"],
+    properties: {
+      dir: { type: "string", description: "Absolute path of an existing directory." },
+      content: { type: "string", description: "File text, at most 1 MB." },
+    },
+  },
+  ProjectMemoryCreateResponse: {
+    type: "object",
+    properties: {
+      file: { type: "string" },
+      size: { type: "integer" },
+      created: { type: "boolean", enum: [true] },
+    },
+  },
+};
+
+const cliErrors = {
+  400: errResp("`EBADARG` (invalid identifier, source or scope) or `EBADACTION`."),
+  422: errResp(
+    "The CLI exited non-zero (`ECLIEXIT`); the body also carries `code`, `stdout`, `stderr`."
+  ),
+  502: errResp("`ECLIFAILED`."),
+  503: errResp("`ECLINOTFOUND` — no `claude` binary."),
+  504: errResp("`ETIMEOUT`."),
+};
+const cliOk = json(
+  { $ref: "#/components/schemas/CcConfigCliResult" },
+  "The CLI succeeded; a `cc_config_changed` WebSocket message is broadcast."
+);
+
+const nameParam = { name: "name", in: "path", required: true, schema: { type: "string" } };
+const toolParam = {
+  name: "tool",
+  in: "path",
+  required: true,
+  schema: { type: "string", example: "codex" },
+  description: "A tool the profiles module covers (`codex`, `omp`).",
+};
+const toolErrors = {
+  400: errResp("`EBADNAME` / `EBADLABEL`."),
+  404: errResp("`EBADTOOL` (unknown tool) or `ENOTFOUND` (no such profile)."),
+  409: errResp(
+    "`EUNSUPPORTED`, `ENOTINSTALLED`, `EBADJSON`, `EACTIVE`, `EUNSAVED`, `ENOAUTH`, `EDUPLICATE` or `ELABELTAKEN`."
+  ),
+  502: errResp("`EOMP` — Oh My Pi's own auth command failed."),
+};
+const toolOk = json(
+  {
+    type: "object",
+    properties: {
+      ok: { type: "boolean", enum: [true] },
+      name: { type: "string" },
+      label: { type: "string" },
+    },
+  },
+  "Done."
+);
+const idParam = {
+  name: "id",
+  in: "path",
+  required: true,
+  schema: { type: "string" },
+  description: "AI Tools catalog id.",
+};
+const indexParam = {
+  name: "index",
+  in: "path",
+  required: true,
+  schema: { type: "integer", minimum: 0 },
+  description: "Index into the tool's catalog-declared `config` list.",
+};
+const configErrors = {
+  400: errResp("`EBADFIELD` (text not a string) or `EBADSYNTAX` (JSON/JSONC/TOML does not parse)."),
+  403: errResp("`ESECRET` — the file (or its symlink target) has a credential-like name."),
+  404: errResp("`ENOTOOL`, `ENOFILE` (no such index) or `ENOENT` (missing / not a regular file)."),
+  409: errResp("`ESTALE` — the file changed since it was opened (PUT)."),
+  413: errResp("`ETOOBIG` — over 1 MB."),
+  415: errResp("`EBINARY` — not a text file."),
+};
+
+const projectMemoryOp = (tool, file, operationId, tag) => ({
+  post: {
+    tags: [tag],
+    summary: `Create ${file} in a project directory`,
+    description: `Creates \`<dir>/${file}\` for a project the dashboard has never run in — the one ${tag} write that takes a caller-chosen directory. \`dir\` must be an absolute, existing directory (resolved with realpath); an existing \`${file}\` — a symlink included — is refused (\`EEXISTS\`), never overwritten. Same-origin guarded; admin-only in server mode. Broadcasts \`${tool === "claude" ? "cc_config_changed" : "codex_config_changed"}\`.`,
+    operationId,
+    requestBody: body({ $ref: "#/components/schemas/ProjectMemoryCreateRequest" }),
+    responses: {
+      200: json({ $ref: "#/components/schemas/ProjectMemoryCreateResponse" }, "Created."),
+      400: errResp("`EBADDIR`, `EBADCONTENT` or `EOUTOFROOT`."),
+      409: errResp("`EEXISTS`."),
+      413: errResp("`ETOOLARGE`."),
+    },
+  },
+});
+
+const paths = {
+  "/api/ai-proxies": {
+    get: {
+      tags: ["AI Proxies"],
+      summary: "List AI Proxy profiles",
+      description:
+        "Every profile the viewer may choose: the built-in `native` first, then the shared ones, then the viewer's own personal ones (nobody lists another user's personal profiles, an admin included). Never carries a key — `hasKey` only.",
+      operationId: "listAiProxies",
+      responses: {
+        200: json(
+          {
+            type: "object",
+            properties: {
+              items: { type: "array", items: { $ref: "#/components/schemas/AiProxyProfile" } },
+            },
+          },
+          "Profiles."
+        ),
+      },
+    },
+    post: {
+      tags: ["AI Proxies"],
+      summary: "Create an AI Proxy profile",
+      description:
+        'Saves a profile under a server-made name derived from `label`. In server mode a non-admin always creates a PERSONAL profile; `scope: "shared"` from a non-admin is `EADMIN`. Local mode writes the shared store. Same-origin guarded. The response is the browser-safe view (no key).',
+      operationId: "createAiProxy",
+      requestBody: body({ $ref: "#/components/schemas/AiProxyWriteRequest" }),
+      responses: {
+        201: json({ $ref: "#/components/schemas/AiProxyProfile" }, "Created."),
+        400: errResp("`EBADNAME`, `EBADLABEL`, `EBADURL` or `EBADMODEL`."),
+        403: errResp("`EADMIN` — only an admin may write a shared profile."),
+        409: errResp("`EBUILTIN` (the name `native`) or `EBADJSON`."),
+      },
+    },
+  },
+  "/api/ai-proxies/9router": {
+    get: {
+      tags: ["AI Proxies"],
+      summary: "Is 9router installed",
+      description:
+        "Reports whether a `9router` binary is on the server's login-shell PATH, so Settings can offer a link to its own UI. A file lookup only; nothing is spawned.",
+      operationId: "getAiProxy9router",
+      responses: {
+        200: json(
+          { type: "object", properties: { installed: { type: "boolean" } } },
+          "Lookup result."
+        ),
+      },
+    },
+  },
+  "/api/ai-proxies/test": {
+    post: {
+      tags: ["AI Proxies"],
+      summary: "Test an AI Proxy endpoint",
+      description:
+        "Probes `<baseUrl>/v1/messages` (Claude Code's shape, 1 output token) and `<baseUrl>/v1/responses` (Codex's, 16 tokens) in parallel, 15 s timeout, redirects not followed. A reachable proxy is a 200 whatever it replies. A blank `apiKey` falls back to the stored key of profile `name` ONLY while the submitted `baseUrl` equals the saved one (and only for the profile's owner); otherwise `EBADKEY`. The key is never echoed. Same-origin guarded.",
+      operationId: "testAiProxy",
+      requestBody: body({
+        type: "object",
+        required: ["baseUrl", "model"],
+        properties: {
+          baseUrl: { type: "string" },
+          model: { type: "string" },
+          apiKey: { type: "string" },
+          name: { type: "string", description: "Saved profile whose key to fall back to." },
+        },
+      }),
+      responses: {
+        200: json(
+          {
+            type: "object",
+            properties: {
+              claude: { $ref: "#/components/schemas/AiProxyTestResult" },
+              codex: { $ref: "#/components/schemas/AiProxyTestResult" },
+            },
+          },
+          "Probe outcomes."
+        ),
+        400: errResp("`EBADKEY` (no key to test with), `EBADURL` or `EBADMODEL`."),
+      },
+    },
+  },
+  "/api/ai-proxies/{name}": {
+    patch: {
+      tags: ["AI Proxies"],
+      summary: "Update an AI Proxy profile",
+      description:
+        "Merges the given fields; the name never changes and an omitted/blank `apiKey` keeps the stored one. Also rewrites the per-session settings files that copy this profile, so a rotated key reaches live sessions. A personal profile is writable only by its owner (anyone else gets 404); a shared one only by an admin. Same-origin guarded.",
+      operationId: "updateAiProxy",
+      parameters: [nameParam],
+      requestBody: body({ $ref: "#/components/schemas/AiProxyWriteRequest" }),
+      responses: {
+        200: json({ $ref: "#/components/schemas/AiProxyProfile" }, "Updated."),
+        400: errResp("`EBADLABEL`, `EBADURL` or `EBADMODEL`."),
+        403: errResp("`EADMIN`."),
+        404: errResp("`ENOTFOUND`."),
+        409: errResp("`EBUILTIN` or `EBADJSON`."),
+      },
+    },
+    delete: {
+      tags: ["AI Proxies"],
+      summary: "Delete an AI Proxy profile",
+      description:
+        "Removes the profile and the per-session files that copy its key. Same ownership rules as PATCH. Same-origin guarded.",
+      operationId: "deleteAiProxy",
+      parameters: [nameParam],
+      responses: {
+        200: json({ type: "object", properties: { removed: { type: "string" } } }, "Removed."),
+        403: errResp("`EADMIN`."),
+        404: errResp("`ENOTFOUND`."),
+        409: errResp("`EBUILTIN`."),
+      },
+    },
+  },
+
+  "/api/tool-profiles": {
+    get: {
+      tags: ["Tool Profiles"],
+      summary: "List login profiles of every non-Claude tool",
+      description:
+        "One entry per covered tool. A tool that cannot be switched (Antigravity keeps its login in the OS keyring) is `supported: false` with a `reason`; one tool failing (Oh My Pi not installed) sets that entry's `error` without hiding the others. Identity metadata only, never a token. Staff-only in server mode. Claude's own profiles are `/api/cc-config/profiles`.",
+      operationId: "listToolProfiles",
+      responses: {
+        200: json({ $ref: "#/components/schemas/ToolProfilesListResponse" }, "Profiles by tool."),
+      },
+    },
+  },
+  "/api/tool-profiles/{tool}": {
+    post: {
+      tags: ["Tool Profiles"],
+      summary: "Save the tool's live login as a profile",
+      description:
+        "Snapshots the login the tool holds right now (Codex: `auth.json`; Oh My Pi: `omp auth export`). Without `name`, re-saves into the login's own profile or picks a free name. A second copy of the same account is `EDUPLICATE`; no live login is `ENOAUTH`. Same-origin guarded; admin-only in server mode.",
+      operationId: "saveToolProfile",
+      parameters: [toolParam],
+      requestBody: body({ $ref: "#/components/schemas/ToolProfileNameRequest" }, false),
+      responses: { 200: toolOk, ...toolErrors },
+    },
+    patch: {
+      tags: ["Tool Profiles"],
+      summary: "Rename a tool login profile",
+      description:
+        "Changes the display `label` of profile `name` (`ELABELTAKEN` when another profile already uses it).",
+      operationId: "renameToolProfile",
+      parameters: [toolParam],
+      requestBody: body({ $ref: "#/components/schemas/ToolProfileNameRequest" }),
+      responses: { 200: toolOk, ...toolErrors },
+    },
+    delete: {
+      tags: ["Tool Profiles"],
+      summary: "Delete a tool login profile",
+      description:
+        "Deletes profile `name` (body). The saved copy of the login in use right now is not deletable (`EACTIVE`).",
+      operationId: "deleteToolProfile",
+      parameters: [toolParam],
+      requestBody: body({ $ref: "#/components/schemas/ToolProfileNameRequest" }),
+      responses: {
+        200: json(
+          { type: "object", properties: { ok: { type: "boolean" }, name: { type: "string" } } },
+          "Deleted."
+        ),
+        ...toolErrors,
+      },
+    },
+  },
+  "/api/tool-profiles/{tool}/activate": {
+    post: {
+      tags: ["Tool Profiles"],
+      summary: "Switch the tool to a saved login",
+      description:
+        "Makes profile `name` the tool's live login. The outgoing login is first saved back into its own profile; switching away from a login that was never saved is refused (`EUNSAVED`). Changes the HOST's login — admin-only in server mode, same-origin guarded.",
+      operationId: "activateToolProfile",
+      parameters: [toolParam],
+      requestBody: body({ $ref: "#/components/schemas/ToolProfileNameRequest" }),
+      responses: {
+        200: json(
+          {
+            type: "object",
+            properties: {
+              ok: { type: "boolean" },
+              name: { type: "string" },
+              savedOutgoing: {
+                type: "string",
+                nullable: true,
+                description: "Profile the outgoing login was saved into.",
+              },
+              written: {
+                type: "array",
+                items: { type: "string" },
+                description: "Files the switch wrote.",
+              },
+            },
+          },
+          "Switched."
+        ),
+        ...toolErrors,
+      },
+    },
+  },
+
+  "/api/ai-tools/{id}/models": {
+    get: {
+      tags: ["AI Tools"],
+      summary: "Model choices for a tool",
+      description:
+        "The models a run of this tool offers, from the tool's own source (Claude's and Codex's lists, else the catalog file's, plus models seen in its recorded token usage), and the user's chosen default. `flag` is false when the tool takes no model flag.",
+      operationId: "getAiToolModels",
+      parameters: [idParam],
+      responses: {
+        200: json(
+          {
+            type: "object",
+            properties: {
+              flag: { type: "boolean" },
+              models: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string" },
+                    label: { type: "string" },
+                    hint: { type: "string" },
+                  },
+                },
+              },
+              defaultModel: { type: "string", nullable: true },
+            },
+          },
+          "Models."
+        ),
+        404: errResp("`ENOTOOL`."),
+      },
+    },
+  },
+  "/api/ai-tools/{id}/usage": {
+    get: {
+      tags: ["AI Tools"],
+      summary: "How much a tool has been used",
+      description:
+        "Count of the tool's sessions and the priced cost of their token usage (same `calculateCost` as everywhere else). A developer in server mode sees only their own sessions.",
+      operationId: "getAiToolUsage",
+      parameters: [idParam],
+      responses: {
+        200: json(
+          {
+            type: "object",
+            properties: { sessions: { type: "integer" }, cost: { type: "number" } },
+          },
+          "Usage."
+        ),
+        404: errResp("`ENOTOOL`."),
+      },
+    },
+  },
+  "/api/ai-tools/{id}/config": {
+    get: {
+      tags: ["AI Tools"],
+      summary: "List a tool's editable config files",
+      description:
+        "The `config` files a RELEASE catalog file declares for this tool (never `DASHBOARD_AI_TOOLS_DIR`), resolved under the home directory, with whether each exists. Staff-only in server mode (they may hold keys).",
+      operationId: "listAiToolConfig",
+      parameters: [idParam],
+      responses: {
+        200: json(
+          {
+            type: "object",
+            properties: {
+              files: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    index: { type: "integer" },
+                    path: { type: "string" },
+                    format: { type: "string", example: "json" },
+                    exists: { type: "boolean" },
+                    size: { type: "integer", nullable: true },
+                  },
+                },
+              },
+            },
+          },
+          "Declared files."
+        ),
+        404: errResp("`ENOTOOL`."),
+      },
+    },
+  },
+  "/api/ai-tools/{id}/config/{index}": {
+    get: {
+      tags: ["AI Tools"],
+      summary: "Read one config file",
+      description:
+        "Returns the text of an existing regular text file ≤ 1 MB from the tool's declared list, with its sha to save against. Refuses a credential-named file (`ESECRET`, checked on the basename and its symlink target). The guard is by name only — a settings file may still contain an API key and is returned whole. Staff-only in server mode.",
+      operationId: "readAiToolConfig",
+      parameters: [idParam, indexParam],
+      responses: {
+        200: json(
+          {
+            type: "object",
+            properties: {
+              path: { type: "string" },
+              format: { type: "string" },
+              text: { type: "string" },
+              sha: { type: "string" },
+            },
+          },
+          "File text."
+        ),
+        ...configErrors,
+      },
+    },
+    put: {
+      tags: ["AI Tools"],
+      summary: "Save one config file",
+      description:
+        "Overwrites an EXISTING declared file (never creates one) only when `baseSha` matches the file on disk (`ESTALE` otherwise); JSON/JSONC/TOML text must parse. The old text is backed up under `<data dir>/ai-tool-config-backups/` first. Same-origin guarded; admin-only in server mode.",
+      operationId: "writeAiToolConfig",
+      parameters: [idParam, indexParam],
+      requestBody: body({
+        type: "object",
+        required: ["text", "baseSha"],
+        properties: { text: { type: "string" }, baseSha: { type: "string" } },
+      }),
+      responses: {
+        200: json(
+          { type: "object", properties: { sha: { type: "string" }, backup: { type: "string" } } },
+          "Saved."
+        ),
+        ...configErrors,
+      },
+    },
+  },
+
+  "/api/cc-config/plugins/available": {
+    get: {
+      tags: ["CcConfig"],
+      summary: "List installable plugins",
+      description:
+        "Runs `claude plugin list --available --json` (30 s timeout) and returns its installed and available lists. Read-only; skips the CLI mutation queue.",
+      operationId: "ccConfigListAvailablePlugins",
+      responses: {
+        200: json(
+          {
+            type: "object",
+            properties: {
+              installed: { type: "array", items: { type: "object" } },
+              available: { type: "array", items: { type: "object" } },
+            },
+          },
+          "CLI output."
+        ),
+        502: errResp("`ECLIFAILED` — the CLI failed or printed unparseable JSON."),
+        503: errResp("`ECLINOTFOUND`."),
+        504: errResp("`ETIMEOUT`."),
+      },
+    },
+  },
+  "/api/cc-config/plugins/install": {
+    post: {
+      tags: ["CcConfig"],
+      summary: "Install a plugin",
+      description:
+        "Runs `claude plugin install <spec> --scope <scope> -y` as an argv array on the serialized CLI queue. `spec` is `<name>` or `<name>@<marketplace>`; `scope` is `user`, `project` or `local`. Admin-only in server mode.",
+      operationId: "ccConfigInstallPlugin",
+      requestBody: body({
+        type: "object",
+        required: ["spec", "scope"],
+        properties: {
+          spec: { type: "string" },
+          scope: { type: "string", enum: ["user", "project", "local"] },
+        },
+      }),
+      responses: { 200: cliOk, ...cliErrors },
+    },
+  },
+  "/api/cc-config/plugins/action": {
+    post: {
+      tags: ["CcConfig"],
+      summary: "Enable, disable, update or uninstall a plugin",
+      description:
+        "Runs `claude plugin <action> <key>` (`update` adds `-y`). With `reload: true` and a successful run, `/reload-plugins` + `/reload-skills` are typed into the open Claude lane panes (`reloaded` in the response); a failed reload never fails the action. Admin-only in server mode.",
+      operationId: "ccConfigPluginAction",
+      requestBody: body({
+        type: "object",
+        required: ["key", "action"],
+        properties: {
+          key: { type: "string", example: "agenthub@agenthub" },
+          action: { type: "string", enum: ["enable", "disable", "update", "uninstall"] },
+          reload: { type: "boolean" },
+        },
+      }),
+      responses: {
+        200: json(
+          {
+            allOf: [
+              { $ref: "#/components/schemas/CcConfigCliResult" },
+              {
+                type: "object",
+                properties: {
+                  reloaded: { type: "object", description: "Reload outcome, when requested." },
+                },
+              },
+            ],
+          },
+          "The CLI succeeded."
+        ),
+        ...cliErrors,
+      },
+    },
+  },
+  "/api/cc-config/marketplaces/add": {
+    post: {
+      tags: ["CcConfig"],
+      summary: "Add a plugin marketplace",
+      description:
+        "Runs `claude plugin marketplace add <source> --scope <scope>`. `source` is `owner/repo`, an http(s) URL or an absolute path (no `..`, no leading `-`). Admin-only in server mode.",
+      operationId: "ccConfigAddMarketplace",
+      requestBody: body({
+        type: "object",
+        required: ["source", "scope"],
+        properties: {
+          source: { type: "string" },
+          scope: { type: "string", enum: ["user", "project", "local"] },
+        },
+      }),
+      responses: { 200: cliOk, ...cliErrors },
+    },
+  },
+  "/api/cc-config/marketplaces/action": {
+    post: {
+      tags: ["CcConfig"],
+      summary: "Remove or update a plugin marketplace",
+      description:
+        "Runs `claude plugin marketplace remove|update <name>`. Admin-only in server mode.",
+      operationId: "ccConfigMarketplaceAction",
+      requestBody: body({
+        type: "object",
+        required: ["name", "action"],
+        properties: {
+          name: { type: "string" },
+          action: { type: "string", enum: ["remove", "update"] },
+        },
+      }),
+      responses: { 200: cliOk, ...cliErrors },
+    },
+  },
+  "/api/cc-config/project-memory": projectMemoryOp(
+    "claude",
+    "CLAUDE.md",
+    "ccConfigCreateProjectMemory",
+    "CcConfig"
+  ),
+  "/api/codex-config/project-memory": projectMemoryOp(
+    "codex",
+    "AGENTS.md",
+    "codexConfigCreateProjectMemory",
+    "CodexConfig"
+  ),
+
+  "/api/git-credentials": {
+    get: {
+      tags: ["Git Credentials"],
+      summary: "List stored git credentials",
+      description:
+        "One row per protocol + host. Never returns a password — `hasToken` only. Staff-only in server mode.",
+      operationId: "listGitCredentials",
+      responses: {
+        200: json({ $ref: "#/components/schemas/GitCredentialsListResponse" }, "Credentials."),
+      },
+    },
+    post: {
+      tags: ["Git Credentials"],
+      summary: "Save or replace a git credential",
+      description:
+        "Stores a username + password/token for `protocol` (`http`/`https`) + plain `host[:port]` in AgentHub's own store (0600), replacing any record for that key. Same-origin guarded; admin-only in server mode. Returns the updated list.",
+      operationId: "saveGitCredential",
+      requestBody: body({
+        type: "object",
+        required: ["protocol", "host", "username", "password"],
+        properties: {
+          protocol: { type: "string", enum: ["http", "https"] },
+          host: { type: "string" },
+          username: { type: "string" },
+          password: { type: "string", description: "Write-only." },
+        },
+      }),
+      responses: {
+        200: json({ $ref: "#/components/schemas/GitCredentialsListResponse" }, "Saved."),
+        400: errResp("`EBADHOST` or `EBADCRED`."),
+      },
+    },
+  },
+  "/api/git-credentials/{protocol}/{host}": {
+    delete: {
+      tags: ["Git Credentials"],
+      summary: "Delete a git credential",
+      description:
+        "Removes the record for this protocol + host. Same-origin guarded; admin-only in server mode.",
+      operationId: "deleteGitCredential",
+      parameters: [
+        {
+          name: "protocol",
+          in: "path",
+          required: true,
+          schema: { type: "string", enum: ["http", "https"] },
+        },
+        { name: "host", in: "path", required: true, schema: { type: "string" } },
+      ],
+      responses: {
+        200: json(
+          { $ref: "#/components/schemas/GitCredentialsListResponse" },
+          "Deleted; the remaining list."
+        ),
+        400: errResp("`EBADHOST`."),
+        404: errResp("`ENOTFOUND`."),
+      },
+    },
+  },
+};
+
+module.exports = { tags, schemas, paths };
@@ -14,7 +14,8 @@
 * MCP server add/remove delegated to the `claude mcp …` CLI. Every file
 * write is preceded by a timestamped backup; the CLI-delegated writes are
 * not files this server touches directly, so there is nothing to back up —
- * the CLI owns `~/.claude.json`.
+ * the CLI owns `~/.claude.json`. Every write carries `sameOriginGuard`: an
+ * MCP server or a plugin is code Claude Code later runs.
 *
 * Also hosts the auth-profile routes (`/profiles*`) that swap which Anthropic
 * account the local CLI runs as; those carry identity metadata only, never
@@ -199,7 +200,7 @@ router.get("/keybindings", (_req, res) => {
 // PUT /api/cc-config/keybindings — structured overwrite of the user's
 // ~/.claude/keybindings.json. Body: { groups: [{ context, bindings: [{ key,
 // action }] }] }. Backs the file up first and preserves top-level metadata.
-router.put("/keybindings", (req, res) => {
+router.put("/keybindings", sameOriginGuard, (req, res) => {
  const { groups } = req.body || {};
  if (!Array.isArray(groups)) {
    return res
@@ -245,7 +246,7 @@ router.get("/file", (req, res) => {
 // Plugins, MCP, hooks-in-settings, and settings.json files are intentionally
 // not mutable here. See cc-mutate.js for the rationale.

-router.put("/file", (req, res) => {
+router.put("/file", sameOriginGuard, (req, res) => {
  const { scope, type, name, content, project } = req.body || {};
  if (typeof scope !== "string" || typeof type !== "string") {
    return res
@@ -271,7 +272,7 @@ router.put("/file", (req, res) => {
  }
 });

-router.delete("/file", (req, res) => {
+router.delete("/file", sameOriginGuard, (req, res) => {
  const { scope, type, name, project } = req.body || {};
  if (typeof scope !== "string" || typeof type !== "string") {
    return res
@@ -355,7 +356,7 @@ router.get("/plugins/available", async (_req, res) => {
  }
 });

-router.post("/plugins/install", async (req, res) => {
+router.post("/plugins/install", sameOriginGuard, async (req, res) => {
  const { spec, scope } = req.body || {};
  try {
    const result = await ccCli.pluginInstall({ spec, scope });
@@ -372,7 +373,7 @@ const PLUGIN_ACTIONS = {
  uninstall: ccCli.pluginUninstall,
 };

-router.post("/plugins/action", async (req, res) => {
+router.post("/plugins/action", sameOriginGuard, async (req, res) => {
  const { key, action, reload } = req.body || {};
  const run = PLUGIN_ACTIONS[action];
  if (!run) {
@@ -409,7 +410,7 @@ router.post("/plugins/action", async (req, res) => {
 * sessions to re-read what is already there — so it neither queues on the CLI
 * mutation chain nor emits `cc_config_changed`.
 */
-router.post("/reload", async (req, res) => {
+router.post("/reload", sameOriginGuard, async (req, res) => {
  const { kinds } = req.body || {};
  if (kinds !== undefined && !Array.isArray(kinds)) {
    return res.status(400).json({
@@ -436,7 +437,7 @@ router.get("/plugins/update-all", (_req, res) => {
  res.json({ batch: readUpdateAll() });
 });

-router.post("/plugins/update-all", async (req, res) => {
+router.post("/plugins/update-all", sameOriginGuard, async (req, res) => {
  if (isRunning()) {
    return res.status(409).json({
      error: { code: "EBUSY", message: "an update-all batch is already running" },
@@ -481,7 +482,7 @@ router.post("/plugins/update-all", async (req, res) => {
  }
 });

-router.post("/marketplaces/add", async (req, res) => {
+router.post("/marketplaces/add", sameOriginGuard, async (req, res) => {
  const { source, scope } = req.body || {};
  try {
    const result = await ccCli.marketplaceAdd({ source, scope });
@@ -496,7 +497,7 @@ const MARKETPLACE_ACTIONS = {
  update: ccCli.marketplaceUpdate,
 };

-router.post("/marketplaces/action", async (req, res) => {
+router.post("/marketplaces/action", sameOriginGuard, async (req, res) => {
  const { name, action } = req.body || {};
  const run = MARKETPLACE_ACTIONS[action];
  if (!run) {
@@ -523,7 +524,7 @@ router.post("/marketplaces/action", async (req, res) => {
 // /mcp above stays on `readMcpServers`; the client refetches it after either
 // call below succeeds.

-router.post("/mcp/add", async (req, res) => {
+router.post("/mcp/add", sameOriginGuard, async (req, res) => {
  const { name, scope, transport, command, args, url, headers, env } = req.body || {};
  try {
    const result = await ccMcpCli.mcpAdd({
@@ -542,7 +543,7 @@ router.post("/mcp/add", async (req, res) => {
  }
 });

-router.post("/mcp/remove", async (req, res) => {
+router.post("/mcp/remove", sameOriginGuard, async (req, res) => {
  const { name, scope } = req.body || {};
  try {
    const result = await ccMcpCli.mcpRemove({ name, scope });
@@ -560,7 +561,7 @@ router.post("/mcp/remove", async (req, res) => {
 // The project layers resolve against the SERVER's cwd, never `?cwd=`: a write
 // target chosen by the caller would let any request create a settings.json
 // anywhere on disk. Reads keep the override; writes do not.
-router.patch("/settings", (req, res) => {
+router.patch("/settings", sameOriginGuard, (req, res) => {
  const { scope, set, unset } = req.body || {};
  try {
    const result = ccMutate.patchSettings({ scope, cwd: process.cwd(), set, unset });
@@ -607,7 +608,7 @@ router.get("/profiles", async (_req, res) => {
  }
 });

-router.post("/profiles", async (req, res) => {
+router.post("/profiles", sameOriginGuard, async (req, res) => {
  try {
    const owner = await ccUsage.liveOwner();
    const result = ccProfiles.saveProfile((req.body || {}).name, { owner });
@@ -619,7 +620,7 @@ router.post("/profiles", async (req, res) => {
 });

 // Rename is a label edit; the profile's `name` identifier never moves.
-router.patch("/profiles", (req, res) => {
+router.patch("/profiles", sameOriginGuard, (req, res) => {
  try {
    const body = req.body || {};
    const result = ccProfiles.renameProfile(body.name, body.label);
@@ -630,7 +631,7 @@ router.patch("/profiles", (req, res) => {
  }
 });

-router.post("/profiles/activate", async (req, res) => {
+router.post("/profiles/activate", sameOriginGuard, async (req, res) => {
  try {
    const owner = await ccUsage.liveOwner();
    const result = ccProfiles.activateProfile((req.body || {}).name, { owner });
@@ -673,7 +674,7 @@ router.post("/profiles/usage", sameOriginGuard, async (req, res) => {
 });

 // Identifier travels in the body, not the URL — same reason as DELETE /file.
-router.delete("/profiles", (req, res) => {
+router.delete("/profiles", sameOriginGuard, (req, res) => {
  try {
    const result = ccProfiles.deleteProfile((req.body || {}).name);
    emitChanged({ action: "delete", type: "profile", name: result.name, project: null });
@@ -135,7 +135,7 @@ router.get("/file", (req, res) => {
 // anywhere on disk (same reasoning cc-config.js's PATCH /settings gives for
 // refusing `?cwd=` there). Reads keep the override.

-router.put("/file", (req, res) => {
+router.put("/file", sameOriginGuard, (req, res) => {
  const { scope, type, name, content } = req.body || {};
  if (typeof scope !== "string" || typeof type !== "string") {
    return res
@@ -151,7 +151,7 @@ router.put("/file", (req, res) => {
  }
 });

-router.delete("/file", (req, res) => {
+router.delete("/file", sameOriginGuard, (req, res) => {
  const { scope, type, name } = req.body || {};
  if (typeof scope !== "string" || typeof type !== "string") {
    return res
@@ -282,7 +282,7 @@ router.get("/marketplaces", async (_req, res) => {
  }
 });

-router.post("/mcp/add", async (req, res) => {
+router.post("/mcp/add", sameOriginGuard, async (req, res) => {
  try {
    const result = await codexCli.mcpAdd(req.body || {});
    return cliResult(res, result, { action: "add", type: "mcp", name: (req.body || {}).name });
@@ -291,7 +291,7 @@ router.post("/mcp/add", async (req, res) => {
  }
 });

-router.post("/mcp/remove", async (req, res) => {
+router.post("/mcp/remove", sameOriginGuard, async (req, res) => {
  const { name } = req.body || {};
  try {
    const result = await codexCli.mcpRemove(name);
@@ -306,7 +306,7 @@ const PLUGIN_ACTIONS = {
  remove: codexCli.pluginRemove,
 };

-router.post("/plugins/action", async (req, res) => {
+router.post("/plugins/action", sameOriginGuard, async (req, res) => {
  const { spec, action } = req.body || {};
  const run = PLUGIN_ACTIONS[action];
  if (!run) {
@@ -325,7 +325,7 @@ router.post("/plugins/action", async (req, res) => {
  }
 });

-router.post("/marketplaces/add", async (req, res) => {
+router.post("/marketplaces/add", sameOriginGuard, async (req, res) => {
  const { url } = req.body || {};
  try {
    const result = await codexCli.marketplaceAdd(url);
@@ -339,7 +339,7 @@ const MARKETPLACE_ACTIONS = {
  remove: codexCli.marketplaceRemove,
 };

-router.post("/marketplaces/action", async (req, res) => {
+router.post("/marketplaces/action", sameOriginGuard, async (req, res) => {
  const { name, action } = req.body || {};
  const run = MARKETPLACE_ACTIONS[action];
  if (!run) {
Author	SHA1	Message	Date
nntrivi2001	649f0599f8	chore: v2.8.18 — pasted file-manager copies attach by path locally, copy/IME/stale-reply fixes, react-router 7, full OpenAPI	2026-10-22 13:58:46 +07:00
nntrivi2001	8d2765313c	fix(chat): a file-manager copy pasted on a local browser attaches by its own path Chrome gives a PASTE of a file manager's copy (Ctrl+C in Nautilus, Ctrl+V in the chat) the files and their paths as plain text, but no text/uri-list — only a drag carries that — so localCandidates found no path and every such file was uploaded, and refused past the upload limit. Plain-text paths (or file:// lines) whose names match the pasted files one for one are now candidates too; sameFilesHere still has the server confirm each is the same file (size) on this machine, so server mode and remote browsers upload as before. The prompt box also attaches a file:// text paste with no file by path, as the terminal already did (copiedFilePaths moved to promptAttach).	2026-10-22 13:47:17 +07:00
nntrivi2001	57f02f0d89	docs: OpenAPI and API.md cover every route; drop removed endpoints; guard config writes - openapi-extra/run.js describes tmux pane runs only: the removed POST /api/run/{id}/message and stream-json run_stream/run_input_ack are gone. - 108 operations added to OpenAPI (lanes, run, settings, reports, cc-config, pets, ai-proxies, tool-profiles, ai-tools, snapshots, locks, ...); openapi.yaml regenerated. - docs/API.md: 74 routes added, 4 endpoints that no longer exist removed. - Role is `developer`, not `member` (CLI.md, DATABASE.md, OVERVIEW.md); `agenthub update` -> `update-check`; help lists `server install-system\|tools` and `users provision`; ARCHITECTURE.md's stale paths and names fixed. - cc-config/codex-config writes carry sameOriginGuard (an MCP server or plugin is code Claude runs later), with a test; `command -v` takes its name as $1.	2026-10-22 12:17:18 +07:00
nntrivi2001	50ac0f0daf	fix(client): copies over plain HTTP, Vietnamese IME Enter, stale replies; react-router 7 - Every Copy goes through copyText: on http://<lan-ip> navigator.clipboard is undefined, so the push token (shown once), snapshot links, tool paths and hosts copied nothing, silently or with a TypeError. - Inputs that submit on Enter use isSubmitEnter, so committing an IME composition (Vietnamese) no longer saves a half-typed pet name, jumps the settings search, or submits a cut-off plugin/MCP/marketplace spec. - LaneChangesPanel, Workspace features/proof and AiToolConfig drop a reply that lands after the next request started: opening file B before file A's read returned showed (and let the editor save) A's text under B's header. - Error-state Retry buttons spin through useSpin; ImageLightbox uses useDialog. - react-router-dom 6.30 -> 7.18.4 (GHSA-wrjc-x8rr-h8h6, GHSA-337j-9hxr-rhxg); screen snapshots gain only Link's data-discover attribute. - StatusBar test follows v2.8.17's "Settings → AI tools → Profiles" text.	2026-10-22 12:17:18 +07:00