cicy-desktop 2.1.42 → 2.1.44

package/CLAUDE.md

@@ -2,7 +2,9 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-`cicy-desktop` is an Electron app that exposes ~50 system tools (Chrome control, clipboard, screenshot, shell exec, system info, ...) over MCP and REST/RPC. The app runs in two roles — **worker** (the Electron process exposing tools) and **master** (a thin control plane that routes tool calls across workers) — and ships a bundled `cicy-code` sidecar daemon so the desktop is a fully offline-capable backend.
+`cicy-desktop` is an Electron app that exposes ~100+ system tools (Chrome control, CDP, clipboard, screenshot, shell/node/python exec, system info, file ops, ...) over MCP and REST/RPC. The app runs in two roles — **worker** (the Electron process exposing tools) and **master** (a thin control plane that routes tool calls across workers). It does **not** bundle a `cicy-code` binary — the sidecar daemon is acquired at runtime (`npx cicy-code` on mac/linux, Docker on Windows; see [Sidecar](#sidecar-cicy-code-daemon)).
+
+**Distribution (2026-06):** end users run via npm, not a packaged installer — `npx cicy-desktop` (mac/linux) / `npm i -g cicy-desktop && cicy-desktop` (Windows). First launch drops a desktop shortcut and auto-acquires the sidecar. CN needs `ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/` so electron's binary postinstall doesn't hit GitHub. The electron-builder packaged build (dmg/NSIS) still exists but is secondary. To discover tools at runtime, call the `list_tools` meta-tool (`electronRPC("list_tools")` / `agent-desktop rpc list_tools`).
 
 ## Development workflow rules (read first)
 
@@ -208,21 +210,17 @@ Supporting modules:
 - `src/cluster/worker-client.js` — worker registration + heartbeat to the master
 - `src/cluster/worker-identity.js` — identity payload advertised to the master
 
-Worker RPC surface:
+Worker tool surface (how the ~100 tools are reached):
 
-- `GET  /rpc/tools` — list registered tools
-- `POST /rpc/tools/call` — `{ name, arguments }` style invocation
-- `POST /rpc/:toolName` — direct REST entrypoint, what `cicy-rpc` uses after resolving the node
+- **IPC** — `ipcMain.handle("rpc", (e, toolName, args) => executeTool(...))` (`src/main.js`). This is what `window.electronRPC(tool, args)` and the cicy-code `desktop_event` bridge ride. No HTTP, no port.
+- **MCP** — every registered tool is exposed via the MCP server (`src/server/mcp-server.js`, `/mcp` + `/messages`).
+- **HTTP index** — `GET /openapi.json` (dynamic, every tool + inputSchema) and the Swagger UI at `/docs`.
+- **`list_tools`** — a meta-tool (`src/tools/list-tools.js`) that returns the live catalog over the IPC/RPC side, so callers that can't reach `/openapi.json` (renderer, `<webview>`, `agent-desktop rpc list_tools`) can still enumerate.
+- **REST `POST /rpc/:toolName`** — served by the **master** (`src/master/master-routes.js`), which forwards to a worker. The worker process itself does not mount `/rpc/*` execution routes.
 
 ### Tool system
 
-Tool implementations live in `src/tools/*.js` and are loaded via `require("../tools")` from `src/server/tool-catalog.js`. Each module exports a function receiving `registerTool(name, description, schema, handler, options)`. The catalog is grouped by `tag` and reused for:
-
-- MCP tool registration
-- `GET /rpc/tools`
-- OpenAPI generation in `/openapi.json`
-
-A tool definition change affects all three surfaces at once.
+Tool implementations live in `src/tools/*.js`, listed in `src/tools/index.js`, loaded via `require("../tools")` from `src/server/tool-catalog.js`. Each module exports a function receiving `registerTool(name, description, schema, handler, options)`. The catalog (grouped by `tag`) is reused for MCP registration, `list_tools`, and OpenAPI generation in `/openapi.json` — **a tool definition change affects all of them at once.**
 
 Tools use **CommonJS** and **Zod schemas**.
 
@@ -386,6 +384,18 @@ Only the **token** HMRs cleanly. If you also rebuilt the helper image with new A
 
 `HELPER_URL_BASE` (App.jsx) is the **other** half of the pairing. It currently points at `http://43.99.56.150:8011` (a long-running shared helper). If you want to swap to a locally rebuilt container, change it to `http://localhost:8011` and `ssh -fNR 8011:127.0.0.1:8011 mac` so the Mac can reach your dev box's helper. Same token-grab step still applies.
 
+### Deep links (`cicy://`) and local-team add/rename
+
+Protocol `cicy://` is registered (`package.json` build `protocols` + `setAsDefaultProtocolClient("cicy")` in `src/main.js`). The handler is `src/main.js::handleDeepLink(url)`, fed by `app.on("open-url")` (mac), `second-instance`, and cold-start `argv` (win/linux).
+
+`cicy://addTeam?title=<t>&url=<base_url>&token=<api_token>`:
+
+- **handleDeepLink adds the team directly in the main process** via `local-teams.addTeam({base_url, api_token, name})` — it does NOT rely on the renderer. (An earlier version only broadcast `deeplink:addTeam` to the renderer, but App.jsx never wired `window.cicy.deeplink.onAddTeam`, so the team was silently dropped.) The homepage polls `localTeams:list` every few seconds, so the new team shows up on its own.
+- **Upsert is keyed by `base_url`** (`local-teams.js::addTeam`): re-adding a known URL refreshes `api_token` + install meta but **keeps the existing (possibly user-renamed) name** — only a brand-new team takes the provided title. No-name → i18n default `localTeams.unnamed` (`Unnamed`/`未命名`/…).
+- The URL value must be **single** percent-encoded; raw CJK in `title` makes macOS `open` re-encode the whole thing (double-encoding → `bad base_url`).
+
+**Rename**: every local team is renamable. `LocalTeamCard` (App.jsx) has inline edit (double-click name / ✎) → `window.cicy.localTeams.update(id, {name})` → `local-teams.js::updateTeam` (whitelists `name`). Labels go through `window.cicyI18n.t` (preload-exposed i18n; keys in `src/i18n/locales/*.json` under `localTeams`).
+
 ### Backends launcher (legacy `src/backends/`)
 
 `src/backends/homepage.html` + `cicy.backends.{list, add, remove, …}` is the **pre-Vite** launcher. It still ships and still works (the bundled sidecar and Add-by-URL flow live here), but it is **not** what new users see — `pickHomepageURL` prefers the Vite/React entry. Touch this only when you're working on the old launcher path. Registry file: `<userData>/backends.json` (`src/backends/registry.js`). IPC handlers: `src/backends/ipc.js`.
@@ -424,7 +434,7 @@ Implication: anything that calls `window.electronRPC` from outside the cicy-code
 
 ### On-disk layout — `~/.local/bin/cicy-code` symlink → versioned binary
 
-Both the in-app installer (`src/sidecar/installer.js`) and the cloud Team Helper agent write the daemon into the user's `~/.local/bin/` with this shape:
+The cloud Team Helper agent writes the daemon into the user's `~/.local/bin/` with this shape (the npx sidecar path uses the npm cache instead, but a Helper-installed `~/.local/bin/cicy-code` on `:8008` is still reused first via `probeExisting`, and `upgradeNative` manages it):
 
 ```
 ~/.local/bin/cicy-code-2.1.8      (actual binary, +x)
@@ -451,23 +461,16 @@ Upgrade flow inside `src/backends/local-teams.js::upgradeNative`:
 
 The cloud helper agent uses the **same layout** when it does the initial install (`AGENTS.md` step 1A.2/1A.3 in `cicy-cloud/workers/helper/`). It writes `cicy-code-<ver>` + `ln -sfn` + spawns via the symlink, then registers the team with `install_path=~/.local/bin/cicy-code`. This way the agent's install path and the desktop's upgrade path are identical — no special-case wiring needed.
 
-### Sidecar cicy-code daemon — **NOT bundled** (2026-05-29 principle)
-
-`cicy-desktop` no longer ships a `cicy-code` binary in the `.app`. The daemon is acquired one of three ways:
-
-1. **Already running on `:8008`** — left over from a previous session, started by the user, or installed by the cloud Team Helper. `src/sidecar/cicy-code.js::probeExisting` detects it and `start()` reuses without re-spawning.
-2. **In-app installer** — `src/sidecar/installer.js` downloads the platform-matching binary from `cicy-ai/cicy-code` GitHub releases into `<userData>/cicy-code/<platform>-<arch>/cicy-code`. Triggered from the homepage when no daemon is running. `userBinary()` returns this path; `bundledBinaryPath()` only checks this single source — there is intentionally no `<App>/Contents/Resources/cicy-code` fallback.
-3. **Cloud Team Helper** — the trial helper container walks the user through installing cicy-code on their own machine, then registers it via `window.cicy.localTeams.add({...})`. Today the helper writes to `~/Downloads/cicy-code`; the in-app installer location is preferred (`<userData>/cicy-code/...`) so `userBinary()` discovers it on the next desktop launch with no extra wiring.
+### Sidecar cicy-code daemon
 
-Removed in this principle change:
-- `package.json` no longer has `extraResources` entries for `vendor/cicy-code/*/cicy-code`
-- `package.json` no longer runs `prepare:sidecar` in `prebuild*`
-- `scripts/prepare-cicy-code-sidecar.js` is dormant (kept for reference; can be deleted)
-- `vendor/cicy-code/` directory is no longer touched by the build
+`cicy-desktop` never bundles a `cicy-code` binary. `src/sidecar/cicy-code.js::start()` acquires the daemon at runtime:
 
-`sidecar/cicy-code.js::start()` therefore returns `null` whenever no `userBinary()` is present AND no daemon is on `:8008`. The homepage's Team Helper card is the surface that gets the user from "no daemon" to "daemon running" — either by triggering the in-app installer (for the legacy single-click path) or by walking the cloud-helper onboarding flow.
+1. **Already running on `:8008`** — left over from a previous session, started by the user, or installed by the cloud Team Helper. `probeExisting()` detects it and `start()` reuses without re-spawning. This wins on every platform.
+2. **mac / linux → `npx cicy-code`** — `start()` spawns `npx -y cicy-code` (default registry npmmirror for CN; override with `CICY_NPM_REGISTRY`, pin with `CICY_CODE_VERSION`). The launcher fetches the per-version binary from npm and does its own `:8008` port hygiene. No download/installer code in cicy-desktop.
+3. **Windows → Docker** — `start()` delegates to `src/sidecar/docker.js` (`docker run` of the cicy-code image whose entrypoint `npx`-installs cicy-code). The image is loaded from R2 when absent.
+4. **Cloud Team Helper** — the trial helper container walks the user through installing cicy-code on their machine, then registers the team via `window.cicy.localTeams.add({...})`.
 
-Windows path is unchanged — `src/sidecar/wsl.js` runs the daemon inside WSL2 because cicy-code is POSIX-only.
+**Retired (do not look for these):** the old in-app downloader `src/sidecar/installer.js` and the WSL path `src/sidecar/wsl.js` are **deleted**, along with their IPC handlers and the in-app install UI. There is no `bundledBinaryPath()`/`userBinary()`/`extraResources`/`vendor/cicy-code/` anymore. If no daemon is on `:8008` and the npx/Docker spawn can't run, `start()` returns `null` and the homepage's Team Helper card is the path from "no daemon" to "daemon running".
 
 #### What broke that motivated the principle (2026-05-29)
 
@@ -536,7 +539,10 @@ The master uses `CICY_MASTER_TOKEN` directly or falls back to `MasterTokenManage
 | backends launcher UI | `src/backends/homepage.html` |
 | backends preload bridge | `src/backends/homepage-preload.js` |
 | BrowserWindow trust + auto-inject | `src/utils/window-utils.js` |
-| sidecar packaging | `scripts/prepare-cicy-code-sidecar.js` |
+| sidecar acquisition (npx / docker) | `src/sidecar/cicy-code.js`, `src/sidecar/docker.js` |
+| desktop shortcut + deep links (`cicy://`) | `bin/cicy-desktop` (shortcut gen), `src/main.js` (handleDeepLink) |
+| local teams (add/upsert/rename) + i18n | `src/backends/local-teams.js`, `src/i18n/locales/*.json` |
+| tool list module | `src/tools/index.js`, `src/tools/list-tools.js` |
 | RPC test files | `tests/rpc/master-routes.test.js`, `tests/rpc/cicy-rpc.test.js` |
 
 ## Debugging via remote-debugging-port 9221
@@ -601,7 +607,7 @@ When touching any of these, expect ripple effects:
 - adding a tool → touches MCP server, REST/RPC, OpenAPI all at once via the catalog
 - changing trust criteria → changes `nodeIntegration` for whole classes of windows; verify with the cicy-code bridge still works
 - changing the homepage entry flow → check that cold-launch and "back to launcher" paths both behave (history.length / sessionStorage gates)
-- changing the sidecar packaging → verify `dist/mac/CiCy Desktop.app/Contents/Resources/cicy-code/cicy-code` is present and executable after build
+- changing the sidecar acquisition → there is no bundled binary; verify `npx cicy-code` (mac/linux) / Docker (win) actually spawns and binds `:8008`, and that `probeExisting` reuse still works
 - changing `chrome_*` tools → both master injection (`effectiveChromeProfile`) and worker fallback (`~/cicy-ai/db/chrome.json`) paths still need to work
 - changing **any preload file** → `⌘+Q` + reopen Electron is mandatory; HMR / `⌘+R` won't reload it. Confirm via CDP `Runtime.evaluate` on the target window
 - changing **`src/backends/local-teams.js`** → it's `require`d by main; full Electron restart needed. Don't forget to also expose any new methods through both `homepage-preload.js` (full surface) and `webview-preload.js` (relay)

package/README.md

@@ -295,9 +295,8 @@ Current source of truth in code:
 - tool implementations: `src/tools/*`
 
 At a high level:
-- `src/main.js:242` exposes `POST /rpc/tools/call`
-- `src/main.js:267` exposes `GET /rpc/tools`
-- `src/main.js:294` exposes `POST /rpc/:toolName`
+- the **worker** dispatches tools two ways: in-process via `ipcMain.handle("rpc", …)` (`src/main.js`, what `window.electronRPC(tool, args)` rides) and over HTTP. The full, live tool index is `GET /openapi.json` (browse at `/docs`); call `list_tools` to enumerate from the RPC/IPC side.
+- REST tool invocation (`POST /rpc/:toolName`, used by `cicy-rpc`) is served by the **master** (`src/master/master-routes.js`), which forwards to the selected worker.
 - RPC routes are protected by auth and return `401 Unauthorized` when the token is wrong or missing
 - the desktop CLI starts a local master + worker cluster and provides status/log management
 

package/bin/cicy-desktop

@@ -20,15 +20,35 @@ const ELECTRON_MIRROR = process.env.ELECTRON_MIRROR || "https://npmmirror.com/mi
 const NPM_REGISTRY = process.env.CICY_NPM_REGISTRY || process.env.npm_config_registry || "https://registry.npmmirror.com";
 const MASTER_ENTRY = path.join(PACKAGE_ROOT, "src", "master", "master-main.js");
 
-// Resolve the electron binary to spawn. Prefers the project-local copy
-// (node_modules/.bin/electron) when present; falls back to the global
-// `electron` on PATH (npm i -g electron), and finally to `npx electron`.
+// Resolve a globally-installed electron (`npm i -g electron`), so the ~200MB
+// binary is downloaded once and SHARED across cicy tools / desktop versions
+// instead of one copy per package install. Returns null if not present.
+let _globalElectronBin; // memoized (avoid re-spawning `npm prefix -g`)
+function globalElectronBin() {
+  if (_globalElectronBin !== undefined) return _globalElectronBin;
+  _globalElectronBin = null;
+  try {
+    const prefix = execSync("npm prefix -g", { stdio: ["ignore", "pipe", "ignore"] })
+      .toString().trim();
+    if (prefix) {
+      const p = isWindows
+        ? path.join(prefix, "electron.cmd")
+        : path.join(prefix, "bin", "electron");
+      if (fs.existsSync(p)) _globalElectronBin = p;
+    }
+  } catch { /* keep null */ }
+  return _globalElectronBin;
+}
+
+// Resolve the electron binary to spawn. Order: (C) a shared GLOBAL electron,
+// then the project-local copy, then `npx electron` as a last resort.
 // Windows uses `npx.cmd electron` to handle the shim correctly.
 function resolveElectronSpawn() {
+  const g = globalElectronBin();
+  if (g) return { cmd: g, prefixArgs: [] };
   if (isWindows) return { cmd: "npx.cmd", prefixArgs: ["electron"] };
   const local = path.join(PACKAGE_ROOT, "node_modules", ".bin", "electron");
   if (fs.existsSync(local)) return { cmd: local, prefixArgs: [] };
-  // Fall back to a globally-installed electron resolved via PATH.
   return { cmd: "npx", prefixArgs: ["electron"] };
 }
 const PROJECT_COMMAND_FILE = path.join(PACKAGE_ROOT, "cicy-dektop.command");
