feat(desktop,server,web): app icons, completion notifications, single-user mode, bundled penguin CLI (#226)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

packages/desktop/build/linux/after-install.tpl

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Deb post-install (electron-builder deb.afterInstall). Overriding the option REPLACES
+# electron-builder's default template, so this file is that default (app-builder-lib
+# templates/linux/after-install.tpl, v26.15.3) verbatim, plus the marked PenguinHarness
+# section exposing the bundled `penguin` CLI launcher on PATH. The dollar-brace forms
+# are electron-builder template macros (executable, sanitizedProductName); any other
+# all-letter dollar-brace token fails the build, so shell variables stay brace-less.
+
+if type update-alternatives >/dev/null 2>&1; then
+    # Remove previous link if it doesn't use update-alternatives
+    if [ -L '/usr/bin/${executable}' -a -e '/usr/bin/${executable}' -a "`readlink '/usr/bin/${executable}'`" != '/etc/alternatives/${executable}' ]; then
+        rm -f '/usr/bin/${executable}'
+    fi
+    update-alternatives --install '/usr/bin/${executable}' '${executable}' '/opt/${sanitizedProductName}/${executable}' 100 || ln -sf '/opt/${sanitizedProductName}/${executable}' '/usr/bin/${executable}'
+else
+    ln -sf '/opt/${sanitizedProductName}/${executable}' '/usr/bin/${executable}'
+fi
+
+# PenguinHarness: expose the bundled penguin CLI launcher on PATH. Never clobber a real
+# file of that name; replacing a (possibly stale) symlink keeps re-installs idempotent.
+if [ ! -e '/usr/bin/penguin' ] || [ -L '/usr/bin/penguin' ]; then
+    ln -sf '/opt/${sanitizedProductName}/resources/app/bin/penguin' '/usr/bin/penguin'
+fi
+
+# Check if user namespaces are supported by the kernel and working with a quick test:
+if ! { [[ -L /proc/self/ns/user ]] && unshare --user true; }; then
+    # Use SUID chrome-sandbox only on systems without user namespaces:
+    chmod 4755 '/opt/${sanitizedProductName}/chrome-sandbox' || true
+else
+    chmod 0755 '/opt/${sanitizedProductName}/chrome-sandbox' || true
+fi
+
+if hash update-mime-database 2>/dev/null; then
+    update-mime-database /usr/share/mime || true
+fi
+
+if hash update-desktop-database 2>/dev/null; then
+    update-desktop-database /usr/share/applications || true
+fi
+
+# Install apparmor profile. (Ubuntu 24+)
+# First check if the version of AppArmor running on the device supports our profile.
+# This is in order to keep backwards compatibility with Ubuntu 22.04 which does not support abi/4.0.
+# In that case, we just skip installing the profile since the app runs fine without it on 22.04.
+#
+# Those apparmor_parser flags are akin to performing a dry run of loading a profile.
+# https://wiki.debian.org/AppArmor/HowToUse#Dumping_profiles
+#
+# Unfortunately, at the moment AppArmor doesn't have a good story for backwards compatibility.
+# https://askubuntu.com/questions/1517272/writing-a-backwards-compatible-apparmor-profile
+if apparmor_status --enabled > /dev/null 2>&1; then
+  APPARMOR_PROFILE_SOURCE='/opt/${sanitizedProductName}/resources/apparmor-profile'
+  APPARMOR_PROFILE_TARGET='/etc/apparmor.d/${executable}'
+  if apparmor_parser --skip-kernel-load --debug "$APPARMOR_PROFILE_SOURCE" > /dev/null 2>&1; then
+    cp -f "$APPARMOR_PROFILE_SOURCE" "$APPARMOR_PROFILE_TARGET"
+
+    # Updating the current AppArmor profile is not possible and probably not meaningful in a chroot'ed environment.
+    # Use cases are for example environments where images for clients are maintained.
+    # There, AppArmor might correctly be installed, but live updating makes no sense.
+    if ! { [ -x '/usr/bin/ischroot' ] && /usr/bin/ischroot; } && hash apparmor_parser 2>/dev/null; then
+      # Extra flags taken from dh_apparmor:
+      # > By using '-W -T' we ensure that any abstraction updates are also pulled in.
+      # https://wiki.debian.org/AppArmor/Contribute/FirstTimeProfileImport
+      apparmor_parser --replace --write-cache --skip-read-cache "$APPARMOR_PROFILE_TARGET"
+    fi
+  else
+    echo "Skipping the installation of the AppArmor profile as this version of AppArmor does not seem to support the bundled profile"
+  fi
+fi

packages/desktop/build/linux/after-remove.tpl

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Deb post-remove (electron-builder deb.afterRemove). Overriding the option REPLACES
+# electron-builder's default template, so this file is that default (app-builder-lib
+# templates/linux/after-remove.tpl, v26.15.3) verbatim, plus the marked PenguinHarness
+# section removing the `penguin` CLI launcher link installed by after-install.tpl.
+
+# Delete the link to the binary
+# update-alternatives --remove <name> <path>: 'path' must be the registered alternative binary,
+# not the generic symlink — see https://man7.org/linux/man-pages/man1/update-alternatives.1.html
+if type update-alternatives >/dev/null 2>&1; then
+    update-alternatives --remove '${executable}' '/opt/${sanitizedProductName}/${executable}'
+else
+    rm -f '/usr/bin/${executable}'
+fi
+
+# PenguinHarness: remove the penguin CLI launcher link, but only if it is ours.
+if [ -L '/usr/bin/penguin' ] && [ "`readlink '/usr/bin/penguin'`" = '/opt/${sanitizedProductName}/resources/app/bin/penguin' ]; then
+    rm -f '/usr/bin/penguin'
+fi
+
+APPARMOR_PROFILE_DEST='/etc/apparmor.d/${executable}'
+
+# Remove and unload apparmor profile.
+if [ -f "$APPARMOR_PROFILE_DEST" ]; then
+  # Unload the profile from the running kernel before deleting the file so the
+  # policy is not left enforced until the next reboot.  Mirror the chroot guard
+  # used in the after-install script — live AppArmor operations are not
+  # meaningful inside a chroot.
+  # https://wiki.debian.org/AppArmor/HowToUse
+  if apparmor_status --enabled > /dev/null 2>&1; then
+    if ! { [ -x '/usr/bin/ischroot' ] && /usr/bin/ischroot; } && hash apparmor_parser 2>/dev/null; then
+      apparmor_parser --remove "$APPARMOR_PROFILE_DEST" || true
+    fi
+  fi
+  rm -f "$APPARMOR_PROFILE_DEST"
+fi

packages/desktop/electron-builder.yml

@@ -24,6 +24,10 @@ nodeGypRebuild: false
 
 mac:
   category: public.app-category.developer-tools
+  # Brand icon (rendered from packages/web/public/penguin-logo.svg by
+  # scripts/render-icon.mjs, committed): electron-builder converts the 1024px PNG to
+  # icns itself (app-builder-lib iconConverter; >=512px required).
+  icon: build/icon.png
   # No Developer ID yet (M4): identity null skips codesign instead of failing.
   identity: null
   # Version-less artifact names, following the CLI bundles (penguin-darwin-arm64.tar.gz):
@@ -38,6 +42,9 @@ mac:
       arch: [arm64, x64]
 
 win:
+  # Same source PNG; electron-builder converts it to the multi-size ico embedded in the
+  # exe (>=256px required).
+  icon: build/icon.png
   artifactName: penguin-desktop-win32-${arch}.${ext}
   target:
     - target: nsis
@@ -54,6 +61,9 @@ nsis:
   allowToChangeInstallationDirectory: true
 
 linux:
+  # Pre-rendered freedesktop icon set (scripts/render-icon.mjs): a directory of NxN.png
+  # files is used as-is for AppImage/deb, no conversion step.
+  icon: build/icons
   # The scoped package name is not a valid executable file name.
   executableName: penguin-harness
   # ${arch} expands to each Linux target's own convention — x86_64 for AppImage, amd64
@@ -68,3 +78,11 @@ linux:
       arch: [x64]
     - target: deb
       arch: [x64]
+
+deb:
+  # Extended copies of electron-builder's default scripts (overriding REPLACES them):
+  # they additionally create/remove the /usr/bin/penguin symlink to the staged CLI
+  # launcher (resources/app/bin/penguin), so a deb install gets the `penguin` command
+  # on PATH without the in-app install flow the other formats use.
+  afterInstall: build/linux/after-install.tpl
+  afterRemove: build/linux/after-remove.tpl

packages/desktop/package.json

@@ -17,6 +17,7 @@
     "pack:win": "node scripts/stage.mjs && electron-builder --win"
   },
   "dependencies": {
+    "@prismshadow/penguin-cli": "workspace:*",
     "@prismshadow/penguin-core": "workspace:*",
     "@prismshadow/penguin-server": "workspace:*"
   },

packages/desktop/scripts/render-icon.mjs

