synabun 2.0.10 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,89 @@
+# SynaBun v.2.1.0
+
+SynaBun 2.1.0 adds downloadable release verification reports, improves automated package publishing, and changes Windows clipboard images to explicit paste.
+
+## ✨ New
+
+- **Release verification reports** — Desktop downloads and the npm package are checked with VirusTotal before publication. Release notes include analysis dates, engine results, file hashes and links to the reports. These results describe the scans and do not guarantee that a download is safe.
+
+## 🛠 Fixed
+
+- **Automated npm publishing** — The npm package is published from the prepared release and verified against the scanned package before desktop downloads become available. This helps keep package installation and desktop updates on the same release.
+
+## ⚙️ Changed
+
+- **Explicit clipboard image paste on Windows** — Focus the whiteboard and press Ctrl+V to add a clipboard image. Background clipboard monitoring has been removed; screenshot files in the watched folder still appear automatically. This change addresses a suspected source of antivirus alerts, but resolution of the reported Kaspersky detection has not been confirmed.
+
+---
+
+# SynaBun v.2.0.121
+
+2.0.121 fixes repeated Codex MCP tool approval prompts and keeps automatic approvals aligned with the current session policy.
+
+## 🛠 Fixed
+
+- **Codex MCP approvals** — Auto-accept handles tool approvals even when Codex omits the tool name, avoiding repeated permission cards. Plan mode and remote read-only sessions continue to apply their restrictions, while questions and authorization prompts still wait for your response.
+- **Assistant routing** — Routing requests no longer need an extra tool permission card when approvals are set to Ask.
+
+---
+
+# SynaBun v.2.0.12
+
+2.0.12 makes Skills Studio easier to install from, test and maintain, keeps dispatched workers running through a server restart, and adds a guided tour of the workspace. It also moves OpenCode support to OpenCode 2 and makes the 3D memory map the default for everyone.
+
+## ✨ New
+
+- **Skill health and local usage** — Skills Studio shows local evidence of skill use in Claude Code, Codex and OpenCode runs, with native invocations distinguished from inferred reads. Optional periodic checks report integrity and eligibility changes to the Assistant.
+- **A guided workspace tour** — The help button opens a tour on SynaBun's own whiteboard, with pointing arms, handwritten labels and steps that follow the workspace. It supports narrow windows, English and Portuguese, and reduced motion. The handwriting font ships with the app.
+- **Tool lists** — Choose the SynaBun tools and external MCP servers available to a session, worker or automation from reusable tool lists. External server choices report why a requested server cannot be used, with provider context to help recover.
+
+## 🛠 Fixed
+
+- **Workers resume after a restart** — Dispatched Claude Code, Codex and OpenCode workers can pause during a SynaBun server restart and resume the same run and provider conversation in the same sidepanel tab.
+- **Server crash recovery** — SynaBun restarts a server that crashes and reports the reason. Desktop recovery shows the failure and recovery state, and a stalled Codex title request no longer holds the server open indefinitely.
+- **MoreLogin attachment and cleanup** — Connecting to a MoreLogin profile preserves its native HTTP cache and WebSocket APIs while keeping SynaBun's network guards. Closing a connected browser session also closes the automation tabs SynaBun opened for it, so they do not return on the profile's next start.
+- **Worker startup and permissions** — Codex workers start correctly when external MCP servers are disabled. Protected OpenCode workers receive MCP tools directly with Code Mode disabled, and Codex Plan mode with automatic approvals no longer repeats permission requests in the Assistant.
+- **Claude Code hooks from the desktop** — Hooks work when SynaBun starts from the macOS Dock. Settings shows their actual state and lets you switch them on or off.
+- **Stopping the intended worker** — A request naming one run stops that run. The Assistant's Stop all control requires a second press before it stops every running worker.
+- **Compact activity and app layout** — Activity bubbles use one busy indicator and at most one ellipsis, with long paths and URLs wrapping at separators. Browser tabs and Safari web apps have consistent spacing between the navigation bar and the app frame, and Codex output and tab layout handle narrow panels more reliably.
+
+## ⚙️ Changed
+
+- **Installing approved skills** — Review approval and installation have clearer, separate states. Publishing an approved skill presents one install decision with readable runtime targets, and Claude Code, Codex and OpenCode share the drafting, evaluation and installation workflow. Skill checks cover more shell wrappers, asset references and command forms while keeping passive references distinct from executable instructions.
+- **OpenCode 2 required** — OpenCode 1 support is removed. Every launch path checks the installed version before starting and explains how to install OpenCode 2 when needed.
+- **One memory map** — The memory map uses 3D. Saved 2D preferences and old links open in 3D, and the 2D switch and shortcut have been removed from the interface.
+- **Project test commands** — Browser policy permits test runners inside registered code projects and accepts syntax-only Node checks. Commands that execute preloaded code still receive the normal policy checks.
+
+---
+
+# SynaBun v.2.0.11
+
+2.0.11 rebuilds Skills Studio around a skill library: every skill in one list, a workspace to edit, test, version and publish it, native skill folders for Claude Code, Codex and OpenCode, a Review queue, and skills drafted by AI from your own sources. SynaBun's memory is also one command away for any MCP client (`npx -y synabun mcp`), the whole app has a right-click menu, desktop updates show a splash and restart in seconds, and the Schedules window speaks your language.
+
+## ✨ New
+
+- **Skills Studio 2.0** — Skills Studio is now a window with three places: Library, Review and Create. The Library lists every skill once, whichever tool or account reads it, with where it comes from, what Claude Code, Codex and OpenCode each have of it, and a health badge for what needs a look (problems, an update available, a skill defined twice, an old-style install); filters, saved views, search and bulk actions keep it in order. A skill opens in a workspace with Edit, Test, Versions and Publish: the app's code editor, a form and the YAML kept as one document, the problems each runtime would report, a description helper, the skill's files, a Markdown preview with diagrams, versions with diffs and restore, and an install of exactly the plan you see. The window is not modal, docks beside the side panels, fits narrow widths and works fully from the keyboard, in English and Portuguese.
+- **Native skill folders for Claude Code, Codex and OpenCode** — Installing a skill now puts it in each runtime's own skill folder, with a backup, a check after the install and a way back. Skills installed the old way, as Codex prompts or OpenCode commands, can be moved to the native folders from Settings › Skills › Skill folders: you see the plan first, nothing moves until you press Move, and Undo puts every one back. Nothing is moved at start, during an update or by an agent. The Codex panel runs a skill you pick as a Codex skill, and a skill's arguments are filled in the way Claude Code fills them.
+- **Skills drafted by AI, and a Review queue** — Create's AI box drafts a whole skill from your description and up to five sources: a Claude Code, Codex or OpenCode session, a web page, a registered project, memories, a library skill or an imported bundle. One worker writes it in a folder of its own and can only read and write there; the result is checked, comes with test prompts and lands in Review. While it runs you see its steps, the files written so far, the time and the cost, and you can cancel. The SynaBun Assistant creates and improves skills the same way, with its bundled skill-forge workflow. Whatever an AI makes waits in Review and is installed only after you approve it.
+- **`synabun mcp`** — The npm command now starts SynaBun's MCP server on stdio, for Cursor, Windsurf, Claude Code, Codex or any other MCP client: `"command": "npx", "args": ["-y", "synabun", "mcp"]`, or `"command": "synabun", "args": ["mcp"]` after `npm install -g synabun`. It is the same server, with the same memories and data folder, as the one SynaBun registers for your tools. Only the protocol goes to its output, and it stops when the client that started it stops it.
+- **The official MCP Registry** — The npm package now names SynaBun's entry in the official MCP Registry, `io.github.danilokhury/synabun`, which MCP clients and directories read to find a server and how to start it.
+- **Clickable follow-ups in the Assistant** — When the Assistant ends a turn with options or a question for you, they appear as buttons under its message: one click sends the answer, a set of choices becomes checkboxes with one Send, and Something else… takes you to the composer.
+- **A countdown to a usage-limit reset** — When a provider's usage limit stops the Assistant or one of its workers, a card shows a live countdown to the reset and the local reset time, then Retry now. A worker is retried on the same model.
+- **A right-click menu for the whole app** — A right-click anywhere that has no menu of its own now opens SynaBun's: page actions (Back, Forward, Reload, Copy, Full screen), then what fits what you clicked (selected text, a link, an image, a memory on the map, in the Memory Explorer or on a card, the empty space of the 3D or 2D map, the Focus mode board and its tools), then every panel and tool with its keyboard shortcut. Fields and Shift + right-click keep the browser's menu, and the terminal, the File Explorer's tree, editor tabs and graph cards keep their own. The Menu key and Shift + F10 open it from the keyboard.
+
+## 🛠 Fixed
+
+- **Skills Studio keeps your work** — The Studio could erase frontmatter it did not show, mark text typed during a save as saved, save one skill's file under another's name, lose unsaved work on Escape or close, rewrite every line ending of a Windows-style file, write into SynaBun's bundled skill, replace or delete a same-named skill SynaBun never installed, and install an imported bundle unseen. Now an edit changes only the field you touched, a save that would overwrite a change made elsewhere asks first, bundled skills are read-only with Customize a copy, a skill SynaBun did not install is backed up and changed only after you confirm, and an import is checked, scanned and shown to you before anything is written.
+- **A complete MCP server build** — SynaBun now checks that its MCP server is built completely, every module it loads and not only its entry file, and builds it again at install or start when something is missing.
+
+## ⚙️ Changed
+
+- **Desktop updates** — Updating the desktop app no longer leaves you without a window: a small splash with the mascot shows at every start and through every step of an update, with a progress bar and Details. Once an update is downloaded, the update button becomes Restart to update (also in the app menu, the File menu and the tray), which installs at once when SynaBun is idle, or when the running work ends. The safety snapshot of your data is prepared ahead in the background and compared with your data at the restart, so the new version opens in seconds instead of minutes on a large memory store, and every database copy in it passes an integrity check. On a Mac the app is without a window for about a second, and dark pages on some Macs no longer show a lighter band across the middle.
+- **`synabun help`** — `synabun help`, `synabun --help` and `synabun -h` list every command and the data folder in use. Before, they started SynaBun.
+- **Schedules in your language** — The whole Schedules window now follows the app's language: every view, row, editor, dialog and message, schedules described in plain words, and dates and times in your locale. Changing the language with the window open brings you back to the same view.
+
+---
+
 # SynaBun v.2.0.10
 
 2.0.10 works with OpenCode 2, adds a Settings › App page for updates and start at login, and opens menus, model lists and Settings at once instead of waiting on the network, most noticeably in the Windows desktop app. It also redesigns the Schedules window, shows every worker the Assistant dispatches at work, and closes a security hole in the Codex panel.