@@ -358,6 +378,17 @@ function nodeBinDir() {
   try { return path.dirname(process.execPath); } catch { return ""; }
 }
 
+// npm's global bin dir (<npm prefix -g>[/bin]), where `npm i -g cicy-desktop`
+// installs the launcher. The GUI shortcut runs that global bin directly so
+// startup doesn't pay an npx registry round-trip on every launch.
+function npmGlobalBinDir() {
+  try {
+    const prefix = execSync("npm prefix -g", { stdio: ["ignore", "pipe", "ignore"] })
+      .toString().trim();
+    return prefix ? (isWindows ? prefix : path.join(prefix, "bin")) : "";
+  } catch { return ""; }
+}
+
 function ensureDesktopCommandFile() {
   try {
     if (process.platform === "darwin") return ensureMacDesktopApp();
@@ -373,8 +404,8 @@ function ensureMacDesktopApp() {
   // executable is a shell script triggers "CiCy Desktop is not responding"
   // (LaunchServices waits for the script to register as a Cocoa app and times
   // out). An osacompile applet's executable IS the AppleScript runtime — a
-  // proper Cocoa app — so it launches cleanly, backgrounds `npx cicy-desktop`
-  // via `do shell script`, then quits. Icon = the applet's applet.icns.
+  // proper Cocoa app — so it launches cleanly, backgrounds the global
+  // `cicy-desktop` bin via `do shell script`, then quits. Icon = applet.icns.
   const { execFileSync } = require("child_process");
   const appDir = path.join(DESKTOP_DIR, "CiCy Desktop.app");
   // Idempotent — create only when missing. When the app is launched FROM this
@@ -384,16 +415,21 @@ function ensureMacDesktopApp() {
   // ever appears ("打不开"). Skip if it already exists.
   if (fs.existsSync(appDir)) return;
   const nodeDir = nodeBinDir();
-  // do shell script needs node on PATH (GUI launch has a minimal PATH); the
-  // trailing & + nohup + </dev/null lets the shell return so the applet quits.
-  // ELECTRON_MIRROR + npmmirror: a fresh CN machine has no cached electron
-  // binary, so npx's electron postinstall would try GitHub releases and fail
-  // (ECOMPROMISED / lock-compromised). Point it at npmmirror's electron mirror.
-  // Harmless elsewhere — only consulted when electron actually (re)downloads.
+  const gbin = npmGlobalBinDir();
+  // Launch the globally-installed `cicy-desktop` bin DIRECTLY (npm i -g) — no
+  // per-launch `npx` registry round-trip. Use the absolute path when resolvable
+  // (GUI launch has a minimal PATH); fall back to the bare name otherwise.
+  const cicyBin = gbin && fs.existsSync(path.join(gbin, "cicy-desktop"))
+    ? path.join(gbin, "cicy-desktop")
+    : "cicy-desktop";
+  // do shell script needs node + the global bin on PATH (GUI launch has a
+  // minimal PATH); trailing & + nohup + </dev/null lets the shell return so the
+  // applet quits. ELECTRON_MIRROR + npmmirror only matter if electron ever
+  // (re)downloads — harmless otherwise.
   const ascript =
-    `do shell script "export PATH=\\"${nodeDir}:/usr/local/bin:/opt/homebrew/bin:$PATH\\" ; ` +
+    `do shell script "export PATH=\\"${nodeDir}:${gbin}:/usr/local/bin:/opt/homebrew/bin:$PATH\\" ; ` +
     `export ELECTRON_MIRROR=\\"${ELECTRON_MIRROR}\\" ; export npm_config_registry=\\"${NPM_REGISTRY}\\" ; ` +
-    `nohup npx -y cicy-desktop > /tmp/cicy-desktop.log 2>&1 < /dev/null &"`;
+    `nohup '${cicyBin}' > /tmp/cicy-desktop.log 2>&1 < /dev/null &"`;
   const tmp = path.join(os.tmpdir(), `cicy-launch-${process.pid}.applescript`);
   fs.writeFileSync(tmp, ascript);
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cicy-desktop",
-  "version": "2.1.42",
+  "version": "2.1.44",
   "description": "CiCy - AI-powered operating system browser",
   "main": "src/main.js",
   "bin": {

package/src/backends/artifact-ipc.js

@@ -0,0 +1,142 @@
+// artifact-ipc.js — main-process side of the window.cicy.artifact bridge.
+//
+// The cicy-code app (loaded in a trusted team BrowserWindow) hosts a
+// <webview id="cicy-artifact-webview"> for the 产物 (artifact) tab. Its
+// renderer bridge (cicy-code app/src/lib/artifactBridge.ts) drives that
+// webview's *guest* webContents through `window.cicy.artifact.{invoke,cdp}` —
+// injected in window-utils.js — which round-trips to the handlers here.
+//
+// We resolve the guest via webContents.fromId(guestId) (the renderer passes the
+// element's getWebContentsId()), call webContents methods / drive its debugger,
+// and forward the guest's console / navigation / CDP-message events back to the
+// host renderer as 'artifact:event' (re-dispatched there as the
+// CustomEvent('cicy-artifact-event') the bridge buffers).
+
+const { ipcMain, webContents } = require("electron");
+const log = require("electron-log");
+
+// guest webContents.id → host renderer webContents that should receive events.
+// Updated on every invoke/attach so events follow host reloads.
+const guestHost = new Map();
+// guest webContents.id we've already wired passive (console/nav) listeners on.
+const wiredPassive = new Set();
+// guest webContents.id we've already wired the debugger 'message'/'detach' on.
+const wiredDebugger = new Set();
+
+function getGuest(guestId) {
+  const wc = typeof guestId === "number" ? webContents.fromId(guestId) : null;
+  if (!wc || wc.isDestroyed()) {
+    throw new Error(`artifact guest webContents ${guestId} not found (open the 产物 tab once)`);
+  }
+  return wc;
+}
+
+function emit(wc, detail) {
+  try {
+    const host = guestHost.get(wc.id);
+    if (host && !host.isDestroyed()) host.send("artifact:event", detail);
+  } catch {}
+}
+
+function rememberHost(wc, hostSender) {
+  guestHost.set(wc.id, hostSender);
+  if (!wc.__artifactCleanup) {
+    wc.__artifactCleanup = true;
+    wc.once("destroyed", () => {
+      guestHost.delete(wc.id);
+      wiredPassive.delete(wc.id);
+      wiredDebugger.delete(wc.id);
+    });
+  }
+}
+
+// console-message + navigation → host renderer. Wired once per guest.
+function wirePassive(wc) {
+  if (wiredPassive.has(wc.id)) return;
+  wiredPassive.add(wc.id);
+  wc.on("console-message", (_e, level, message, line, sourceId) => {
+    emit(wc, { source: "console", level, message, line, sourceId });
+  });
+  wc.on("did-navigate", (_e, url, httpResponseCode) => {
+    emit(wc, { source: "navigation", kind: "did-navigate", url, httpResponseCode });
+  });
+  wc.on("did-navigate-in-page", (_e, url, isMainFrame) => {
+    emit(wc, { source: "navigation", kind: "did-navigate-in-page", url, isMainFrame });
+  });
+}
+
+// debugger 'message' (the CDP event stream) + 'detach' → host renderer. Wired
+// once per guest; survives attach/detach cycles (only fires while attached).
+function wireDebugger(wc) {
+  if (wiredDebugger.has(wc.id)) return;
+  wiredDebugger.add(wc.id);
+  wc.debugger.on("message", (_e, method, params) => {
+    emit(wc, { source: "cdp", method, params });
+  });
+  wc.debugger.on("detach", (_e, reason) => {
+    emit(wc, { source: "cdp", method: "__detached", params: { reason } });
+  });
+}
+
+function register() {
+  // Call any webContents method on the artifact guest. capturePage/printToPDF
+  // are normalized to dataURL / base64 so the result survives JSON/WS.
+  ipcMain.handle("artifact:invoke", async (e, payload) => {
+    const { guestId, method, args = [] } = payload || {};
+    const wc = getGuest(guestId);
+    rememberHost(wc, e.sender);
+    wirePassive(wc);
+    if (typeof wc[method] !== "function") {
+      throw new Error(`artifact.invoke: webContents has no method '${method}'`);
+    }
+    if (method === "capturePage") {
+      const img = await wc.capturePage(...(args || []));
+      return img && typeof img.toDataURL === "function" ? img.toDataURL() : null;
+    }
+    if (method === "printToPDF") {
+      const buf = await wc.printToPDF((args && args[0]) || {});
+      return Buffer.from(buf).toString("base64");
+    }
+    return await wc[method](...(args || []));
+  });
+
+  ipcMain.handle("artifact:cdp-attach", async (e, payload) => {
+    const { guestId, protocolVersion } = payload || {};
+    const wc = getGuest(guestId);
+    rememberHost(wc, e.sender);
+    // DevTools and the debugger are mutually exclusive on one webContents —
+    // close a manually-opened inspector first, else attach() throws.
+    try { if (wc.isDevToolsOpened()) wc.closeDevTools(); } catch {}
+    if (!wc.debugger.isAttached()) {
+      wc.debugger.attach(protocolVersion || "1.3");
+    }
+    wireDebugger(wc);
+    wirePassive(wc);
+    return { ok: true, attached: true };
+  });
+
+  ipcMain.handle("artifact:cdp-detach", async (_e, payload) => {
+    const { guestId } = payload || {};
+    const wc = getGuest(guestId);
+    if (wc.debugger.isAttached()) wc.debugger.detach();
+    return { ok: true, attached: false };
+  });
+
+  ipcMain.handle("artifact:cdp-is-attached", async (_e, payload) => {
+    const { guestId } = payload || {};
+    try { return getGuest(guestId).debugger.isAttached(); } catch { return false; }
+  });
+
+  ipcMain.handle("artifact:cdp-send", async (_e, payload) => {
+    const { guestId, method, params } = payload || {};
+    const wc = getGuest(guestId);
+    if (!wc.debugger.isAttached()) {
+      throw new Error("artifact.cdp: debugger not attached (call cdp.attach first)");
+    }
+    return await wc.debugger.sendCommand(method, params || {});
+  });
+
+  log.info("[artifact] window.cicy.artifact IPC handlers registered");
+}
+
+module.exports = { register };

package/src/backends/homepage-preload.js

@@ -150,6 +150,11 @@ contextBridge.exposeInMainWorld("cicy", {
   auth: {
     loginStart:  ()  => logInvoke("auth:login-start"),
     loginCancel: ()  => logInvoke("auth:login-cancel"),
+    // Durable, origin-independent login persisted in main (global.json).
+    // getSaved() restores it when this origin's localStorage is empty;
+    // logout() clears it (the only thing that should).
+    getSaved:    ()  => logInvoke("auth:get-saved"),
+    logout:      ()  => logInvoke("auth:logout"),
     onComplete:  (cb) => {
       const handler = (_e, payload) => { try { cb(payload); } catch {} };
       ipcRenderer.on("auth:complete", handler);