@@ -0,0 +1,72 @@
+/**
+ * Render the app icon PNGs from the brand mark (packages/web/public/penguin-logo.svg,
+ * treated as immutable — landing/docs carry byte-identical copies).
+ *
+ * Outputs (COMMITTED — regenerate only when the SVG changes):
+ * - build/icon.png            1024×1024. electron-builder converts it to icns (mac,
+ *                             >=512px required) and ico (win, >=256px) at pack time;
+ *                             also the runtime BrowserWindow icon (see src/app-icon.ts).
+ * - build/icons/<N>x<N>.png   128/256/512 freedesktop set for the Linux targets
+ *                             (used as-is, no conversion).
+ *
+ * Regenerate: node packages/desktop/scripts/render-icon.mjs
+ * Rasterizes via the Playwright chromium already installed for packages/landing (no new
+ * dependency; precedent: packages/landing/scripts/capture-readme-demo.mjs). Each size is
+ * rendered at its native resolution (no downscaling), with a transparent background so
+ * the SVG's rounded-rect clip keeps the corners transparent.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG_DIR = path.resolve(HERE, "..");
+const REPO_ROOT = path.resolve(PKG_DIR, "..", "..");
+const SVG_PATH = path.join(REPO_ROOT, "packages", "web", "public", "penguin-logo.svg");
+const BUILD_DIR = path.join(PKG_DIR, "build");
+const ICON_SET_DIR = path.join(BUILD_DIR, "icons");
+
+// Resolve @playwright/test from the landing package's context (it is not a dependency
+// of this package, and must not become one).
+const requireLanding = createRequire(path.join(REPO_ROOT, "packages", "landing", "package.json"));
+const { chromium } = requireLanding("@playwright/test");
+
+const svgDataUrl = `data:image/svg+xml;base64,${readFileSync(SVG_PATH).toString("base64")}`;
+
+/** [size, output path]; icon.png is the 1024 master, the rest form the Linux icon set. */
+const targets = [
+  [1024, path.join(BUILD_DIR, "icon.png")],
+  [512, path.join(ICON_SET_DIR, "512x512.png")],
+  [256, path.join(ICON_SET_DIR, "256x256.png")],
+  [128, path.join(ICON_SET_DIR, "128x128.png")],
+];
+
+mkdirSync(ICON_SET_DIR, { recursive: true });
+
+const browser = await chromium.launch();
+try {
+  for (const [size, outPath] of targets) {
+    const page = await browser.newPage({
+      viewport: { width: size, height: size },
+      deviceScaleFactor: 1,
+    });
+    await page.setContent(
+      `<style>html,body{margin:0;padding:0;background:transparent}` +
+        `img{display:block;width:${size}px;height:${size}px}</style>` +
+        `<img src="${svgDataUrl}">`,
+    );
+    await page.evaluate(() => document.querySelector("img").decode());
+    const png = await page.screenshot({
+      omitBackground: true,
+      clip: { x: 0, y: 0, width: size, height: size },
+    });
+    writeFileSync(outPath, png);
+    console.log(
+      `[render-icon] ${path.relative(PKG_DIR, outPath)} (${size}x${size}, ${png.length} bytes)`,
+    );
+    await page.close();
+  }
+} finally {
+  await browser.close();
+}

packages/desktop/scripts/stage.mjs

@@ -2,20 +2,25 @@
  * Assemble the self-contained app directory electron-builder packs (stage/app).
  *
  * `pnpm deploy --prod` materializes this package plus its production dependency tree —
- * including the workspace packages — into a portable directory whose symlinks all stay
- * inside it (verified: the server boots from the deploy dir as-is). On top of that:
+ * including the workspace packages (@prismshadow/penguin-cli among them, so the staged
+ * node_modules carries cli + server + core + skills) — into a portable directory whose
+ * symlinks all stay inside it (verified: the server boots from the deploy dir as-is).
+ * On top of that:
  * - prune dev files (sources, configs) so only dist/, node_modules/ and package.json ship;
  * - copy the web build to `node_modules/@prismshadow/penguin-server/web-dist`, the npm
  *   package layout the server's static-hosting lookup checks first;
+ * - copy build/icon.png into the app dir (the runtime window icon, see src/app-icon.ts);
+ * - generate the `penguin` CLI launchers into `bin/` (POSIX + Windows, see
+ *   src/launcher.ts): they run the bundled CLI on the app's Electron runtime as Node;
  * - ensure `stage/minigit` exists (may be empty): the Windows CI job downloads MinGit
  *   into it, and electron-builder's win extraResources entry must always have a source.
  *
- * Run from anywhere; all paths are derived from this file's location.
+ * Run from anywhere (after `pnpm -r build`); all paths derive from this file's location.
  */
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const repoRoot = path.resolve(pkgDir, "..", "..");
@@ -76,6 +81,44 @@ if (!fs.existsSync(path.join(webDist, "index.html"))) {
 const serverPkg = path.join(appDir, "node_modules", "@prismshadow", "penguin-server");
 fs.cpSync(webDist, path.join(serverPkg, "web-dist"), { recursive: true, dereference: true });
 
+// The shell forks the server by this exact path, and the CLI launchers point at the
+// CLI entry: verify both landed in the deploy tree before packing.
+const launcherModule = path.join(pkgDir, "dist", "launcher.js");
+for (const [what, file] of [
+  ["server entry", path.join(serverPkg, "dist", "index.js")],
+  [
+    "CLI entry",
+    path.join(appDir, "node_modules", "@prismshadow", "penguin-cli", "dist", "index.js"),
+  ],
+  ["launcher generator (dist/launcher.js)", launcherModule],
+]) {
+  if (!fs.existsSync(file)) {
+    console.error(`[stage] missing ${what} (${file}) — run \`pnpm -r build\` first.`);
+    process.exit(1);
+  }
+}
+
+// Runtime window icon: same app-dir-relative location as the dev run (build/icon.png),
+// so src/app-icon.ts resolves it identically in both layouts.
+const iconSrc = path.join(pkgDir, "build", "icon.png");
+if (!fs.existsSync(iconSrc)) {
+  console.error("[stage] build/icon.png is missing — run `node scripts/render-icon.mjs`.");
+  process.exit(1);
+}
+fs.mkdirSync(path.join(appDir, "build"), { recursive: true });
+fs.copyFileSync(iconSrc, path.join(appDir, "build", "icon.png"));
+
+// CLI launchers (bin/penguin, bin/penguin.cmd): generated, not committed — the script
+// text lives in src/launcher.ts so it is unit-tested with the rest of the shell.
+const { posixLauncherScript, windowsLauncherScript } = await import(
+  pathToFileURL(launcherModule).href
+);
+const binDir = path.join(appDir, "bin");
+fs.mkdirSync(binDir, { recursive: true });
+fs.writeFileSync(path.join(binDir, "penguin"), posixLauncherScript(), { mode: 0o755 });
+fs.chmodSync(path.join(binDir, "penguin"), 0o755);
+fs.writeFileSync(path.join(binDir, "penguin.cmd"), windowsLauncherScript());
+
 fs.mkdirSync(path.join(stageDir, "minigit"), { recursive: true });
 
 console.log("[stage] done:", appDir);

packages/desktop/src/app-icon.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime window icon — pure path logic, no Electron imports (unit-tested).
+ *
+ * Only Linux (and Windows dev runs) need it: a packaged Windows app gets its taskbar
+ * icon from the exe resources electron-builder embeds, and macOS ignores BrowserWindow
+ * icons entirely (the Dock icon comes from the bundle's icns). The PNG lives at
+ * build/icon.png both in the source package (committed, rendered by
+ * scripts/render-icon.mjs) and in the staged app directory (copied by scripts/stage.mjs),
+ * so the same app-path-relative lookup serves dev and packaged runs.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+/** Window icon location relative to the app directory (dev package dir / staged app dir). */
+export const WINDOW_ICON_RELPATH = ["build", "icon.png"];
+
+/** The window-icon path for a platform, or null where window icons are not used (macOS). */
+export function windowIconPathFor(appPath: string, platform: NodeJS.Platform): string | null {
+  if (platform === "darwin") return null;
+  return path.join(appPath, ...WINDOW_ICON_RELPATH);
+}
+
+/** Same, but only when the file actually exists (a missing icon must not break windows). */
+export function resolveWindowIcon(appPath: string, platform: NodeJS.Platform): string | null {
+  const iconPath = windowIconPathFor(appPath, platform);
+  return iconPath !== null && fs.existsSync(iconPath) ? iconPath : null;
+}

packages/desktop/src/cli-install.ts

@@ -0,0 +1,212 @@
+/**
+ * "Install 'penguin' Command" — PATH exposure for the bundled CLI launcher
+ * (<app>/bin/penguin, generated at stage time; see launcher.ts).
+ *
+ * Per platform (deb is absent on purpose — its postinst ships /usr/bin/penguin, see
+ * build/linux/after-install.tpl):
+ * - macOS: symlink /usr/local/bin/penguin → <app>/bin/penguin; on permission errors,
+ *   escalate ONCE via osascript "with administrator privileges".
+ * - Windows: append <app>\bin to the user PATH (HKCU\Environment) via reg.exe,
+ *   idempotently (read + compare first); new terminals pick it up.
+ * - Linux AppImage: write an executable ~/.local/bin/penguin wrapper that runs the
+ *   AppImage itself as Node (see launcher.ts appImageWrapperScript).
+ *
+ * Everything is native UI (menu item + dialogs) in English: the main process stays
+ * outside the web app's i18n, and per the design the desktop shell talks to the page
+ * only through the server's HTTP API — never a private IPC channel.
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { app, dialog } from "electron";
+import type { BrowserWindow } from "electron";
+import { appImageWrapperScript, cliInstallKind, mergeWindowsUserPath } from "./launcher.js";
+import type { CliInstallKind } from "./launcher.js";
+
+const execFileAsync = promisify(execFile);
+
+/** The staged launcher directory inside the packaged app. */
+function binDir(): string {
+  return path.join(app.getAppPath(), "bin");
+}
+
+/** This run's install kind, or null when there is nothing to install (dev run / deb). */
+export function currentCliInstallKind(): CliInstallKind | null {
+  return cliInstallKind({
+    packaged: app.isPackaged,
+    platform: process.platform,
+    appImagePath: process.env.APPIMAGE ?? null,
+  });
+}
+
+function showResult(win: BrowserWindow | null, ok: boolean, detail: string): void {
+  const opts = {
+    type: ok ? ("info" as const) : ("error" as const),
+    title: "PenguinHarness",
+    message: ok
+      ? "The 'penguin' command is installed."
+      : "Could not install the 'penguin' command.",
+    detail,
+  };
+  void (win !== null ? dialog.showMessageBox(win, opts) : dialog.showMessageBox(opts));
+}
+
+/** macOS: /usr/local/bin/penguin symlink, escalating once via osascript on EACCES/EPERM. */
+async function installDarwin(win: BrowserWindow | null): Promise<void> {
+  const target = path.join(binDir(), "penguin");
+  const link = "/usr/local/bin/penguin";
+  try {
+    fs.mkdirSync("/usr/local/bin", { recursive: true });
+    fs.rmSync(link, { force: true });
+    fs.symlinkSync(target, link);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "EACCES" && code !== "EPERM") {
+      showResult(win, false, String(err));
+      return;
+    }
+    // Privileged retry; paths contain no single quotes (the bundle path is fixed and
+    // /Applications-style paths at most contain spaces).
+    const shellCmd = `mkdir -p /usr/local/bin && ln -sf '${target}' '${link}'`;
+    try {
+      await execFileAsync("osascript", [
+        "-e",
+        `do shell script "${shellCmd.replace(/"/g, '\\"')}" with administrator privileges`,
+      ]);
+    } catch (escalated) {
+      showResult(
+        win,
+        false,
+        `Administrator authorization failed or was cancelled.\n${String(escalated)}`,
+      );
+      return;
+    }
+  }
+  showResult(
+    win,
+    true,
+    `${link} now points at the app's bundled CLI. Run 'penguin' from any terminal.`,
+  );
+}
+
+/** Windows: idempotent HKCU\Environment PATH append via reg.exe. */
+async function installWindows(win: BrowserWindow | null): Promise<void> {
+  const dir = binDir();
+  let current: string | null = null;
+  try {
+    const { stdout } = await execFileAsync("reg", ["query", "HKCU\\Environment", "/v", "Path"]);
+    // Output line: "    Path    REG_EXPAND_SZ    C:\foo;C:\bar"
+    const m = /^\s*Path\s+REG(?:_EXPAND)?_SZ\s+(.*)$/im.exec(stdout);
+    if (m) current = m[1]!.trim();
+  } catch {
+    current = null; // No user Path value yet.
+  }
+  const merged = mergeWindowsUserPath(current, dir);
+  if (merged === null) {
+    showResult(win, true, `${dir} is already on your PATH. Run 'penguin' from any terminal.`);
+    return;
+  }
+  try {
+    // REG_EXPAND_SZ keeps any %VAR% entries of the existing value expandable.
+    await execFileAsync("reg", [
+      "add",
+      "HKCU\\Environment",
+      "/v",
+      "Path",
+      "/t",
+      "REG_EXPAND_SZ",
+      "/d",
+      merged,
+      "/f",
+    ]);
+  } catch (err) {
+    showResult(win, false, String(err));
+    return;
+  }
+  showResult(
+    win,
+    true,
+    `${dir} was added to your user PATH. Open a NEW terminal (existing ones keep the old PATH) and run 'penguin'.`,
+  );
+}
+
+/** Linux AppImage: executable ~/.local/bin/penguin wrapper invoking the AppImage as Node. */
+function installAppImage(win: BrowserWindow | null): void {
+  const appImage = process.env.APPIMAGE;
+  if (!appImage) {
+    showResult(win, false, "APPIMAGE is not set; this build cannot install the command.");
+    return;
+  }
+  const dir = path.join(os.homedir(), ".local", "bin");
+  const wrapper = path.join(dir, "penguin");
+  let script: string;
+  try {
+    script = appImageWrapperScript(appImage);
+  } catch (err) {
+    showResult(win, false, String(err));
+    return;
+  }
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(wrapper, script, { mode: 0o755 });
+    fs.chmodSync(wrapper, 0o755); // writeFileSync mode is ignored when the file existed.
+  } catch (err) {
+    showResult(win, false, String(err));
+    return;
+  }
+  showResult(
+    win,
+    true,
+    `${wrapper} now runs the CLI bundled in this AppImage. Make sure ~/.local/bin is on your PATH (most distributions add it at login), then run 'penguin' from a new terminal. Re-run this menu item if you move the AppImage.`,
+  );
+}
+
+/** Runs the platform installer (menu item and first-launch offer both land here). */
+export async function installCliCommand(win: BrowserWindow | null): Promise<void> {
+  switch (currentCliInstallKind()) {
+    case "darwin":
+      await installDarwin(win);
+      return;
+    case "windows":
+      await installWindows(win);
+      return;
+    case "appimage":
+      installAppImage(win);
+      return;
+    case null:
+      showResult(win, false, "This build has no bundled CLI to install (development run).");
+  }
+}
+
+/**
+ * One-time first-launch offer: asks once per installation whether to install the
+ * command, and never again (the app menu keeps the entry point available). The
+ * "offered" flag persists under userData next to the shell's other state files.
+ */
+export async function maybeOfferCliInstall(win: BrowserWindow | null): Promise<void> {
+  if (currentCliInstallKind() === null) return;
+  const flag = path.join(app.getPath("userData"), "cli-install-offered");
+  try {
+    if (fs.existsSync(flag)) return;
+    fs.mkdirSync(path.dirname(flag), { recursive: true });
+    fs.writeFileSync(flag, `${new Date().toISOString()}\n`);
+  } catch {
+    return; // Unreadable/unwritable userData: skip rather than re-offer forever.
+  }
+  const opts = {
+    type: "question" as const,
+    title: "PenguinHarness",
+    message: "Install the 'penguin' command line tool?",
+    detail:
+      "Makes the CLI bundled with this app available in your terminal. You can do this later from the application menu: Install 'penguin' Command.",
+    buttons: ["Install", "Not Now"],
+    defaultId: 0,
+    cancelId: 1,
+  };
+  const { response } = await (win !== null
+    ? dialog.showMessageBox(win, opts)
+    : dialog.showMessageBox(opts));
+  if (response === 0) await installCliCommand(win);
+}