package/README.md

@@ -23,7 +23,26 @@
 
 ---
 
-SynaBun gives your AI coding tools a memory that lasts. What you decided, fixed and explained in one session is there in the next one, in every project and every tool you connect, so you stop repeating yourself. It all lives in one file on your computer: no account, no cloud service, no API key.
+**SynaBun is an open-source, self-hosted AI workspace and persistent memory MCP server: SynaBun Assistant coordinates Claude Code, Codex and OpenCode agents.** What you decided, fixed and explained in one session is there in the next one, in every project and every tool you connect, so you stop repeating yourself. It all lives in one SQLite file on your computer: no account, no cloud service, no API key.
+
+```bash
+npm install -g synabun
+```
+
+`synabun` starts the app. `synabun mcp` is the MCP server on stdio, for any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "SynaBun": {
+      "command": "npx",
+      "args": ["-y", "synabun", "mcp"]
+    }
+  }
+}
+```
+
+After the global install, `"command": "synabun", "args": ["mcp"]` runs the same server. Read the [docs](https://synabun.ai/docs), or see how SynaBun [compares](https://synabun.ai/compare) with other memory tools.
 
 It connects to Claude Code, Codex CLI, Gemini CLI and OpenCode with one switch each, and to Cursor, Windsurf or any other tool that supports MCP (the Model Context Protocol) with a config snippet you copy. It comes with the Neural Interface, a local web app where you see what your tools remember and run your coding agents.
 
@@ -159,7 +178,7 @@ Everything SynaBun stores is in one folder outside the app: `~/.synabun` on macO
 
 ## Links
 
-- [Changelog](./CHANGELOG.md): what is new in 2.0.10 and before
+- [Changelog](./CHANGELOG.md): what is new in 2.1.0 and before
 - [Security](./SECURITY.md): security model and how to report a vulnerability
 - [Contributing](./CONTRIBUTING.md): bug reports and feature requests are welcome as [issues](https://github.com/danilokhury/Synabun/issues); pull requests are not accepted
 - [Website](https://synabun.ai), [docs](https://synabun.ai/docs) and [blog](https://synabun.ai/blog)
@@ -174,3 +193,7 @@ You are free to use, modify, and distribute SynaBun under Apache 2.0. Premium fe
 ## Trademark Notice
 
 "SynaBun" is a trademark of its authors. The license does not grant permission to use the SynaBun name, trademarks, service marks, or branding. If you fork this project, you must use a different name for your derivative work.
+
+<!-- synabun:verification:start -->
+Package verification: [downloadable VirusTotal reports and SHA-256 hashes](https://github.com/danilokhury/Synabun/releases/latest). Match the report to your exact version and file hash. Reports record engine coverage and analysis dates; they are not a guarantee of safety. Website results describe URL reputation, not a vulnerability audit.
+<!-- synabun:verification:end -->

package/THIRD-PARTY-LICENSES.md

@@ -59,6 +59,7 @@ runtime dependencies in the published package.
 | `playwright` | `^1.59.1` | 1.59.1 | Apache-2.0 | [npm](https://www.npmjs.com/package/playwright) |
 | `undici` | `^8.5.0` | 8.8.0 | MIT | [npm](https://www.npmjs.com/package/undici) |
 | `ws` | `^8.21.0` | 8.21.1 | MIT | [npm](https://www.npmjs.com/package/ws) |
+| `yaml` | `2.9.1` | 2.9.1 | ISC | [npm](https://www.npmjs.com/package/yaml) |
 | `zod` | `^4.4.3` | 4.4.3 | MIT | [npm](https://www.npmjs.com/package/zod) |
 
 ## Neural Interface Development Dependencies
@@ -94,6 +95,8 @@ runtime dependencies in the published package.
 | highlight.js | 11.12.0 | Bundled browser asset (`neural-interface/public/vendor/highlight/`) copied from the npm development dependency `@highlightjs/cdn-assets` | BSD-3-Clause | [GitHub](https://github.com/highlightjs/highlight.js) |
 | Mermaid | 11.17.2 | Bundled browser asset (`neural-interface/public/vendor/mermaid/`) copied from the npm development dependency | MIT | [GitHub](https://github.com/mermaid-js/mermaid) |
 | html2canvas | 1.4.1 | Bundled browser asset (`neural-interface/public/vendor/html2canvas/`) copied from the npm development dependency | MIT | [GitHub](https://github.com/niklasvh/html2canvas) |
+| yaml | 2.9.1 | Bundled browser asset (`neural-interface/public/vendor/yaml/`) built from the npm dependency | ISC | [GitHub](https://github.com/eemeli/yaml) |
+| Caveat (font) | 5.3.0 (`@fontsource/caveat`) | Bundled browser asset (`neural-interface/public/vendor/caveat/`): the Latin 400 and 700 WOFF2 files, copied unmodified with the package's license | OFL-1.1 | [GitHub](https://github.com/googlefonts/caveat) |
 
 ### CodeMirror 6
 
@@ -156,6 +159,24 @@ The card screenshot tool of the 3D map (`index.html`). Its own browser build (`d
 - **Copyright:** Copyright (c) 2012 Niklas von Hertzen
 - **URL:** https://github.com/niklasvh/html2canvas
 