packages/desktop/src/launcher.ts

@@ -0,0 +1,180 @@
+/**
+ * CLI launcher generation and PATH plumbing — pure helpers, no Electron imports, so
+ * they unit-test under plain vitest AND load in plain node: scripts/stage.mjs imports
+ * the built dist/launcher.js at stage time to write the launcher scripts into the
+ * packaged app directory's bin/.
+ *
+ * The launchers run the bundled @prismshadow/penguin-cli on the app's own Electron
+ * runtime as Node (ELECTRON_RUN_AS_NODE), so an installed desktop app provides a
+ * working `penguin` command without any system Node installation. How bin/ reaches
+ * PATH is per platform (see cli-install.ts and build/linux/*.tpl for the deb variant).
+ */
+
+/** CLI entry inside the staged app directory (pnpm-deploy layout, asar off). */
+export const CLI_ENTRY_RELPATH = "node_modules/@prismshadow/penguin-cli/dist/index.js";
+
+/**
+ * Platform executable names, fixed by electron-builder.yml: productName PenguinHarness
+ * (macOS bundle executable and Windows .exe) and linux.executableName penguin-harness.
+ */
+export const MAC_EXECUTABLE = "PenguinHarness";
+export const WIN_EXECUTABLE = "PenguinHarness.exe";
+export const LINUX_EXECUTABLE = "penguin-harness";
+
+/**
+ * POSIX launcher, staged as `<app>/bin/penguin` (chmod 755). Resolves its own real
+ * location first (PATH exposure is a symlink on macOS/deb), then finds the Electron
+ * executable at the platform's fixed position relative to the app directory:
+ * - macOS: app dir is `<bundle>/Contents/Resources/app` → `../../MacOS/PenguinHarness`
+ * - Linux: app dir is `<install>/resources/app` → `../../penguin-harness`
+ */
+export function posixLauncherScript(): string {
+  return `#!/bin/sh
+# penguin CLI launcher (generated by packages/desktop/scripts/stage.mjs).
+# Runs the bundled penguin CLI on this app's Electron runtime as Node
+# (ELECTRON_RUN_AS_NODE=1) - no system Node installation required.
+
+# Resolve this script's real location; PATH exposure installs a symlink to it
+# (readlink -f is not portable to macOS, hence the loop).
+SOURCE=$0
+while [ -h "$SOURCE" ]; do
+  DIR=$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)
+  SOURCE=$(readlink "$SOURCE")
+  case $SOURCE in
+    /*) ;;
+    *) SOURCE="$DIR/$SOURCE" ;;
+  esac
+done
+BIN_DIR=$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)
+APP_DIR=$(dirname "$BIN_DIR")
+
+CLI_ENTRY="$APP_DIR/${CLI_ENTRY_RELPATH}"
+# The Electron executable sits at a fixed location relative to the app directory:
+# macOS <bundle>/Contents/Resources/app -> ../../MacOS/${MAC_EXECUTABLE};
+# Linux <install>/resources/app -> ../../${LINUX_EXECUTABLE}.
+for CANDIDATE in "$APP_DIR/../../MacOS/${MAC_EXECUTABLE}" "$APP_DIR/../../${LINUX_EXECUTABLE}"; do
+  if [ -x "$CANDIDATE" ]; then
+    export ELECTRON_RUN_AS_NODE=1
+    exec "$CANDIDATE" "$CLI_ENTRY" "$@"
+  fi
+done
+echo "penguin: could not find the PenguinHarness runtime next to $APP_DIR" >&2
+exit 1
+`;
+}
+
+/**
+ * Windows launcher, staged as `<app>\\bin\\penguin.cmd`. `%~dp0` is this script's
+ * directory (with a trailing backslash): the exe sits three levels up
+ * (bin -> app -> resources -> install root), the CLI entry one level up in the app dir.
+ * CRLF line endings on purpose - cmd.exe is unreliable with bare LF scripts.
+ */
+export function windowsLauncherScript(): string {
+  return [
+    "@echo off",
+    "rem penguin CLI launcher (generated by packages/desktop/scripts/stage.mjs).",
+    "rem Runs the bundled penguin CLI on this app's Electron runtime as Node.",
+    "setlocal",
+    'set "ELECTRON_RUN_AS_NODE=1"',
+    `"%~dp0..\\..\\..\\${WIN_EXECUTABLE}" "%~dp0..\\${CLI_ENTRY_RELPATH.replaceAll("/", "\\")}" %*`,
+    "exit /b %errorlevel%",
+    "",
+  ].join("\r\n");
+}
+
+/**
+ * Single-line CJS bootstrap for the AppImage wrapper (`electron -e <this>`): resolves
+ * the CLI entry relative to the mounted application (process.execPath is the Electron
+ * binary inside the AppImage mount, resources/app sits next to it), splices it into
+ * argv[1] so `node -e` argv ([execPath, ...args]) becomes the [execPath, entry, ...args]
+ * shape the CLI's argv parsing expects, then imports the (ESM) entry. Must not contain
+ * single quotes: the wrapper embeds it in a single-quoted shell string.
+ */
+export function appImageBootstrapJs(): string {
+  return (
+    'const path=require("path");' +
+    'const cli=path.join(path.dirname(process.execPath),"resources","app",' +
+    '"node_modules","@prismshadow","penguin-cli","dist","index.js");' +
+    "process.argv.splice(1,0,cli);" +
+    "import(cli).catch((err)=>{console.error(err);process.exit(1);});"
+  );
+}
+
+/**
+ * Wrapper script installed to ~/.local/bin/penguin for the AppImage form, which has no
+ * stable install directory to symlink into: it invokes the AppImage itself as Node.
+ * The AppImage path is baked in at install time; the guard turns a moved/deleted
+ * AppImage into a clear message instead of a shell "not found".
+ */
+export function appImageWrapperScript(appImagePath: string): string {
+  if (appImagePath.includes("'")) {
+    // A quote would break out of the single-quoted assignment below; refuse rather
+    // than generate a broken (or injectable) script.
+    throw new Error(`AppImage path must not contain single quotes: ${appImagePath}`);
+  }
+  return `#!/bin/sh
+# penguin CLI launcher (generated by the PenguinHarness desktop app).
+# Runs the CLI bundled inside the AppImage by starting the AppImage's Electron
+# runtime as Node (ELECTRON_RUN_AS_NODE=1). If the AppImage moves, re-run
+# "Install 'penguin' Command" from the PenguinHarness application menu.
+APPIMAGE_PATH='${appImagePath}'
+if [ ! -x "$APPIMAGE_PATH" ]; then
+  echo "penguin: AppImage not found at $APPIMAGE_PATH (moved or deleted?)." >&2
+  echo "penguin: re-run \\"Install 'penguin' Command\\" from the PenguinHarness menu." >&2
+  exit 1
+fi
+export ELECTRON_RUN_AS_NODE=1
+# The -- ends Node option parsing: without it a leading-dash argument (penguin --help)
+# would be swallowed as a Node flag instead of reaching the CLI.
+exec "$APPIMAGE_PATH" -e '${appImageBootstrapJs()}' -- "$@"
+`;
+}
+
+/**
+ * Idempotent HKCU\\Environment PATH append: returns the new value to write, or null
+ * when `binDir` is already present (comparison ignores case, surrounding quotes and
+ * trailing slashes). The existing value is preserved verbatim — only `;binDir` is
+ * appended — so other software's entries are never rewritten.
+ */
+export function mergeWindowsUserPath(
+  current: string | null | undefined,
+  binDir: string,
+): string | null {
+  const normalize = (entry: string): string =>
+    entry
+      .trim()
+      .replace(/^"|"$/g, "")
+      .replace(/[\\/]+$/, "")
+      .toLowerCase();
+  const target = binDir.trim().replace(/[\\/]+$/, "");
+  const base = (current ?? "").trim();
+  const present = base
+    .split(";")
+    .map(normalize)
+    .some((entry) => entry !== "" && entry === normalize(target));
+  if (present) return null;
+  if (base === "") return target;
+  return base.endsWith(";") ? `${base}${target}` : `${base};${target}`;
+}
+
+export type CliInstallKind = "darwin" | "windows" | "appimage";
+
+/**
+ * Whether (and how) this run can install the `penguin` command onto PATH. Dev runs have
+ * no staged bin/; deb installs already ship a /usr/bin symlink from their postinst
+ * script (build/linux/after-install.tpl), so only the AppImage form qualifies on Linux
+ * (recognized by the APPIMAGE env var its runtime sets).
+ */
+export function cliInstallKind(opts: {
+  packaged: boolean;
+  platform: NodeJS.Platform;
+  appImagePath: string | null;
+}): CliInstallKind | null {
+  if (!opts.packaged) return null;
+  if (opts.platform === "darwin") return "darwin";
+  if (opts.platform === "win32") return "windows";
+  if (opts.platform === "linux" && opts.appImagePath !== null && opts.appImagePath !== "") {
+    return "appimage";
+  }
+  return null;
+}

packages/desktop/src/main.ts

@@ -19,6 +19,9 @@ import path from "node:path";
 import { app, BrowserWindow, dialog, shell } from "electron";
 import { resolveRoot } from "@prismshadow/penguin-core";
 import { liveServerLock } from "@prismshadow/penguin-server/lock";
+import { resolveWindowIcon } from "./app-icon.js";
+import { installCliCommand, maybeOfferCliInstall, currentCliInstallKind } from "./cli-install.js";
+import { installAppMenu } from "./menu.js";
 import { startEmbeddedServer, stopEmbeddedServer } from "./server-process.js";
 import type { EmbeddedServer } from "./server-process.js";
 import {
@@ -30,6 +33,10 @@ import {
 } from "./util.js";
 
 app.setName("PenguinHarness");
+// Windows toasts (the web app's task-completion notifications) need the AppUserModelID
+// of the installed shortcuts; electron-builder stamps them with the appId. Keep in sync
+// with electron-builder.yml.
+if (process.platform === "win32") app.setAppUserModelId("com.prismshadow.penguinharness");
 
 let win: BrowserWindow | null = null;
 let server: EmbeddedServer | null = null;
@@ -46,11 +53,15 @@ function fatal(context: string, err: unknown): void {
 }
 
 function createWindow(url: string): void {
+  // Linux window/taskbar icon (and Windows dev runs); packaged Windows uses the exe
+  // resources and macOS its bundle icns, so those ignore it (see app-icon.ts).
+  const iconPath = resolveWindowIcon(app.getAppPath(), process.platform);
   win = new BrowserWindow({
     width: 1280,
     height: 860,
     show: false,
     autoHideMenuBar: true,
+    ...(iconPath !== null ? { icon: iconPath } : {}),
     webPreferences: {
       // The window is a plain browser: no Node, no preload — the minimal attack surface.
       contextIsolation: true,
@@ -75,6 +86,7 @@ function createWindow(url: string): void {
           width: 1100,
           height: 800,
           autoHideMenuBar: true,
+          ...(iconPath !== null ? { icon: iconPath } : {}),
           // Same hardening as the main window: the preview is Agent-written, untrusted
           // HTML and must never get Node.
           webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true },
@@ -202,9 +214,20 @@ if (!app.requestSingleInstanceLock()) {
     }
   });
 
-  void app
-    .whenReady()
-    .then(() => boot().catch((err) => fatal("PenguinHarness failed to start.", err)));
+  void app.whenReady().then(() =>
+    (async () => {
+      // Standard menu plus the CLI-install entry where installing makes sense
+      // (packaged macOS / Windows / AppImage; deb ships /usr/bin/penguin itself).
+      installAppMenu({
+        includeCliInstall: currentCliInstallKind() !== null,
+        onInstallCli: () => void installCliCommand(win),
+      });
+      await boot();
+      // First launch only: offer the 'penguin' command once; the menu entry remains.
+      // Skipped in smoke mode — a modal dialog would hang the automated run.
+      if (process.env.PENGUIN_DESKTOP_SMOKE !== "1") await maybeOfferCliInstall(win);
+    })().catch((err) => fatal("PenguinHarness failed to start.", err)),
+  );
 }
 
 // --- smoke hook ------------------------------------------------------------

packages/desktop/src/menu.ts

@@ -0,0 +1,54 @@
+/**
+ * Application menu. Electron's default menu cannot be extended, only replaced, so the
+ * standard structure is rebuilt here — on macOS the Edit roles are what make clipboard
+ * shortcuts work inside the window, so they must be present. The one custom entry is
+ * "Install 'penguin' Command…" (see cli-install.ts), shown only where installing makes
+ * sense (packaged macOS / Windows / AppImage; deb ships /usr/bin/penguin itself).
+ * On Windows/Linux the window uses autoHideMenuBar, so the bar appears on Alt.
+ */
+import { app, Menu } from "electron";
+import type { MenuItemConstructorOptions } from "electron";
+
+export const INSTALL_CLI_MENU_LABEL = "Install 'penguin' Command…";
+
+export function installAppMenu(opts: {
+  includeCliInstall: boolean;
+  onInstallCli: () => void;
+}): void {
+  const isMac = process.platform === "darwin";
+  const cliItems: MenuItemConstructorOptions[] = opts.includeCliInstall
+    ? [{ label: INSTALL_CLI_MENU_LABEL, click: opts.onInstallCli }]
+    : [];
+
+  const template: MenuItemConstructorOptions[] = [];
+  if (isMac) {
+    template.push({
+      label: app.name,
+      submenu: [
+        { role: "about" },
+        ...(cliItems.length > 0
+          ? ([{ type: "separator" }, ...cliItems] as MenuItemConstructorOptions[])
+          : []),
+        { type: "separator" },
+        { role: "services" },
+        { type: "separator" },
+        { role: "hide" },
+        { role: "hideOthers" },
+        { role: "unhide" },
+        { type: "separator" },
+        { role: "quit" },
+      ],
+    });
+  } else {
+    template.push({
+      label: "File",
+      submenu: [
+        ...cliItems,
+        ...(cliItems.length > 0 ? ([{ type: "separator" }] as MenuItemConstructorOptions[]) : []),
+        { role: "quit" },
+      ],
+    });
+  }
+  template.push({ role: "editMenu" }, { role: "viewMenu" }, { role: "windowMenu" });
+  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+}

packages/desktop/test/app-icon.test.ts

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, it } from "vitest";
+import { resolveWindowIcon, WINDOW_ICON_RELPATH, windowIconPathFor } from "../src/app-icon.js";
+
+describe("windowIconPathFor", () => {
+  it("is null on macOS (window icons are ignored; the bundle icns owns the Dock)", () => {
+    expect(windowIconPathFor("/app", "darwin")).toBeNull();
+  });
+
+  it("resolves build/icon.png inside the app dir on Linux and Windows", () => {
+    expect(windowIconPathFor("/app", "linux")).toBe(path.join("/app", ...WINDOW_ICON_RELPATH));
+    expect(windowIconPathFor("C:\\app", "win32")).toBe(
+      path.join("C:\\app", ...WINDOW_ICON_RELPATH),
+    );
+  });
+});
+
+describe("resolveWindowIcon", () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "penguin-desktop-icon-"));
+  afterAll(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  it("returns the path only when the file exists", () => {
+    expect(resolveWindowIcon(tmp, "linux")).toBeNull();
+    fs.mkdirSync(path.join(tmp, "build"), { recursive: true });
+    fs.writeFileSync(path.join(tmp, "build", "icon.png"), "png");
+    expect(resolveWindowIcon(tmp, "linux")).toBe(path.join(tmp, "build", "icon.png"));
+    expect(resolveWindowIcon(tmp, "darwin")).toBeNull();
+  });
+
+  it("the committed source icon resolves for a dev run of this package", () => {
+    const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    expect(resolveWindowIcon(pkgDir, "linux")).toBe(path.join(pkgDir, "build", "icon.png"));
+  });
+});