+### yaml
+
+The YAML parser behind the Skills Studio: it reads the frontmatter of skills, commands and agents, and changes it one key at a time without touching the rest (`neural-interface/lib/skills/`, `neural-interface/public/shared/skills/ss-frontmatter.js`). No dependencies of its own. The Studio's metadata form uses the same package in the browser: its browser build (`browser/dist/index.js`), bundled by `neural-interface/scripts/build-vendor.mjs` into one file in `neural-interface/public/vendor/yaml/` with the package's `LICENSE` and a `manifest.json`, loaded only when the editor opens.
+
+- **Version:** 2.9.1
+- **License:** ISC
+- **Copyright:** Copyright Eemeli Aro
+- **URL:** https://github.com/eemeli/yaml
+
+### Caveat
+
+The handwriting of the whiteboard and of the Workspace tour, served by SynaBun itself instead of a font CDN. The Latin subset of weights 400 and 700 (`caveat-latin-400-normal.woff2`, `caveat-latin-700-normal.woff2`) from the npm package `@fontsource/caveat` 5.3.0, copied unmodified into `neural-interface/public/vendor/caveat/` with the package's `LICENSE` as `OFL.txt`, a `caveat.css` that declares the two faces and a `manifest.json` with the SHA-256 of each file. The font is not sold on its own and its name is not changed (OFL 1.1, conditions 1 and 3).
+
+- **Version:** 5.3.0 (`@fontsource/caveat`)
+- **License:** SIL Open Font License 1.1
+- **Copyright:** Copyright 2014 The Caveat Project Authors
+- **URL:** https://github.com/googlefonts/caveat
+
 ## Vendored Code
 
 | Component | Location | License | Project |
@@ -224,6 +245,7 @@ The model is distributed under Apache-2.0. See its
 - [BSD 2-Clause License](https://opensource.org/license/bsd-2-clause)
 - [BSD 3-Clause License](https://opensource.org/license/bsd-3-clause)
 - [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html)
+- [ISC License](https://opensource.org/license/isc-license-txt)
 
 SynaBun's own Apache-2.0 terms are in [LICENSE](./LICENSE), and attribution
 information is in [NOTICE](./NOTICE). The

package/bin/synabun.js

@@ -1,30 +1,77 @@
 #!/usr/bin/env node
 
+/**
+ * `synabun`, the command an npm install puts on the PATH.
+ *
+ *   synabun mcp [...]   the MCP server on stdio, for an AI tool's MCP config. It
+ *                       starts mcp-server/run.mjs straight from here, as
+ *                       `node <package>/mcp-server/run.mjs` and a packaged build's
+ *                       `<entry> mcp` do (packaging/launcher/launcher.c): same
+ *                       environment, same working folder, same arguments after
+ *                       `mcp`. setup.js is never loaded, so nothing reaches stdout,
+ *                       the protocol channel, before the server does; the server
+ *                       logs to stderr.
+ *   synabun [...]       everything else: setup.js with the same arguments.
+ */
+
 import { spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const setupPath = resolve(packageRoot, 'setup.js');
-const child = spawn(process.execPath, [
-  '--disable-warning=ExperimentalWarning',
-  setupPath,
-  ...process.argv.slice(2),
-], {
-  cwd: process.cwd(),
-  env: process.env,
-  stdio: 'inherit',
-});
-
-child.on('error', error => {
-  console.error(`Could not start SynaBun: ${error.message}`);
-  process.exitCode = 1;
-});
-
-child.on('exit', (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exitCode = code ?? 1;
-});
+export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const MCP_COMMAND = 'mcp';
+// node:sqlite's warning: every SynaBun process starts with it off (setup.js, the packaged launcher).
+const NODE_FLAG = '--disable-warning=ExperimentalWarning';
+
+/** Node's arguments for `synabun <args>`. */
+export function nodeArgs(args, { packageRoot = PACKAGE_ROOT } = {}) {
+  if (args[0] === MCP_COMMAND) return [NODE_FLAG, resolve(packageRoot, 'mcp-server', 'run.mjs'), ...args.slice(1)];
+  return [NODE_FLAG, resolve(packageRoot, 'setup.js'), ...args];
+}
+
+/** The signals an MCP client (or a terminal) stops the server with. */
+export function forwardedSignals(platform = process.platform) {
+  return platform === 'win32' ? ['SIGINT', 'SIGTERM'] : ['SIGINT', 'SIGTERM', 'SIGHUP'];
+}
+
+/**
+ * Node on `args`, with this process's stdio, environment and working folder.
+ * This process then ends the way the child ended: its exit code, or the same
+ * signal. With `forwardSignals`, a SIGINT, SIGTERM or SIGHUP sent to this
+ * process goes to the child while it runs: an MCP client stops the server it
+ * started by signalling the process it started, which is this one.
+ */
+export function runNode(args, { execPath = process.execPath, env = process.env, cwd = process.cwd(), forwardSignals = false } = {}) {
+  const child = spawn(execPath, args, { cwd, env, stdio: 'inherit' });
+  const handlers = forwardSignals
+    ? forwardedSignals().map((signal) => [signal, () => { try { child.kill(signal); } catch {} }])
+    : [];
+  for (const [signal, handler] of handlers) process.on(signal, handler);
+  const release = () => { for (const [signal, handler] of handlers) process.removeListener(signal, handler); };
+
+  child.on('error', (error) => {
+    release();
+    console.error(`Could not start SynaBun: ${error.message}`);
+    process.exitCode = 1;
+  });
+
+  child.on('exit', (code, signal) => {
+    release();
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+  return child;
+}
+
+const invokedDirectly = (() => {
+  try { return !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+})();
+
+if (invokedDirectly) {
+  const args = process.argv.slice(2);
+  runNode(nodeArgs(args), { forwardSignals: args[0] === MCP_COMMAND });
+}

package/docs/whatsapp.md

@@ -299,7 +299,7 @@ Ask for a file and the Assistant sends it to this chat as a real WhatsApp attach
 - password managers (1Password, Bitwarden, KeePass `*.kdbx`), `~/Library/Keychains`, GNOME Keyring and KWallet, Windows Credential Manager (with its DPAPI keys and the Vault), the Mail and Messages stores and Thunderbird;
 - shell histories (`.zsh_history`, `.bash_history`, fish's history, PowerShell's), `.netrc`, `.npmrc`, `.pypirc`, `.pgpass`, `.git-credentials` and git's `~/.config/git/credentials`, `.vault-token`, the `.docker`, `.kube`, `.aws`, `.azure`, gcloud, `gh`, `.gnupg` and `.ssh` folders, and CLI token stores (cargo, gem, Pulumi, Hugging Face, Kaggle, rclone, hub, glab, doctl, Stripe, Fly, cloudflared, OCI, Databricks);
 - key and certificate files anywhere (`*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.jks`, `*.keystore`, `*.ppk`, `*.p8`, SSH `id_*` keys), `.env` files and their variants, terraform state;
-- AI tool configuration and credentials: `~/.claude.json`, `~/.claude*`, `~/.codex*`, OpenCode's configuration and `auth.json`, GitHub Copilot's tokens, `.cursor/mcp.json`, `claude_desktop_config.json`, `mcp-api-key` and `.synabun-api-key` files;
+- AI tool configuration and credentials: `~/.claude.json`, `~/.claude*`, `~/.codex*`, OpenCode's configuration, its database (`opencode.db`, where OpenCode 2 keeps credentials) and the `auth.json` OpenCode 1 kept, GitHub Copilot's tokens, `.cursor/mcp.json`, `claude_desktop_config.json`, `mcp-api-key` and `.synabun-api-key` files;
 - copies of those places' secret parts wherever they are (a backup disk, Time Machine): `.synabun/whatsapp`, `mcp-data`, `runtime` and `backups`, `sidepanel-configs`, `.claude/settings*.json` and `.claude/projects`, `.codex*/config.toml`, `sessions` and `history.jsonl`; and SynaBun's own backup archives (`synabun-<kind>-<timestamp>.zip`, `synabun-auto-backup.zip`) by their name, in whatever folder the backups go to.
 
 The list is explicit (`neural-interface/lib/whatsapp/local-file.js`, `DENYLIST`) and matched without regard to letter case. The protected folders (the session, the data home, `~/.claude*`, `~/.codex*`) are also recognized by what they are on disk, their device and inode, so another spelling of the same folder is refused like the usual one: macOS reaches every folder of the data volume under `/System/Volumes/Data/…` too, which `realpath` keeps. On Windows a name is also checked as Windows opens it, without trailing dots and spaces (`.ssh.\id_rsa` is `.ssh\id_rsa`). **The content of a file is never inspected**: a secret inside an ordinary file with an ordinary name is sent like any other file, so ask only for what you mean to receive. Keynote presentations share the `.key` extension with private keys and are refused too: export them to PDF first.
@@ -390,7 +390,7 @@ App-wide, every WebSocket upgrade (`/ws/*`) must carry no `Origin` or this serve
 | "SynaBun is not reachable: nothing was sent" (`UNREACHABLE`) | The brain's MCP server could not reach SynaBun at all, so the file was not sent. Check that SynaBun is running, then ask again. |
 | Transcripts get words wrong | Set `transcriptionLanguage` to the language you speak (`auto` guesses per note), or point `transcriptionModelPath` at a larger ggml model. |
 
-**Not the same as the WhatsApp browser tools.** The `whatsapp` MCP profile (`browser_extract_wa_chats`, `browser_extract_wa_messages`) lets agents read WhatsApp Web in SynaBun's browser. The WhatsApp Link is you chatting with SynaBun from your phone. They share nothing.
+**Not the same as the WhatsApp browser tools.** The `browser_whatsapp` tool group (`browser_extract_wa_chats`, `browser_extract_wa_messages`) lets agents read WhatsApp Web in SynaBun's browser. The WhatsApp Link is you chatting with SynaBun from your phone. They share nothing.
 
 ## Environment
 

package/hooks/claude-code/pre-websearch.mjs

@@ -29,7 +29,11 @@ import { getDataHome } from '../../lib/paths.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DATA_HOME = getDataHome();
 const LOOP_DIR = join(DATA_HOME, 'data', 'loop');
-const NI_BASE = process.env.SYNABUN_NI_URL || 'http://localhost:3344';
+// A guarded worker's sandbox blocks :3344, so SynaBun gives it the worker-only channel (its browser proxy forwards
+// /api/browser/*). Inside such a worker the browser-only policy must NOT fail open: if SynaBun cannot be reached
+// even over the channel, apply the worker default and deny WebSearch/WebFetch.
+const WORKER_CHANNEL = process.env.SYNABUN_WORKER_CHANNEL || null;
+const NI_BASE = WORKER_CHANNEL || process.env.SYNABUN_NI_URL || 'http://localhost:3344';
 
 const BLOCK_REASON = (toolName) =>
   `BLOCKED: ${toolName} is not allowed while a SynaBun browser session is open. Use the SynaBun browser tools (browser_navigate, browser_click, browser_content, etc.) instead. If the page requires login or CAPTCHA, STOP and tell the user what they need to do in the browser panel. Do NOT fall back to web search.`;
@@ -69,6 +73,13 @@ async function handleInput() {
     }
 
     if (!niReachable) {
+      // A guarded worker that cannot reach SynaBun even over its channel: apply the worker default (deny), so the
+      // sandbox's inability to reach :3344 never becomes a way to bypass the browser-only policy. Outside a guarded
+      // worker (no channel var) this stays fail-open and quiet — a stale loop file must not block the owner.
+      if (WORKER_CHANNEL) {
+        process.stdout.write(JSON.stringify({ decision: 'block', reason: BLOCK_REASON(tool_name) }));
+        return;
+      }
       process.stdout.write(JSON.stringify({}));
       return;
     }

package/hooks/claude-code/shared.mjs

@@ -864,8 +864,13 @@ export async function judgeText(kind, text, { project, timeoutMs = 1500, extra =
 /**
  * Fire-and-forget POST that may wait at most `waitMs` for the answer and never
  * keeps the process alive past that. Resolves true only on a 2xx.
+ * SYNABUN_HOOK_NOTICE_WAIT_MS replaces `waitMs` for the hook tests only
+ * (tests/helpers/hook-harness.mjs): on a machine running the whole suite the
+ * notice missed its 200 ms. Nothing SynaBun starts sets it.
  */
 export async function postNotice(path, body, waitMs = 200) {
+  const testWait = Number(process.env.SYNABUN_HOOK_NOTICE_WAIT_MS);
+  if (Number.isFinite(testWait) && testWait > 0) waitMs = testWait;
   let timer;
   try {
     const request = fetch(`${niUrl()}${path}`, {

package/hooks/claude-code/stop.mjs

@@ -916,7 +916,7 @@ function handleStop({ sessionId, lastMessage, cwd, transcriptPath, judged = {},
     }
 
     // CHECK 2.5: User learning (bundled with task or standalone)
-    // Skipped when waiting for user action (interactive flows like Leonardo questionnaires).
+    // Skipped when waiting for user action (interactive questionnaire flows).
     // Limited to 1 retry to minimize chat noise.
     // Never inside the Assistant's brain (SYNABUN_ASSISTANT_SESSION): SynaBun's harness learns
     // about the user there, and prompt-submit.mjs never arms this in it.

package/lib/claude-hooks.js

@@ -1,6 +1,8 @@
-import { resolve } from 'node:path';
+import { accessSync, constants, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { isAbsolute, join, resolve, sep } from 'node:path';
 import { PACKAGE_ROOT } from './paths.js';
-import { durableEntry, packagedRuntime } from './packaged-runtime.js';
+import { durableEntry, isReadOnlyVolumePath, isTransientPath, packagedRuntime } from './packaged-runtime.js';
 
 // Handler identity must be byte-for-byte identical across settings scopes.
 // Claude Code deduplicates matching settings handlers before executing them.
@@ -27,10 +29,10 @@ export function hookDefinitionsForEvent(event) {
   return HOOK_SCRIPTS.filter(def => events.includes(def.event));
 }
 
-// No shell-specific environment expansion, install paths, or downloads. Walk
-// up from the project/cwd for checkout-only installs, then use the installed
-// root. Single quotes inside JS work inside the command's double quotes on
-// both cmd.exe and POSIX shells. Keep this versioned literal stable.
+// No install paths or downloads. Walk up from the project/cwd for checkout-only
+// installs, then use the installed root. Single quotes inside JS work inside
+// the command's double quotes on both cmd.exe and POSIX shells. Keep this
+// versioned literal stable.
 const BOOTSTRAP = "const f=require('node:fs'),p=require('node:path'),u=require('node:url'),s=process.argv[1];let r;const ok=d=>{try{return JSON.parse(f.readFileSync(p.join(d,'package.json'),'utf8')).name==='synabun'&&f.existsSync(p.join(d,'hooks','claude-code',s))}catch{return false}};for(let d=p.resolve(process.env.CLAUDE_PROJECT_DIR||process.cwd());;d=p.dirname(d)){if(ok(d)){r=d;break}if(d===p.dirname(d))break}if(!r&&process.env.SYNABUN_HOOK_ROOT&&ok(process.env.SYNABUN_HOOK_ROOT))r=process.env.SYNABUN_HOOK_ROOT;if(!r)throw Error('SynaBun hook root unavailable; repair the hook installation');import(u.pathToFileURL(p.join(r,'hooks','claude-code',s)).href)";
 
 /**
@@ -49,23 +51,48 @@ function quoteHookEntry(entry) {
   return `"${entry.replace(/[\\"$`]/g, '\\$&')}"`;
 }
 
+// Windows: cmd.exe, PowerShell and Git Bash all run this, and a Windows program
+// gets the user's PATH from the registry whoever starts it.
 const nodeHookCommand = scriptName => `node -e "${BOOTSTRAP}" ${scriptName}`;
 
+/**
+ * Where a hook started without the login PATH looks for Node after `node` on
+ * PATH: the official installer's and Homebrew's folders and Volta's shim (the
+ * Node a terminal finds, as a rule), then SYNABUN_NODE. The same names on every
+ * machine.
+ */
+export const HOOK_NODE_FOLDERS = Object.freeze(['/usr/local/bin/node', '/opt/homebrew/bin/node', '$HOME/.volta/bin/node']);
+
+// macOS and Linux: Claude Code runs a settings hook with /bin/sh in its own
+// environment. Started from a terminal that has the login PATH; started from
+// the Dock, Finder, a desktop app or launchd it is /usr/bin:/bin:/usr/sbin:/sbin,
+// where `node` is not found and every hook exits 127. So: `node` on PATH, as a
+// terminal finds it, then the usual folders, then the Node the installer named
+// in the user's settings (SYNABUN_NODE: nvm and the like have no usual folder).
+// Nothing in it names this machine, so the tracked template and the projects'
+// settings carry it as they are.
+const POSIX_NODE_FINDER = `n=$(command -v node) || for n in ${HOOK_NODE_FOLDERS.map(p => (p.startsWith('$') ? `"${p}"` : p)).join(' ')} "$SYNABUN_NODE"; do [ -f "$n" ] && [ -x "$n" ] && break; n=node; done; `;
+const posixHookCommand = scriptName => `${POSIX_NODE_FINDER}exec "$n" -e "${BOOTSTRAP}" ${scriptName}`;
+
 // Whatever entry wrote it: an application that moved must still find, and
 // repair, its own handlers.
 const PACKAGED_HOOK_COMMAND = new RegExp(`^"(?:[^"\\\\]|\\\\.)+"\\s+${PACKAGED_HOOK_MODE}\\s+(\\S+)$`);
 
-export function hookCommandString(scriptName, _targetProjectPath, runtime = packagedRuntime()) {
+export function hookCommandString(scriptName, _targetProjectPath, runtime = packagedRuntime(), platform = process.platform) {
   if (!HOOK_SCRIPTS.some(h => h.script === scriptName)) throw new Error('Unknown SynaBun hook');
   const entry = durableEntry(runtime);
-  return entry ? `${quoteHookEntry(entry)} ${PACKAGED_HOOK_MODE} ${scriptName}` : nodeHookCommand(scriptName);
+  if (entry) return `${quoteHookEntry(entry)} ${PACKAGED_HOOK_MODE} ${scriptName}`;
+  return platform === 'win32' ? nodeHookCommand(scriptName) : posixHookCommand(scriptName);
 }
 
 export function isSynaBunHookCommand(command, scriptName) {
   if (typeof command !== 'string') return false;
-  // Both canonical forms, whichever kind of install is reading: moving between
-  // an npm install and the application must not leave two handlers behind.
-  if (command === nodeHookCommand(scriptName)) return true;
+  // Every canonical form, whichever kind of install and system is reading:
+  // moving between an npm install and the application, or a settings file
+  // shared between Windows and macOS, must not leave two handlers behind.
+  if (command === nodeHookCommand(scriptName) || command === posixHookCommand(scriptName)) return true;
+  // Any version of the POSIX finder in front of the same bootstrap.
+  if (command.startsWith('n=$(command -v node)') && command.endsWith(` -e "${BOOTSTRAP}" ${scriptName}`)) return true;
   const packaged = command.trim().match(PACKAGED_HOOK_COMMAND);
   if (packaged) return packaged[1] === scriptName;
   // Recognize only the old direct-node path forms, including cross-OS installs.
@@ -98,25 +125,47 @@ export function hookInstallPlan({ target, registered = false, hook } = {}, runti
   return target === 'project' && !registered && !hook ? 'register-only' : 'refuse';
 }
 
-export function ensureHookRoot(settings, targetProjectPath, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime()) {
+/**
+ * The Node a hook falls back to when Claude Code was started without the login
+ * PATH (SYNABUN_NODE): the one running SynaBun, which is known to run its hooks,
+ * when its path outlives this run. null on Windows (its programs get the user's
+ * PATH) and for a Node in a temporary place.
+ */
+export function hookNodePin({ execPath = process.execPath, platform = process.platform, env = process.env, writable } = {}) {
+  if (platform === 'win32' || typeof execPath !== 'string' || !isAbsolute(execPath)) return null;
+  if (isTransientPath(execPath, env) || isReadOnlyVolumePath(execPath, { platform, writable })) return null;
+  const temporary = [tmpdir(), '/tmp', '/private/tmp', '/private/var/folders', '/var/folders'];
+  if (temporary.some(dir => resolve(execPath).startsWith(`${resolve(dir)}${sep}`))) return null;
+  return execPath;
+}
+
+export function ensureHookRoot(settings, targetProjectPath, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime(), { node = hookNodePin() } = {}) {
   // A packaged application's command finds its own handlers, and its package
   // root can be a mount that ends with the run.
   if (runtime) return false;
   // The checked-in template must not acquire a machine-specific env path.
   if (targetProjectPath && resolve(targetProjectPath) === resolve(packageRoot)) return false;
-  if (settings.env?.SYNABUN_HOOK_ROOT === resolve(packageRoot)) return false;
-  settings.env = { ...settings.env, SYNABUN_HOOK_ROOT: resolve(packageRoot) };
-  return true;
+  let changed = false;
+  if (settings.env?.SYNABUN_HOOK_ROOT !== resolve(packageRoot)) {
+    settings.env = { ...settings.env, SYNABUN_HOOK_ROOT: resolve(packageRoot) };
+    changed = true;
+  }
+  // The user's own settings only (this machine's file): every session gets its env.
+  if (!targetProjectPath && node && settings.env?.SYNABUN_NODE !== node) {
+    settings.env = { ...settings.env, SYNABUN_NODE: node };
+    changed = true;
+  }
+  return changed;
 }
 
-export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime()) {
+export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime(), { platform = process.platform, node = hookNodePin({ platform }) } = {}) {
   if (!settings?.hooks || hookInstallBlocker(runtime)) return false;
   let changed = false;
   let ownsHooks = false;
   for (const def of HOOK_SCRIPTS) {
     const entries = settings.hooks[def.event];
     if (!Array.isArray(entries)) continue;
-    const command = hookCommandString(def.script, targetProjectPath, runtime);
+    const command = hookCommandString(def.script, targetProjectPath, runtime, platform);
     const matches = entries.flatMap(e => (e.hooks || []).filter(h => isSynaBunHookCommand(h.command, def.script)).map(h => ({ entry: e, hook: h })));
     if (!matches.length) continue;
     ownsHooks = true;
@@ -133,6 +182,111 @@ export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, pack
     settings.hooks[def.event] = [...rest, { matcher: def.matcher || '', hooks: [{ type: 'command', command, timeout: def.timeout }] }];
     changed = true;
   }
-  if (ownsHooks && ensureHookRoot(settings, targetProjectPath, packageRoot, runtime)) changed = true;
+  if (ownsHooks && ensureHookRoot(settings, targetProjectPath, packageRoot, runtime, { node })) changed = true;
   return changed;
 }
+
+// ── What is really installed (Settings → Automations → Claude Code hooks) ────
+
+/**
+ * What one settings file holds of SynaBun's handlers. `handlers`: one per
+ * HOOK_SCRIPTS entry, with `copies` (SynaBun handlers for that script in any
+ * form) and `current` (one of them is this machine's command, matcher and
+ * timeout); `events`: every handler of the event present; `installed` /
+ * `current` / `total` count handlers, `duplicates` the extra copies (each runs).
+ */
+export function hookInstallState(settings, { targetProjectPath, runtime = packagedRuntime(), platform = process.platform } = {}) {
+  const handlers = HOOK_SCRIPTS.map((def) => {
+    const entries = Array.isArray(settings?.hooks?.[def.event]) ? settings.hooks[def.event] : [];
+    const owned = entries.flatMap(entry => (Array.isArray(entry?.hooks) ? entry.hooks : [])
+      .filter(hook => isSynaBunHookCommand(hook?.command, def.script)).map(hook => ({ entry, hook })));
+    const command = hookCommandString(def.script, targetProjectPath, runtime, platform);
+    const current = owned.some(({ entry, hook }) => hook.command === command && (entry.matcher || '') === (def.matcher || '') && hook.timeout === def.timeout);
+    return { event: def.event, script: def.script, copies: owned.length, current };
+  });
+  const events = {};
+  for (const h of handlers) events[h.event] = (events[h.event] ?? true) && h.copies > 0;
+  return {
+    handlers,
+    events,
+    installed: handlers.filter(h => h.copies > 0).length,
+    current: handlers.filter(h => h.current).length,
+    duplicates: handlers.reduce((sum, h) => sum + Math.max(0, h.copies - 1), 0),
+    total: handlers.length,
+  };
+}
+
+/** The commands of SynaBun's handlers in a settings file, script by script (to compare two scopes). */
+export function hookCommandsOf(settings) {
+  const out = {};
+  for (const def of HOOK_SCRIPTS) {
+    const entries = Array.isArray(settings?.hooks?.[def.event]) ? settings.hooks[def.event] : [];
+    const commands = entries.flatMap(entry => (Array.isArray(entry?.hooks) ? entry.hooks : []))
+      .map(hook => hook?.command).filter(command => isSynaBunHookCommand(command, def.script));
+    out[`${def.event}:${def.script}`] = [...new Set(commands)].sort();
+  }
+  return out;
+}
+
+/**
+ * Whether a project's SynaBun handlers run once next to the user's: Claude Code
+ * runs one copy of identical handlers from both files, and both of different
+ * ones. 'same' (nothing of SynaBun's there, or the same commands), 'different'.
+ */
+export function projectHooksAgree(userSettings, projectSettings) {
+  const user = hookCommandsOf(userSettings);
+  const project = hookCommandsOf(projectSettings);
+  for (const [key, commands] of Object.entries(project)) {
+    if (!commands.length) continue;
+    const mine = user[key] || [];
+    if (!mine.length) continue; // only the project runs it: once
+    if (commands.some(command => !mine.includes(command))) return 'different';
+  }
+  return 'same';
+}
+
+/** Claude Code's own switches that stop SynaBun's handlers, in one settings file: the first that applies, or null. */
+export function hooksSwitchedOff(settings, { managed = false } = {}) {
+  if (!settings || typeof settings !== 'object') return null;
+  if (settings.disableAllHooks === true) return 'disableAllHooks';
+  // Only managed settings can keep user and project hooks from running.
+  if (managed && settings.allowManagedHooksOnly === true) return 'allowManagedHooksOnly';
+  return null;
+}
+
+/** Where Claude Code reads managed (organization) settings on this system. */
+export function managedClaudeSettingsPath(platform = process.platform) {
+  if (platform === 'darwin') return '/Library/Application Support/ClaudeCode/managed-settings.json';
+  if (platform === 'win32') return 'C:\\Program Files\\ClaudeCode\\managed-settings.json';
+  return '/etc/claude-code/managed-settings.json';
+}
+
+/** The PATH macOS gives a program it starts from the Dock, Finder or launchd. */
+export const LAUNCHD_PATH = Object.freeze(['/usr/bin', '/bin', '/usr/sbin', '/sbin']);
+
+function runnableFile(path) {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * The Node a SynaBun hook would run with in a Claude Code started without the
+ * login PATH (the Dock, Finder, a desktop app, launchd): what the POSIX command
+ * tries after PATH, in its order. { path, via: 'SYNABUN_NODE' | 'folder' } or
+ * null (such a session would fail every hook). Windows: not asked (null).
+ */
+export function hookNodeWithoutPath({ env = {}, home = homedir(), platform = process.platform, runnable = runnableFile } = {}) {
+  if (platform === 'win32') return null;
+  // `command -v node` on the PATH such a launch has (a Linux distribution's own Node).
+  for (const dir of LAUNCHD_PATH) if (runnable(`${dir}/node`)) return { path: `${dir}/node`, via: 'PATH' };
+  for (const folder of HOOK_NODE_FOLDERS) {
+    const path = folder.startsWith('$HOME/') ? join(home, folder.slice('$HOME/'.length)) : folder;
+    if (runnable(path)) return { path, via: 'folder' };
+  }
+  const pinned = typeof env.SYNABUN_NODE === 'string' ? env.SYNABUN_NODE : '';
+  if (pinned && runnable(pinned)) return { path: pinned, via: 'SYNABUN_NODE' };
+  return null;
+}