packages/desktop/test/launcher.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from "vitest";
+import {
+  appImageBootstrapJs,
+  appImageWrapperScript,
+  CLI_ENTRY_RELPATH,
+  cliInstallKind,
+  LINUX_EXECUTABLE,
+  MAC_EXECUTABLE,
+  mergeWindowsUserPath,
+  posixLauncherScript,
+  WIN_EXECUTABLE,
+  windowsLauncherScript,
+} from "../src/launcher.js";
+
+describe("posixLauncherScript", () => {
+  const script = posixLauncherScript();
+
+  it("is a /bin/sh script that resolves symlinks before locating the runtime", () => {
+    expect(script.startsWith("#!/bin/sh\n")).toBe(true);
+    expect(script).toContain('while [ -h "$SOURCE" ]');
+    expect(script).toContain("readlink");
+  });
+
+  it("targets the bundled CLI entry and both platform runtime locations", () => {
+    expect(script).toContain(`CLI_ENTRY="$APP_DIR/${CLI_ENTRY_RELPATH}"`);
+    // macOS: resources/app -> ../../MacOS/<executable>; Linux: -> ../../<executableName>.
+    expect(script).toContain(`"$APP_DIR/../../MacOS/${MAC_EXECUTABLE}"`);
+    expect(script).toContain(`"$APP_DIR/../../${LINUX_EXECUTABLE}"`);
+  });
+
+  it("execs as Node and forwards all arguments", () => {
+    expect(script).toContain("export ELECTRON_RUN_AS_NODE=1");
+    expect(script).toContain('exec "$CANDIDATE" "$CLI_ENTRY" "$@"');
+  });
+
+  it("fails with a message when no runtime is found", () => {
+    expect(script).toContain("exit 1");
+  });
+});
+
+describe("windowsLauncherScript", () => {
+  const script = windowsLauncherScript();
+
+  it("uses CRLF line endings (cmd.exe is unreliable with bare LF)", () => {
+    expect(script).toContain("\r\n");
+    expect(script.split("\r\n").join("")).not.toContain("\n");
+  });
+
+  it("finds the exe three levels up from bin\\ and the CLI entry in the app dir", () => {
+    expect(script).toContain(`"%~dp0..\\..\\..\\${WIN_EXECUTABLE}"`);
+    expect(script).toContain(`"%~dp0..\\${CLI_ENTRY_RELPATH.replaceAll("/", "\\")}"`);
+  });
+
+  it("runs as Node, forwards arguments and propagates the exit code", () => {
+    expect(script).toContain('set "ELECTRON_RUN_AS_NODE=1"');
+    expect(script).toContain(" %*");
+    expect(script).toContain("exit /b %errorlevel%");
+  });
+});
+
+describe("appImageWrapperScript", () => {
+  const appImage = "/home/user/Apps/penguin-desktop-linux-x86_64.AppImage";
+  const script = appImageWrapperScript(appImage);
+
+  it("bakes in the AppImage path and guards against it disappearing", () => {
+    expect(script).toContain(`APPIMAGE_PATH='${appImage}'`);
+    expect(script).toContain('if [ ! -x "$APPIMAGE_PATH" ]');
+  });
+
+  it("invokes the AppImage as Node with the bootstrap and forwards arguments", () => {
+    expect(script).toContain("export ELECTRON_RUN_AS_NODE=1");
+    // The -- is load-bearing: without it Node swallows leading-dash arguments
+    // (penguin --help) as its own flags instead of passing them to the CLI.
+    expect(script).toContain(`exec "$APPIMAGE_PATH" -e '${appImageBootstrapJs()}' -- "$@"`);
+  });
+
+  it("refuses paths containing single quotes (they would break the quoting)", () => {
+    expect(() => appImageWrapperScript("/tmp/it's.AppImage")).toThrow(/single quote/);
+  });
+});
+
+describe("appImageBootstrapJs", () => {
+  const js = appImageBootstrapJs();
+
+  it("contains no single quotes (embedded in a single-quoted shell string)", () => {
+    expect(js).not.toContain("'");
+  });
+
+  it("resolves the CLI entry relative to process.execPath and fixes argv", () => {
+    expect(js).toContain("process.execPath");
+    expect(js).toContain('"resources","app"');
+    expect(js).toContain('"penguin-cli","dist","index.js"');
+    // node -e argv is [execPath, ...args]; the CLI slices argv from index 2, so the
+    // entry path must be spliced in at index 1.
+    expect(js).toContain("process.argv.splice(1,0,cli)");
+    expect(js).toContain("import(cli)");
+  });
+
+  it("is valid JavaScript", () => {
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval
+    expect(() => new Function(js)).not.toThrow();
+  });
+});
+
+describe("mergeWindowsUserPath", () => {
+  const bin = "C:\\Program Files\\PenguinHarness\\resources\\app\\bin";
+
+  it("appends to an existing value with a semicolon", () => {
+    expect(mergeWindowsUserPath("C:\\other", bin)).toBe(`C:\\other;${bin}`);
+  });
+
+  it("does not double the separator when the value ends with one", () => {
+    expect(mergeWindowsUserPath("C:\\other;", bin)).toBe(`C:\\other;${bin}`);
+  });
+
+  it("starts a missing or empty value with just the bin dir", () => {
+    expect(mergeWindowsUserPath(null, bin)).toBe(bin);
+    expect(mergeWindowsUserPath("", bin)).toBe(bin);
+    expect(mergeWindowsUserPath("   ", bin)).toBe(bin);
+  });
+
+  it("is idempotent: returns null when already present", () => {
+    expect(mergeWindowsUserPath(`C:\\other;${bin}`, bin)).toBeNull();
+  });
+
+  it("matches case-insensitively and ignores quotes and trailing slashes", () => {
+    expect(
+      mergeWindowsUserPath(`c:\\program files\\penguinharness\\RESOURCES\\app\\BIN`, bin),
+    ).toBeNull();
+    expect(mergeWindowsUserPath(`"${bin}"`, bin)).toBeNull();
+    expect(mergeWindowsUserPath(`${bin}\\`, bin)).toBeNull();
+  });
+
+  it("preserves the existing value verbatim (including %VAR% entries)", () => {
+    const current = "%USERPROFILE%\\bin;C:\\tools";
+    expect(mergeWindowsUserPath(current, bin)).toBe(`${current};${bin}`);
+  });
+});
+
+describe("cliInstallKind", () => {
+  it("is null for dev runs regardless of platform", () => {
+    expect(cliInstallKind({ packaged: false, platform: "darwin", appImagePath: null })).toBeNull();
+    expect(cliInstallKind({ packaged: false, platform: "win32", appImagePath: null })).toBeNull();
+  });
+
+  it("maps packaged macOS and Windows to their installers", () => {
+    expect(cliInstallKind({ packaged: true, platform: "darwin", appImagePath: null })).toBe(
+      "darwin",
+    );
+    expect(cliInstallKind({ packaged: true, platform: "win32", appImagePath: null })).toBe(
+      "windows",
+    );
+  });
+
+  it("on Linux only the AppImage form installs (deb ships /usr/bin/penguin itself)", () => {
+    expect(cliInstallKind({ packaged: true, platform: "linux", appImagePath: null })).toBeNull();
+    expect(cliInstallKind({ packaged: true, platform: "linux", appImagePath: "" })).toBeNull();
+    expect(
+      cliInstallKind({ packaged: true, platform: "linux", appImagePath: "/x/y.AppImage" }),
+    ).toBe("appimage");
+  });
+});

packages/desktop/tsup.config.ts

@@ -1,7 +1,9 @@
 import { defineConfig } from "tsup";
 
 export default defineConfig({
-  entry: ["src/main.ts"],
+  // launcher.ts is a second entry on purpose: scripts/stage.mjs imports dist/launcher.js
+  // at stage time (plain node, no Electron) to generate the CLI launcher scripts.
+  entry: ["src/main.ts", "src/launcher.ts"],
   format: ["esm"],
   target: "node22",
   platform: "node",

packages/docs/content/server-api.en.md

@@ -67,6 +67,8 @@ curl -c cookies.txt -H "Content-Type: application/json" \
 | POST | /api/admin/users/:userId/password | Reset a password (invalidates all of that user's login sessions) |
 | DELETE | /api/admin/users/:userId | Delete a user |
 
+In desktop mode (the server spawned by the desktop app) the whole surface answers `403` with code `desktop_single_user`: the desktop app is single-user, so user management is disabled — existing users in the data root are untouched.
+
 ### Server Settings (admin only)
 
 | Method | Path | Description |
@@ -97,7 +99,7 @@ curl -c cookies.txt -H "Content-Type: application/json" \
 | POST | /api/projects/:projectId/members | Add a member: `{userId}` |
 | DELETE | /api/projects/:projectId/members/:userId | Remove a member |
 
-Member writes are owner-only.
+Member writes are owner-only. The member routes also answer `403 desktop_single_user` in desktop mode (see User Administration above).
 
 ### Models
 

packages/docs/content/server-api.zh.md

@@ -67,6 +67,8 @@ curl -c cookies.txt -H "Content-Type: application/json" \
 | POST | /api/admin/users/:userId/password | 重置密码（该用户全部登录会话失效） |
 | DELETE | /api/admin/users/:userId | 删除用户 |
 
+桌面模式下（server 由桌面应用拉起）整组路由返回 `403`、错误码 `desktop_single_user`：桌面应用是单用户形态，用户管理整体停用——数据根中已有的用户不受影响。
+
 ### 服务端设置（仅管理员）
 
 | 方法 | 路径 | 说明 |
@@ -97,7 +99,7 @@ curl -c cookies.txt -H "Content-Type: application/json" \
 | POST | /api/projects/:projectId/members | 添加成员：`{userId}` |
 | DELETE | /api/projects/:projectId/members/:userId | 移除成员 |
 
-成员写操作仅限 Owner。
+成员写操作仅限 Owner。成员路由在桌面模式下同样返回 `403 desktop_single_user`（见上文「用户管理」）。
 
 ### 模型
 

packages/server/src/http/routes/admin.ts

@@ -1,10 +1,12 @@
 /**
- * Admin user-backend routes: only the built-in admin can use these (403 for non-admins).
+ * Admin user-backend routes: only the built-in admin can use these (403 for non-admins),
+ * and desktop mode rejects the whole surface (single-user; 403 `desktop_single_user`).
  * GET|POST /api/admin/users, POST /api/admin/users/:userId/password, DELETE /api/admin/users/:userId.
  */
 import { Hono } from "hono";
 import type { AdminUserCreateResponse, AdminUsersResponse } from "../../api/types.js";
 import { HttpError } from "../errors.js";
+import { rejectInDesktopMode } from "./desktop.js";
 import type { AppEnv } from "../../auth/middleware.js";
 import { pathParam, readJson, requireString } from "../validate.js";
 import type { AppDeps } from "../../app.js";
@@ -12,6 +14,7 @@ import type { AppDeps } from "../../app.js";
 export function adminUsersRoutes(deps: AppDeps): Hono<AppEnv> {
   const app = new Hono<AppEnv>();
 
+  app.use("*", rejectInDesktopMode(deps));
   app.use("*", async (c, next) => {
     if (!c.var.user.isAdmin) {
       throw new HttpError(403, "admin_required", "Only an admin can perform this operation.");

packages/server/src/http/routes/desktop.ts

@@ -1,15 +1,37 @@
 /**
- * Desktop-mode routes: POST /api/desktop/shutdown.
+ * Desktop-mode routes: POST /api/desktop/shutdown, plus the shared desktop-mode guard
+ * that turns off multi-user surfaces (see rejectInDesktopMode).
  *
- * Authenticated by the shell's Bearer token, not the cookie session (the shell holds no
- * cookie), so this mounts OUTSIDE authMiddleware and only when desktop mode is enabled.
- * Responds 202 first, then triggers the graceful shutdown a beat later so the response
- * isn't cut off by the closing listener.
+ * The shutdown route is authenticated by the shell's Bearer token, not the cookie
+ * session (the shell holds no cookie), so it mounts OUTSIDE authMiddleware and only
+ * when desktop mode is enabled. Responds 202 first, then triggers the graceful
+ * shutdown a beat later so the response isn't cut off by the closing listener.
  */
 import { Hono } from "hono";
+import type { MiddlewareHandler } from "hono";
 import { HttpError } from "../errors.js";
 import type { AppDeps } from "../../app.js";
 
+/**
+ * Guard for user-management surfaces (admin users, Project members): the desktop app is
+ * single-user, so the whole surface answers 403 with a dedicated code rather than being
+ * unmounted — a stray client gets a clear, localizable error instead of a 404. Existing
+ * users and memberships in the data root are untouched; only the management routes are
+ * closed while the server runs under the desktop shell.
+ */
+export function rejectInDesktopMode(deps: AppDeps): MiddlewareHandler {
+  return async (_c, next) => {
+    if (deps.desktop !== null) {
+      throw new HttpError(
+        403,
+        "desktop_single_user",
+        "User management is disabled in the desktop app (single-user mode).",
+      );
+    }
+    await next();
+  };
+}
+
 /** Delay between answering 202 and starting shutdown: lets the response flush. */
 const SHUTDOWN_DELAY_MS = 50;
 

packages/server/src/http/routes/members.ts

@@ -2,16 +2,20 @@
  * Member authorization routes:
  * GET|POST /api/projects/:p/members, DELETE /api/projects/:p/members/:userId.
  * Reading requires access; adding/removing is owner-only (validated inside the service).
+ * Desktop mode rejects the whole surface (single-user; 403 `desktop_single_user`).
  */
 import { Hono } from "hono";
 import type { MemberAddResponse, MembersResponse } from "../../api/types.js";
 import type { AppEnv } from "../../auth/middleware.js";
+import { rejectInDesktopMode } from "./desktop.js";
 import { pathParam, readJson, requireString, requireValidId } from "../validate.js";
 import type { AppDeps } from "../../app.js";
 
 export function membersRoutes(deps: AppDeps): Hono<AppEnv> {
   const app = new Hono<AppEnv>();
 
+  app.use("*", rejectInDesktopMode(deps));
+
   app.get("/", (c) => {
     // Defensive id validation (FD-4).
     const members = deps.projectService.listMembers(

packages/server/test/desktop.test.ts

@@ -1,10 +1,11 @@
 /**
  * Desktop mode: one-shot desktop-login, Bearer-token shutdown, desktopMode in /api/me,
- * and the desktop-session password change without oldPassword.
+ * the desktop-session password change without oldPassword, and the single-user guard
+ * closing the user-management and Project-member surfaces.
  */
 import { describe, expect, it } from "vitest";
 import { apiClient, createTestApp, loginAdmin } from "./helpers.js";
-import type { MeResponse } from "../src/api/types.js";
+import type { ErrorBody, MeResponse } from "../src/api/types.js";
 
 const TOKEN = "test-desktop-token";
 
@@ -119,6 +120,75 @@ describe("desktop shutdown endpoint", () => {
   });
 });
 
+describe("desktop single-user mode", () => {
+  async function expectSingleUser403(res: Response): Promise<void> {
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as ErrorBody;
+    expect(body.error.code).toBe("desktop_single_user");
+  }
+
+  it("rejects the whole admin-users surface with desktop_single_user", async () => {
+    const t = await desktopApp();
+    try {
+      // The seeded admin signed in through the regular login form: even a fully
+      // authorized admin session gets the dedicated 403, not admin_required.
+      const admin = await loginAdmin(t.app);
+      const api = apiClient(t.app, admin.cookie);
+      await expectSingleUser403(await api.get("/api/admin/users"));
+      await expectSingleUser403(
+        await api.post("/api/admin/users", { userId: "eve", password: "password-123" }),
+      );
+      await expectSingleUser403(
+        await api.post("/api/admin/users/admin/password", { password: "password-456" }),
+      );
+      await expectSingleUser403(
+        await t.app.request("/api/admin/users/eve", {
+          method: "DELETE",
+          headers: { cookie: admin.cookie },
+        }),
+      );
+      // No user was created by the rejected POST.
+      expect(t.deps.db.prepare("SELECT COUNT(*) AS n FROM users").get()?.n).toBe(1);
+    } finally {
+      await t.cleanup();
+    }
+  });
+
+  it("rejects Project member management (reads and writes) with desktop_single_user", async () => {
+    const t = await desktopApp();
+    try {
+      const admin = await loginAdmin(t.app);
+      const api = apiClient(t.app, admin.cookie);
+      await expectSingleUser403(await api.get("/api/projects/default_project/members"));
+      await expectSingleUser403(
+        await api.post("/api/projects/default_project/members", { userId: "eve" }),
+      );
+      await expectSingleUser403(
+        await t.app.request("/api/projects/default_project/members/eve", {
+          method: "DELETE",
+          headers: { cookie: admin.cookie },
+        }),
+      );
+    } finally {
+      await t.cleanup();
+    }
+  });
+
+  it("leaves both surfaces working on a normal multi-user server", async () => {
+    const t = await createTestApp();
+    try {
+      const admin = await loginAdmin(t.app);
+      const api = apiClient(t.app, admin.cookie);
+      const users = await api.get("/api/admin/users");
+      expect(users.status).toBe(200);
+      const members = await api.get("/api/projects/default_project/members");
+      expect(members.status).toBe(200);
+    } finally {
+      await t.cleanup();
+    }
+  });
+});
+
 describe("desktop-session password change", () => {
   async function desktopCookie(t: Awaited<ReturnType<typeof desktopApp>>): Promise<string> {
     const res = await t.app.request(`/api/auth/desktop-login?token=${TOKEN}`);

packages/web/src/components/layout/app-layout.tsx

@@ -12,6 +12,7 @@ import { useVersionInfo } from "../../lib/use-version-info";
 import { useAuth } from "../../state/auth";
 import { useProject } from "../../state/project";
 import { useSessions } from "../../state/sessions";
+import { useCompletionNotifications } from "../../state/use-completion-notifications";
 import { Drawer } from "../ui/drawer";
 import { GlyphIcon } from "../ui/glyph-icon";
 import { NAV_ICONS } from "../ui/icons";
@@ -167,6 +168,9 @@ function CollapsedRail({ onExpand }: { onExpand: () => void }) {
 
 export function AppLayout() {
   const { user, desktopMode } = useAuth();
+  // Desktop shell only (gated inside): system notification when a task finishes while
+  // the window is unfocused.
+  useCompletionNotifications();
   const [drawerOpen, setDrawerOpen] = useState(false);
   const [changePasswordOpen, setChangePasswordOpen] = useState(false);
   // Desktop sidebar collapse (persisted): collapsed state leaves a narrow rail to expand from.

packages/web/src/components/layout/project-dialogs.tsx

@@ -172,7 +172,7 @@ export function CreateProjectDialog({
  * deletion (owner); members see the name and member list read-only.
  */
 export function ProjectSettingsDialog({ open, onClose }: { open: boolean; onClose: () => void }) {
-  const { user } = useAuth();
+  const { user, desktopMode } = useAuth();
   const { currentProject, setCurrentProjectId, projects, reloadProjects } = useProject();
   const [members, setMembers] = useState<MemberInfo[] | null>(null);
   const [newMemberId, setNewMemberId] = useState("");
@@ -196,14 +196,18 @@ export function ProjectSettingsDialog({ open, onClose }: { open: boolean; onClos
     setConfirmDelete(false);
     setName(savedName);
     setNameError(undefined);
-    api
-      .listMembers(projectId)
-      .then((res) => setMembers(res.members))
-      .catch((e: unknown) => setLoadError(apiErrorText(e)));
+    // Desktop mode is single-user: the member section is hidden below and the server
+    // rejects the member routes (desktop_single_user), so nothing is fetched.
+    if (!desktopMode) {
+      api
+        .listMembers(projectId)
+        .then((res) => setMembers(res.members))
+        .catch((e: unknown) => setLoadError(apiErrorText(e)));
+    }
     // savedName is read at open time only: retyping in the field must not be clobbered by a
     // list refresh, and reopening the dialog re-seeds it.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [open, projectId]);
+  }, [open, projectId, desktopMode]);
 
   if (!currentProject || !projectId) return null;
 
@@ -306,76 +310,85 @@ export function ProjectSettingsDialog({ open, onClose }: { open: boolean; onClos
           <p className="mt-1 font-mono text-xs text-gray-400">{projectId}</p>
         </div>
 
-        <div>
-          <p className="mb-2 text-xs font-medium text-gray-500">{S.project.members}</p>
-          {loadError ? (
-            <p className="text-xs text-red-600 dark:text-red-400">{loadError}</p>
-          ) : members === null ? (
-            <p className="text-xs text-gray-400">{S.common.loading}</p>
-          ) : (
-            // Member permission table: username / role / actions; cells never wrap.
-            // Last row (owner only) = add member: small username input + add button (new members are always the member role).
-            <div className="overflow-x-auto rounded-md border border-gray-200 dark:border-gray-800">
-              <table className="w-full text-xs">
-                <thead>
-                  <tr className="border-b border-gray-100 bg-gray-50 text-left text-gray-500 dark:border-gray-800 dark:bg-gray-900/60 dark:text-gray-400">
-                    <th className="whitespace-nowrap px-2.5 py-1.5 font-medium">
-                      {S.common.username}
-                    </th>
-                    <th className="whitespace-nowrap px-2.5 py-1.5 font-medium">{S.common.role}</th>
-                    <th className="w-20 whitespace-nowrap px-2.5 py-1.5 text-right font-medium">
-                      {S.common.actions}
-                    </th>
-                  </tr>
-                </thead>
-                <tbody className="divide-y divide-gray-100 dark:divide-gray-800/60">
-                  {members.map((m) => (
-                    <tr key={m.userId}>
-                      <td className="whitespace-nowrap px-2.5 py-1.5">{m.userId}</td>
-                      <td className="whitespace-nowrap px-2.5 py-1.5">
-                        <Badge tone="gray">{m.role}</Badge>
-                      </td>
-                      <td className="whitespace-nowrap px-2.5 py-1 text-right">
-                        {isOwner && m.role !== "owner" && m.userId !== user?.userId && (
-                          <Button size="sm" variant="ghost" onClick={() => void doRemove(m.userId)}>
-                            {S.project.removeMember}
+        {/* Member management does not exist in the single-user desktop app. */}
+        {!desktopMode && (
+          <div>
+            <p className="mb-2 text-xs font-medium text-gray-500">{S.project.members}</p>
+            {loadError ? (
+              <p className="text-xs text-red-600 dark:text-red-400">{loadError}</p>
+            ) : members === null ? (
+              <p className="text-xs text-gray-400">{S.common.loading}</p>
+            ) : (
+              // Member permission table: username / role / actions; cells never wrap.
+              // Last row (owner only) = add member: small username input + add button (new members are always the member role).
+              <div className="overflow-x-auto rounded-md border border-gray-200 dark:border-gray-800">
+                <table className="w-full text-xs">
+                  <thead>
+                    <tr className="border-b border-gray-100 bg-gray-50 text-left text-gray-500 dark:border-gray-800 dark:bg-gray-900/60 dark:text-gray-400">
+                      <th className="whitespace-nowrap px-2.5 py-1.5 font-medium">
+                        {S.common.username}
+                      </th>
+                      <th className="whitespace-nowrap px-2.5 py-1.5 font-medium">
+                        {S.common.role}
+                      </th>
+                      <th className="w-20 whitespace-nowrap px-2.5 py-1.5 text-right font-medium">
+                        {S.common.actions}
+                      </th>
+                    </tr>
+                  </thead>
+                  <tbody className="divide-y divide-gray-100 dark:divide-gray-800/60">
+                    {members.map((m) => (
+                      <tr key={m.userId}>
+                        <td className="whitespace-nowrap px-2.5 py-1.5">{m.userId}</td>
+                        <td className="whitespace-nowrap px-2.5 py-1.5">
+                          <Badge tone="gray">{m.role}</Badge>
+                        </td>
+                        <td className="whitespace-nowrap px-2.5 py-1 text-right">
+                          {isOwner && m.role !== "owner" && m.userId !== user?.userId && (
+                            <Button
+                              size="sm"
+                              variant="ghost"
+                              onClick={() => void doRemove(m.userId)}
+                            >
+                              {S.project.removeMember}
+                            </Button>
+                          )}
+                        </td>
+                      </tr>
+                    ))}
+                    {isOwner && (
+                      <tr>
+                        <td className="px-2.5 py-1.5">
+                          <Input
+                            placeholder={S.common.username}
+                            size="sm"
+                            value={newMemberId}
+                            onChange={(e) => setNewMemberId(e.target.value)}
+                            onKeyDown={(e) => {
+                              if (e.key === "Enter") void addMember();
+                            }}
+                          />
+                        </td>
+                        <td className="whitespace-nowrap px-2.5 py-1.5">
+                          <Badge tone="gray">member</Badge>
+                        </td>
+                        <td className="whitespace-nowrap px-2.5 py-1 text-right">
+                          <Button
+                            size="sm"
+                            disabled={!newMemberId.trim()}
+                            onClick={() => void addMember()}
+                          >
+                            {S.project.addMember}
                           </Button>
-                        )}
-                      </td>
-                    </tr>
-                  ))}
-                  {isOwner && (
-                    <tr>
-                      <td className="px-2.5 py-1.5">
-                        <Input
-                          placeholder={S.common.username}
-                          size="sm"
-                          value={newMemberId}
-                          onChange={(e) => setNewMemberId(e.target.value)}
-                          onKeyDown={(e) => {
-                            if (e.key === "Enter") void addMember();
-                          }}
-                        />
-                      </td>
-                      <td className="whitespace-nowrap px-2.5 py-1.5">
-                        <Badge tone="gray">member</Badge>
-                      </td>
-                      <td className="whitespace-nowrap px-2.5 py-1 text-right">
-                        <Button
-                          size="sm"
-                          disabled={!newMemberId.trim()}
-                          onClick={() => void addMember()}
-                        >
-                          {S.project.addMember}
-                        </Button>
-                      </td>
-                    </tr>
-                  )}
-                </tbody>
-              </table>
-            </div>
-          )}
-        </div>
+                        </td>
+                      </tr>
+                    )}
+                  </tbody>
+                </table>
+              </div>
+            )}
+          </div>
+        )}
 
         <ChatDefaultsSection projectId={projectId} isOwner={isOwner} />
 

packages/web/src/components/layout/sidebar.tsx

@@ -1119,8 +1119,10 @@ export function Sidebar({
                 )}
               </button>
             )}
-            {/* User management is visible only to admins (the page route also has its own guard as a fallback). */}
-            {user?.isAdmin && (
+            {/* User management is visible only to admins (the page route also has its own
+                guard as a fallback), and never in desktop mode: the desktop app is
+                single-user and the server rejects the routes (desktop_single_user). */}
+            {user?.isAdmin && !desktopMode && (
               <button
                 type="button"
                 className={menuItemClass}

packages/web/src/features/admin/admin-users-page.tsx

@@ -23,7 +23,7 @@ import { Modal } from "../../components/ui/modal";
 
 export function AdminUsersPage() {
   useDocumentTitle(S.admin.users);
-  const { user } = useAuth();
+  const { user, desktopMode } = useAuth();
   const [users, setUsers] = useState<UserInfo[] | null>(null);
   const [listError, setListError] = useState<string | null>(null);
   const [createOpen, setCreateOpen] = useState(false);
@@ -40,11 +40,13 @@ export function AdminUsersPage() {
   }, []);
 
   useEffect(() => {
-    if (user?.isAdmin) void reload();
-  }, [user?.isAdmin, reload]);
+    if (user?.isAdmin && !desktopMode) void reload();
+  }, [user?.isAdmin, desktopMode, reload]);
 
-  // Route guard fallback: non-admins are redirected back to the chat page (the sidebar has no entry point anyway).
-  if (user && !user.isAdmin) return <Navigate to="/chat" replace />;
+  // Route guard fallback: non-admins are redirected back to the chat page (the sidebar has
+  // no entry point anyway); same for desktop mode, where the app is single-user and the
+  // server rejects the admin-user routes (desktop_single_user).
+  if (user && (!user.isAdmin || desktopMode)) return <Navigate to="/chat" replace />;
 
   return (
     <div className="h-full overflow-y-auto p-4 md:p-6">

packages/web/src/lib/completion-notify.ts

@@ -0,0 +1,75 @@
+/**
+ * Task-completion detection over the tracked Session list (pure logic, node-testable —
+ * the desktop notification hook in state/use-completion-notifications.ts drives it).
+ *
+ * A Session is "active" while running or compacting; a completion is the transition of
+ * a KNOWN active Session to idle. First observations never fire — a freshly loaded list
+ * only states where sessions already are, it doesn't witness a finish. Because the
+ * transition flips the stored state, each run fires at most once (the per-session+run
+ * dedupe); on top of that, a short per-session cooldown swallows the flap where a stale
+ * list snapshot racing the live SSE flip briefly resurrects "running" and would
+ * otherwise double-notify the same finish.
+ */
+import type { SessionStatus } from "@prismshadow/penguin-server/api";
+
+export interface ObservedSession {
+  sessionId: string;
+  status: SessionStatus;
+}
+
+/** Whether a status counts as an in-flight run. */
+function isActive(status: SessionStatus): boolean {
+  return status === "running" || status === "compacting";
+}
+
+/** Minimum spacing between two completion firings of the same Session (see header). */
+export const COMPLETION_COOLDOWN_MS = 10_000;
+
+export interface CompletionTracker {
+  /**
+   * Feed the current Session list; returns the sessionIds whose run just completed.
+   * `now` is injectable for tests (defaults to Date.now()).
+   */
+  observe(list: readonly ObservedSession[], now?: number): string[];
+}
+
+export function createCompletionTracker(
+  cooldownMs: number = COMPLETION_COOLDOWN_MS,
+): CompletionTracker {
+  interface Entry {
+    active: boolean;
+    lastFiredAt: number | null;
+  }
+  const entries = new Map<string, Entry>();
+  return {
+    observe(list, now = Date.now()) {
+      const completed: string[] = [];
+      const seen = new Set<string>();
+      for (const s of list) {
+        // Defensive: the list is deduplicated upstream, but only the first occurrence
+        // of an id may drive the state machine.
+        if (seen.has(s.sessionId)) continue;
+        seen.add(s.sessionId);
+        const active = isActive(s.status);
+        const prev = entries.get(s.sessionId);
+        if (prev === undefined) {
+          entries.set(s.sessionId, { active, lastFiredAt: null });
+          continue;
+        }
+        if (prev.active && !active) {
+          if (prev.lastFiredAt === null || now - prev.lastFiredAt >= cooldownMs) {
+            completed.push(s.sessionId);
+            prev.lastFiredAt = now;
+          }
+        }
+        prev.active = active;
+      }
+      // Prune vanished sessions (deleted / Project switch): reappearing later counts as
+      // a fresh first observation, which never fires.
+      for (const id of [...entries.keys()]) {
+        if (!seen.has(id)) entries.delete(id);
+      }
+      return completed;
+    },
+  };
+}

packages/web/src/lib/strings-en.ts

@@ -92,6 +92,13 @@ export const en: Strings = {
     adminOnly: "Only an administrator can run the update from here.",
   },
 
+  /** Desktop task-completion notifications (window unfocused; desktop-shell sessions only). */
+  notify: {
+    taskCompleteTitle: "Task completed",
+    /** `session` is the Session title (defaultSessionTitle when unnamed). */
+    taskCompleteBody: (session: string): string => `"${session}" has finished — click to view`,
+  },
+
   common: {
     save: "Save",
     cancel: "Cancel",
@@ -1143,6 +1150,7 @@ Scenarios:
       password_mismatch: "The current password is incorrect.",
       invalid_password: "Password must be at least 8 characters.",
       admin_required: "Only an admin can perform this operation.",
+      desktop_single_user: "The desktop app is single-user; user management is unavailable.",
       not_found: "This resource does not exist, or you do not have access.",
       agent_not_found: "This agent no longer exists.",
       unknown_agent: "That agent does not exist in this Project.",

packages/web/src/lib/strings.ts

@@ -92,6 +92,13 @@ export const zh = {
     adminOnly: "只有管理员可以在这里执行更新。",
   },
 
+  /** Desktop task-completion notifications (window unfocused; desktop-shell sessions only). */
+  notify: {
+    taskCompleteTitle: "任务完成",
+    /** `session` is the Session title (defaultSessionTitle when unnamed). */
+    taskCompleteBody: (session: string): string => `「${session}」已完成，点击查看`,
+  },
+
   common: {
     save: "保存",
     cancel: "取消",
@@ -1117,6 +1124,7 @@ Benchmark：
       password_mismatch: "当前密码不正确。",
       invalid_password: "密码至少 8 位。",
       admin_required: "仅管理员可执行此操作。",
+      desktop_single_user: "桌面应用为单用户模式，用户管理不可用。",
       not_found: "资源不存在，或你没有访问权限。",
       agent_not_found: "该 Agent 已不存在。",
       unknown_agent: "该 Agent 不存在于本 Project。",

packages/web/src/state/use-completion-notifications.ts

@@ -0,0 +1,68 @@
+/**
+ * Desktop task-completion notifications, renderer-side only (standard Web Notification
+ * API — no preload, no private IPC, per design § "桌面端原型 · 进程模型").
+ *
+ * Watches the tracked Session list for active→idle transitions (lib/completion-notify)
+ * and, when the window is hidden or unfocused, shows a system notification with the
+ * Session's title; clicking focuses the window and opens that Session. Gated to
+ * sessionVia === "desktop": only the desktop shell's own window qualifies — there the
+ * Notification permission is granted by default, so plain browsers (which would face a
+ * permission prompt) are never touched.
+ */
+import { useEffect, useRef } from "react";
+import { useNavigate } from "react-router";
+import { S } from "../lib/strings";
+import { createCompletionTracker } from "../lib/completion-notify";
+import { useAuth } from "./auth";
+import { useProject } from "./project";
+import { useSessions } from "./sessions";
+
+export function useCompletionNotifications(): void {
+  const { sessionVia } = useAuth();
+  const { sessions } = useSessions();
+  const { setCurrentAgentId } = useProject();
+  const navigate = useNavigate();
+
+  const trackerRef = useRef(createCompletionTracker());
+  // Click handlers fire long after the effect ran: read the latest helpers via refs.
+  const navigateRef = useRef(navigate);
+  navigateRef.current = navigate;
+  const setCurrentAgentIdRef = useRef(setCurrentAgentId);
+  setCurrentAgentIdRef.current = setCurrentAgentId;
+
+  const enabled = sessionVia === "desktop";
+  useEffect(() => {
+    if (!enabled) return;
+    // The tracker must see every snapshot (also while focused): completions the user
+    // watched happen are consumed silently instead of surfacing on a later blur.
+    const completed = trackerRef.current.observe(
+      sessions.map((s) => ({ sessionId: s.sessionId, status: s.status })),
+    );
+    if (completed.length === 0) return;
+    if (!document.hidden && document.hasFocus()) return;
+    if (typeof Notification === "undefined" || Notification.permission !== "granted") return;
+    for (const sessionId of completed) {
+      const session = sessions.find((s) => s.sessionId === sessionId);
+      const title = session?.title ?? S.chat.defaultSessionTitle;
+      const agentId = session?.agentId ?? null;
+      try {
+        const notification = new Notification(S.notify.taskCompleteTitle, {
+          body: S.notify.taskCompleteBody(title),
+          // One notification per Session: a newer completion replaces the stale one.
+          tag: `penguin-task-${sessionId}`,
+          icon: "/penguin-logo.svg",
+        });
+        notification.onclick = () => {
+          notification.close();
+          window.focus();
+          // Mirrors the sidebar's openSession: the current agent follows the Session.
+          if (agentId !== null) setCurrentAgentIdRef.current(agentId);
+          navigateRef.current(`/chat/${sessionId}`);
+        };
+      } catch {
+        // Notification construction is best-effort; a platform refusing it must not
+        // break the app.
+      }
+    }
+  }, [enabled, sessions]);
+}

packages/web/test/completion-notify.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { createCompletionTracker } from "../src/lib/completion-notify";
+import type { ObservedSession } from "../src/lib/completion-notify";
+import type { SessionStatus } from "@prismshadow/penguin-server/api";
+
+const row = (sessionId: string, status: SessionStatus): ObservedSession => ({
+  sessionId,
+  status,
+});
+
+describe("createCompletionTracker", () => {
+  it("fires when a known running session goes idle", () => {
+    const t = createCompletionTracker();
+    expect(t.observe([row("a", "running")], 0)).toEqual([]);
+    expect(t.observe([row("a", "idle")], 1000)).toEqual(["a"]);
+  });
+
+  it("treats compacting as still active and fires only on the flip to idle", () => {
+    const t = createCompletionTracker();
+    t.observe([row("a", "running")], 0);
+    expect(t.observe([row("a", "compacting")], 100)).toEqual([]);
+    expect(t.observe([row("a", "idle")], 200)).toEqual(["a"]);
+  });
+
+  it("never fires on first observation, even an idle one after a running list load", () => {
+    const t = createCompletionTracker();
+    // A list that loads with idle sessions has witnessed nothing.
+    expect(t.observe([row("a", "idle"), row("b", "idle")], 0)).toEqual([]);
+    expect(t.observe([row("a", "idle"), row("b", "idle")], 100)).toEqual([]);
+  });
+
+  it("dedupes per run: repeated idle observations fire once", () => {
+    const t = createCompletionTracker();
+    t.observe([row("a", "running")], 0);
+    expect(t.observe([row("a", "idle")], 1000)).toEqual(["a"]);
+    expect(t.observe([row("a", "idle")], 2000)).toEqual([]);
+    expect(t.observe([row("a", "idle")], 60_000)).toEqual([]);
+  });
+
+  it("fires again for a genuinely new run after the cooldown", () => {
+    const t = createCompletionTracker(10_000);
+    t.observe([row("a", "running")], 0);
+    expect(t.observe([row("a", "idle")], 1000)).toEqual(["a"]);
+    t.observe([row("a", "running")], 20_000);
+    expect(t.observe([row("a", "idle")], 30_000)).toEqual(["a"]);
+  });
+
+  it("suppresses a stale-snapshot flap within the cooldown window", () => {
+    const t = createCompletionTracker(10_000);
+    t.observe([row("a", "running")], 0);
+    expect(t.observe([row("a", "idle")], 1000)).toEqual(["a"]);
+    // A stale reload snapshot resurrects "running", then the fresh state lands again:
+    // the same finish must not notify twice.
+    t.observe([row("a", "running")], 1100);
+    expect(t.observe([row("a", "idle")], 1200)).toEqual([]);
+  });
+
+  it("tracks sessions independently and reports multiple completions", () => {
+    const t = createCompletionTracker();
+    t.observe([row("a", "running"), row("b", "running"), row("c", "idle")], 0);
+    expect(t.observe([row("a", "idle"), row("b", "idle"), row("c", "idle")], 1000)).toEqual([
+      "a",
+      "b",
+    ]);
+  });
+
+  it("prunes sessions that leave the list: reappearing is a fresh first observation", () => {
+    const t = createCompletionTracker();
+    t.observe([row("a", "running")], 0);
+    // Project switch empties the list; the session's state is dropped.
+    t.observe([], 100);
+    expect(t.observe([row("a", "idle")], 200)).toEqual([]);
+  });
+
+  it("ignores duplicate ids within one observation (first occurrence wins)", () => {
+    const t = createCompletionTracker();
+    t.observe([row("a", "running")], 0);
+    expect(t.observe([row("a", "idle"), row("a", "running")], 1000)).toEqual(["a"]);
+    // The duplicate "running" row did not restart the run.
+    expect(t.observe([row("a", "idle")], 60_000)).toEqual([]);
+  });
+});

pnpm-lock.yaml

@@ -114,6 +114,9 @@ importers:
 
   packages/desktop:
     dependencies:
+      '@prismshadow/penguin-cli':
+        specifier: workspace:*
+        version: file:packages/cli(supports-color@10.2.2)
       '@prismshadow/penguin-core':
         specifier: workspace:*
         version: file:packages/core(supports-color@10.2.2)(ws@8.21.0)