dsh-everything 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.4.0] - 2026-10-27
+
+### Added
+- **HTTP fast channel**: searches are now served by Everything's built-in
+  HTTP JSON server on `127.0.0.1` when it is available — no per-call
+  `es.exe` spawn, native UTF-8, and exact totals for free. The plugin
+  auto-enables the server itself (Everything ships it disabled AND
+  policy-locked: `allow_http_server=0` in the ini next to
+  `Everything.exe`; the GUI cannot unlock it) by patching both
+  `Everything.ini` files, binding loopback only, and restarting the GUI
+  once per session (`httpAutoEnable`, default on; `httpPort` default 5151,
+  `0` disables; optional Basic auth via `httpUsername`/`httpPassword`).
+  The `es.exe` CLI remains the always-available fallback and covers
+  `dateCreated`, the extra sort keys, and `regex` + `path`/type-filter
+  combinations the HTTP API cannot express.
+- `exactTotal` (default `true`): set `false` to skip the extra
+  match-count round-trip on full pages; the total then reports as a
+  page-based lower bound (`≥N`, `totalExact: false`).
+- Results now carry `channel` (`"http"`/`"es"`), `totalExact`, and `notes`
+  (non-fatal query-interpretation remarks) so behavior is observable.
+- A whole-query quoted phrase containing spaces (an exact multi-word
+  match) is automatically converted to an equivalent regex — previously
+  it degraded to ANDed words silently.
+
+### Fixed
+- `readExportText` no longer blocks the event loop while waiting out the
+  es.exe export-file flush race (async retry instead of `Atomics.wait`),
+  and a genuinely empty/missing export file now falls back to decoded
+  stdout instead of reporting a fake empty result page.
+- A `path` that does not exist (or points at a file) is rejected up front
+  with `ES_INVALID_ARGS` instead of silently returning "no matches"
+  (UNC paths are checked after a zero-result page).
+- `truncated` is `true` whenever a full page is returned with an
+  inexact total, not only when the exact count exceeds the page.
+
 ## [1.3.1] - 2026-10-27
 
 ### Fixed

package/README.md

@@ -2,9 +2,9 @@
 
 [中文文档](README.zh-CN.md)
 
-A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin that gives the agent an **`everything_search`** tool: whole-disk file and folder search in **milliseconds**, powered by the local [Everything](https://www.voidtools.com/) (voidtools) index through its official command line `es.exe`.
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin that gives the agent an **`everything_search`** tool: whole-disk file and folder search in **milliseconds**, powered by the local [Everything](https://www.voidtools.com/) (voidtools) index.
 
-Instead of recursively scanning directories (glob) when the model needs to locate a file, the agent asks Everything's pre-built index — instant even on drives with millions of files.
+Instead of recursively scanning directories (glob) when the model needs to locate a file, the agent asks Everything's pre-built index — instant even on drives with millions of files. Two channels are used: Everything's built-in HTTP JSON server (loopback only, auto-enabled — no process spawn per call, native UTF-8, exact totals) with the official command line `es.exe` as an always-available fallback for everything the HTTP server cannot express.
 
 ## Requirements
 
@@ -59,13 +59,14 @@ Published on npm as [`dsh-everything`](https://www.npmjs.com/package/dsh-everyth
 | `foldersOnly` / `filesOnly` | boolean | Restrict result type. |
 | `dateCreated` | boolean | Also return each result's creation date. |
 | `countOnly` | boolean | Return only the total match count — the fastest way to check existence or estimate volume. |
+| `exactTotal` | boolean | Default `true`. `false` skips the extra match-count round-trip on full pages and reports a `≥N` total instead. |
 
-Returns `{ query, total, truncated, results: [{ path, size, dateModified, dateCreated? }] }` and renders in the chat as a search-paths card.
+Returns `{ query, total, totalExact, truncated, results: [{ path, size, dateModified, dateCreated? }], channel, notes }` (`channel` is `"http"` or `"es"`; `notes` carries query-interpretation remarks) and renders in the chat as a search-paths card.
 
 Typical queries: `report ext:docx` · `*.sln dm:thisweek` · `size:>500mb` · `notes !archive` · recently changed files with `sort: date-modified-descending` + `dm:thisweek`.
 
-> **Phrase quirks:** a quoted phrase only matches the *name* part, so `"report.docx"` matches nothing — pass it unquoted. Phrases containing spaces cannot be expressed through the es.exe CLI (they degrade to ANDed words); use `regex=true` for exact multi-word matching.
-> **Encoding:** results are read from es.exe's UTF-8 `-export-json` output, so non-ASCII file names (Chinese, Japanese, emoji, …) survive the round trip intact.
+> **Phrase quirks:** a quoted phrase only matches the *name* part, so `"report.docx"` matches nothing — pass it unquoted. A quoted phrase **containing spaces that is the whole query** (an exact multi-word match) is automatically converted to an equivalent regex; one embedded alongside other terms degrades to ANDed words and is reported in `notes` (use `regex=true` for those).
+> **Encoding:** the HTTP channel is UTF-8 natively; the es.exe fallback reads its UTF-8 `-export-json` output — non-ASCII file names (Chinese, Japanese, emoji, …) survive the round trip intact either way.
 
 > **Scope note:** searches names and paths only, never file contents — content search stays with `grep`.
 > **Coverage note:** results follow the local Everything index — NTFS/reFS drives and folders explicitly added to the index. FAT/exFAT removable drives and network shares are typically not covered.
@@ -82,11 +83,20 @@ Edit the plugin's `config` in `cordis.patch.yml` (or your profile's patch layer)
 | `autoInstall` | `true` | Download & install Everything + ES CLI when missing (see above). |
 | `installDir` | `%LOCALAPPDATA%\dsh-everything` | Where the auto-installed ES CLI lives. |
 | `maxResults` | `100` | Default per-call result cap. |
-| `timeoutMs` | `8000` | Per-spawn timeout (ms). |
+| `timeoutMs` | `8000` | Per-call timeout (ms). |
+| `httpPort` | `5151` | Everything HTTP server port for the fast channel; `0` disables the HTTP channel entirely. |
+| `httpAutoEnable` | `true` | When the HTTP server is down, once per session: patch Everything's own config (unlock + enable + loopback bind) and restart its GUI. Set `false` to never touch Everything's config. |
+| `httpUsername` / `httpPassword` | `''` | Optional Basic-auth credentials for the HTTP server. |
+
+### Fast path: the built-in HTTP server
+
+Everything 1.4 ships with an HTTP JSON server, but it is **disabled and policy-locked by default** — installed builds write `allow_http_server=0` next to `Everything.exe`, and the GUI cannot unlock it. With `httpAutoEnable: true` the plugin flips that switch itself (one-time, once per session): it patches both `Everything.ini` files, binds the server to **127.0.0.1 only**, restarts the Everything GUI, and routes searches through it. The background index service keeps running untouched.
+
+The HTTP channel serves plain searches, `path`/`foldersOnly`/`filesOnly` scope, `countOnly`, pagination, and the `name`/`path`/`size`/`date-modified` sort keys. Everything else — `dateCreated`, other sort keys, and `regex` combined with a `path` or type filter — automatically uses the es.exe channel instead. If the HTTP server cannot be started (port busy, Everything not installed yet), the plugin silently stays on es.exe and retries later; a `path` that does not exist is reported as an error rather than an empty result.
 
 ## Privacy
 
-The search scope is **every indexed drive** on the machine, and result paths are sent to the model as tool output. Keep that in mind on machines with sensitive directory layouts; use `path` to scope searches.
+The search scope is **every indexed drive** on the machine, and result paths are sent to the model as tool output. Keep that in mind on machines with sensitive directory layouts; use `path` to scope searches. The HTTP fast path listens on `127.0.0.1` only — nothing is exposed to the network.
 
 ## Development
 

package/README.zh-CN.md

@@ -2,9 +2,9 @@
 
 [English](README.md)
 
-一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）插件，为模型注册 **`everything_search`** 工具：借助本机 [Everything](https://www.voidtools.com/)（voidtools）索引，通过官方命令行 `es.exe` 实现**毫秒级**全盘文件/文件夹搜索。
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）插件，为模型注册 **`everything_search`** 工具：借助本机 [Everything](https://www.voidtools.com/)（voidtools）索引，实现**毫秒级**全盘文件/文件夹搜索。
 
-当模型需要找文件时，不再递归遍历目录（glob），而是直接查询 Everything 预先建好的索引——即使磁盘上有数百万文件也是秒回。
+当模型需要找文件时，不再递归遍历目录（glob），而是直接查询 Everything 预先建好的索引——即使磁盘上有数百万文件也是秒回。内部走两条通道：优先用 Everything 内置的 HTTP JSON 服务（仅绑定 127.0.0.1，插件会自动启用——每次调用无需再拉起进程、原生 UTF-8、精确总数免费自带），官方命令行 `es.exe` 作为兜底，覆盖 HTTP 服务表达不了的一切查询。
 
 ## 环境要求
 
@@ -57,13 +57,14 @@ plugin_manager install_bundle，target = dsh-everything
 | `foldersOnly` / `filesOnly` | boolean | 只看文件夹 / 只看文件。 |
 | `dateCreated` | boolean | 一并返回每个结果的创建时间。 |
 | `countOnly` | boolean | 只返回匹配总数——判断存在性、估量级的最快方式。 |
+| `exactTotal` | boolean | 默认 `true`。设 `false` 时整页结果不再额外做一次计数往返，总数显示为 `≥N` 下界。 |
 
-返回 `{ query, total, truncated, results: [{ path, size, dateModified, dateCreated? }] }`，在会话里以搜索路径卡片展示。
+返回 `{ query, total, totalExact, truncated, results: [{ path, size, dateModified, dateCreated? }], channel, notes }`（`channel` 为 `"http"` 或 `"es"`；`notes` 携带查询解释说明），在会话里以搜索路径卡片展示。
 
 典型查询：`report ext:docx` · `*.sln dm:thisweek` · `size:>500mb` · `notes !archive` · 最近改动文件用 `sort: date-modified-descending` + `dm:thisweek`。
 
-> **短语怪癖**：带引号的短语只匹配文件名的“名字部分”，所以 `"report.docx"` 永远搜不到——直接写不带引号的 `report.docx`。含空格的短语无法经 es.exe CLI 表达（会退化为逐词 AND）；需要精确多词匹配请用 `regex=true`。
-> **编码**：结果改从 es.exe 的 UTF-8 `-export-json` 输出读取，非 ASCII 文件名（中文、日文、emoji 等）完整回传、不再乱码。
+> **短语怪癖**：带引号的短语只匹配文件名的“名字部分”，所以 `"report.docx"` 永远搜不到——直接写不带引号的 `report.docx`。**整条查询**就是一个含空格的引号短语（精确多词匹配）时，插件会自动转换成等价正则；与其他词混用的引号短语会退化为逐词 AND 并在 `notes` 里说明（这类场景请显式用 `regex=true`）。
+> **编码**：HTTP 通道原生 UTF-8；es.exe 兜底通道从其 UTF-8 `-export-json` 输出读取——无论哪条通道，非 ASCII 文件名（中文、日文、emoji 等）都完整回传、不再乱码。
 
 > **范围说明**：只搜文件名和路径，不搜文件内容——内容搜索请继续用 `grep`。
 > **覆盖说明**：结果取决于本机 Everything 索引——NTFS/reFS 磁盘与显式加入索引的目录；FAT/exFAT 可移动盘与网络共享通常不在覆盖范围。
@@ -80,11 +81,20 @@ plugin_manager install_bundle，target = dsh-everything
 | `autoInstall` | `true` | 后端缺失时自动下载并安装 Everything + ES CLI（见上文）。 |
 | `installDir` | `%LOCALAPPDATA%\dsh-everything` | 自动安装的 ES CLI 存放目录。 |
 | `maxResults` | `100` | 单次返回条数默认上限。 |
-| `timeoutMs` | `8000` | 单次 spawn 超时（毫秒）。 |
+| `timeoutMs` | `8000` | 单次调用超时（毫秒）。 |
+| `httpPort` | `5151` | 快速通道的 Everything HTTP 服务端口；设 `0` 完全关闭 HTTP 通道。 |
+| `httpAutoEnable` | `true` | HTTP 服务未开启时，每会话一次：自动改写 Everything 自身配置（解锁+启用+仅回环绑定）并重启其 GUI。设 `false` 则永不触碰 Everything 的配置。 |
+| `httpUsername` / `httpPassword` | `''` | HTTP 服务的可选 Basic 认证凭据。 |
+
+### 快速通道：内置 HTTP 服务
+
+Everything 1.4 自带 HTTP JSON 服务，但**默认是关闭且被策略锁死的**——安装版会在 `Everything.exe` 旁写入 `allow_http_server=0`，GUI 里也解不了锁。`httpAutoEnable: true`（默认）时插件会亲自翻开这个开关（每会话一次）：同时补丁两份 `Everything.ini`、把服务**只绑定到 127.0.0.1**、重启 Everything GUI，之后搜索都走 HTTP。后台索引服务全程不受影响。
+
+HTTP 通道覆盖：普通搜索、`path`/`foldersOnly`/`filesOnly` 范围限定、`countOnly`、分页，以及 `name`/`path`/`size`/`date-modified` 排序键。其余——`dateCreated`、其他排序键、`regex` 搭配 `path` 或类型过滤——自动改走 es.exe 通道。HTTP 服务起不来（端口被占、Everything 未安装）时插件静默留在 es.exe 通道、稍后重试；`path` 指向不存在的路径会直接报错，而不是返回空结果。
 
 ## 隐私
 
-搜索范围是本机**所有已索引磁盘**，结果路径会作为工具输出发给模型。在目录结构敏感的机器上请注意，可用 `path` 参数收窄范围。
+搜索范围是本机**所有已索引磁盘**，结果路径会作为工具输出发给模型。在目录结构敏感的机器上请注意，可用 `path` 参数收窄范围。HTTP 快速通道只监听 `127.0.0.1`——不向网络暴露任何东西。
 
 ## 开发
 

package/cordis.patch.yml

@@ -6,3 +6,7 @@
         autoInstall: true
         maxResults: 100
         timeoutMs: 8000
+        httpPort: 5151
+        httpAutoEnable: true
+        httpUsername: ''
+        httpPassword: ''

package/index.js

@@ -1,13 +1,19 @@
 /**
  * dsh-everything: model-facing `everything_search` tool backed by the local
- * Everything (voidtools) index through the official ES command line (es.exe).
+ * Everything (voidtools) index.
  *
- * The tool spawns es.exe with a fixed argv vector (no shell layer), reads its
- * results from a UTF-8 `-export-json` file (immune to console codepages), and
- * projects results onto the built-in search-paths card.
- * No external npm dependencies. Windows only: Everything itself is a Windows
- * application, so on other platforms a stub tool is registered that fails with
- * a clear platform message instead of a confusing spawn error.
+ * Two channels, tried in order:
+ *   1. Everything's built-in HTTP JSON server (127.0.0.1 only) — no process
+ *      spawn per call, native UTF-8, exact totals for free. Auto-enabled from
+ *      the plugin when httpAutoEnable is on (one Everything GUI restart).
+ *   2. The official ES command line (es.exe) — always available as fallback
+ *      (and used for dateCreated, unsupported sort keys, and regex+scope
+ *      combos). Results are read from a UTF-8 `-export-json` file, immune to
+ *      console codepages.
+ * Results project onto the built-in search-paths card. No external npm
+ * dependencies. Windows only: Everything itself is a Windows application, so
+ * on other platforms a stub tool is registered that fails with a clear
+ * platform message instead of a confusing spawn error.
  *
  * Config (set in cordis.patch.yml):
  *   esPath         absolute path to es.exe (default: well-known locations, then auto-install)
@@ -16,13 +22,18 @@
  *   autoInstall    download & install Everything + ES CLI when missing (default: true)
  *   installDir     where the auto-installed ES CLI lives (default: %LOCALAPPDATA%\dsh-everything)
  *   maxResults     default per-call result cap (default: 100, ceiling: 1000)
- *   timeoutMs      per-spawn timeout in milliseconds (default: 8000)
+ *   timeoutMs      per-call timeout in milliseconds (default: 8000)
+ *   httpPort       Everything HTTP server port; 0 disables the HTTP channel (default: 5151)
+ *   httpAutoEnable flip Everything's own config to start its HTTP server (default: true)
+ *   httpUsername   optional Basic-auth user for the Everything HTTP server (default: '')
+ *   httpPassword   optional Basic-auth password (default: '')
  */
 import { execFile, spawn } from 'node:child_process';
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join as joinPath, win32 as win32path } from 'node:path';
-import { ensureBackend, EverythingError } from './setup.js';
+import { ensureBackend, ensureHttpServer, probeHttpPort, EverythingError } from './setup.js';
 
 const DEFAULT_MAX_RESULTS = 100;
 const DEFAULT_TIMEOUT_MS = 8000;
@@ -30,6 +41,11 @@ const MAX_RESULTS_CEILING = 1000;
 const MAX_BUFFER = 32 * 1024 * 1024;
 const AUTOSTART_WAIT_MS = 15000;
 const SETUP_BUDGET_MS = 240000;
+const DEFAULT_HTTP_PORT = 5151;
+/** After an HTTP failure, stay on the es.exe channel for this long before probing again. */
+const HTTP_RETRY_DOWN_MS = 30000;
+/** Per-request cap for HTTP calls (hot latency is ~2ms; 5s covers worst cases). */
+const HTTP_REQUEST_CAP_MS = 5000;
 
 /** Fallback candidates when the patch config does not pin `esPath`. */
 const ES_CANDIDATES = [
@@ -40,6 +56,9 @@ const ES_CANDIDATES = [
 
 const SORT_NAME_RE = /^[a-z][a-z0-9-]*(-(ascending|descending))?$/i;
 
+/** Sort keys the Everything HTTP server understands (es.exe accepts more). */
+const HTTP_SORT_KEYS = { name: 'name', path: 'path', size: 'size', 'date-modified': 'date_modified' };
+
 export { EverythingError };
 
 function clampInt(value, min, max, fallback) {
@@ -156,11 +175,14 @@ async function autoStartEverything(everythingPath, esPath, signal) {
  * `*.docx dm:thisweek` MUST be passed as two arguments. Quoted phrases
  * without spaces keep their quotes (phrase semantics); a quoted phrase that
  * contains a space cannot be expressed positionally, so it degrades to its
- * component words ANDed together (use regex=true for exact multi-word
- * matching).
+ * component words ANDed together (report it so callers can switch to regex).
+ *
+ * Returns { terms, degraded } — `degraded` lists the quoted phrases that had
+ * to be split (only used for the user-facing note).
  */
 function tokenizeQuery(query) {
-  const tokens = [];
+  const terms = [];
+  const degraded = [];
   let current = '';
   let inQuotes = false;
   const flush = () => {
@@ -168,12 +190,14 @@ function tokenizeQuery(query) {
     if (/\s/.test(current)) {
       // Only reachable for a quoted phrase with internal spaces: es.exe cannot
       // take it as one term, so degrade to its component words (quotes stripped).
+      const bare = current.replace(/"/g, '').trim();
+      if (bare.length > 0) degraded.push(bare);
       for (const word of current.split(/\s+/)) {
-        const bare = word.replace(/"/g, '');
-        if (bare.length > 0) tokens.push(bare);
+        const w = word.replace(/"/g, '');
+        if (w.length > 0) terms.push(w);
       }
     } else if (current.replace(/"/g, '').length > 0) {
-      tokens.push(current);
+      terms.push(current);
     }
     current = '';
   };
@@ -188,7 +212,35 @@ function tokenizeQuery(query) {
     }
   }
   flush();
-  return tokens;
+  return { terms, degraded };
+}
+
+/**
+ * Pre-process a raw query. A quoted phrase WITH spaces that is the whole
+ * query (the only exact-phrase intent es.exe cannot express) is converted to
+ * an equivalent regex (`word\s+word`), because both channels accept regex.
+ */
+function prepareQuery(query) {
+  const trimmed = query.trim();
+  const m = /^"([^"]*\s[^"]*)"$/.exec(trimmed);
+  if (m) {
+    return {
+      query: phraseToRegex(m[1]),
+      regex: true,
+      note: `exact phrase "${m[1]}" was converted to a regular expression (quoted phrases with spaces are not expressible otherwise)`,
+    };
+  }
+  return { query: trimmed, regex: false, note: null };
+}
+
+/** Escape each word and join with `\s+` — a regex equivalent of a phrase. */
+function phraseToRegex(phrase) {
+  const escapeRe = /[.*+?^${}()|[\]\\]/g;
+  return phrase
+    .split(/\s+/)
+    .filter((w) => w.length > 0)
+    .map((w) => w.replace(escapeRe, '\\$&'))
+    .join('\\s+');
 }
 
 /** Decode es.exe stdout: it emits the console/ANSI codepage, not UTF-8. */
@@ -208,11 +260,13 @@ let exportFileCounter = 0;
 /**
  * Read the UTF-8 file written by `es.exe -export-json <file>`.
  * The file occasionally exists but is still empty right after the process
- * exits (flush race), so an empty read is retried briefly.
- * Returns { exists, text } — `exists: false` lets the caller fall back to
- * decoding stdout (e.g. an es.exe build that ignores -export-json).
+ * exits (flush race), so an empty read is retried briefly (async, never
+ * blocking the event loop).
+ * Returns { exists, text } — `exists: false` (or empty text) lets the caller
+ * fall back to decoding stdout (e.g. an es.exe build that ignores
+ * -export-json).
  */
-function readExportText(filePath) {
+async function readExportText(filePath) {
   for (let attempt = 0; attempt < 4; attempt++) {
     try {
       const text = readFileSync(filePath, 'utf8');
@@ -221,7 +275,7 @@ function readExportText(filePath) {
       return { exists: false, text: '' };
     }
     // exists but empty: brief wait for the flush race
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    await sleep(100);
   }
   return { exists: true, text: '' };
 }
@@ -247,7 +301,7 @@ function buildSearchFlags(args, query) {
   }
   if (args.regex === true) argv.push('-regex', query);
   else {
-    const terms = tokenizeQuery(query);
+    const { terms } = tokenizeQuery(query);
     if (terms.length === 0) {
       throw new EverythingError('everything_search: "query" must contain at least one search term (not only quotes or whitespace).', 'ES_INVALID_ARGS');
     }
@@ -278,6 +332,98 @@ function parseResults(stdout) {
   return results;
 }
 
+// ---------------------------------------------------------------------------
+// HTTP channel (Everything's built-in JSON server on 127.0.0.1)
+// ---------------------------------------------------------------------------
+
+/** Map our sort names onto HTTP params. null = this sort must use es.exe. */
+function httpSortParams(sort) {
+  if (typeof sort !== 'string' || sort.trim().length === 0) return {};
+  const s = sort.trim();
+  const key = s.replace(/-(ascending|descending)$/i, '');
+  const httpKey = HTTP_SORT_KEYS[key];
+  if (!httpKey) return null;
+  return { sort: httpKey, ascending: /-descending$/i.test(s) ? 0 : 1 };
+}
+
+/**
+ * URL parameters for the Everything HTTP server (pure, exported for tests).
+ * Scope (`path:`) and type (`folder:`/`file:`) filters are folded into the
+ * search text — the HTTP API has no dedicated parameters for them. NOTE: in
+ * regex mode Everything does not interpret those prefixes, so the caller
+ * routes regex+scope combos to es.exe instead.
+ */
+function httpSearchParams(input, query, { limit, offset }) {
+  let search = query;
+  if (input.foldersOnly === true) search = `folder:${search}`;
+  else if (input.filesOnly === true) search = `file:${search}`;
+  if (typeof input.path === 'string' && input.path.trim().length > 0) search += ` path:"${input.path.trim()}"`;
+  const params = {
+    search,
+    json: '1',
+    count: String(input.countOnly === true ? 1 : limit),
+    offset: String(offset),
+    // JSON mode defaults count to 4294967295 — always pass it explicitly. The
+    // *_column switches make results carry the fields we project.
+    path_column: '1',
+    size_column: '1',
+    date_modified_column: '1',
+  };
+  if (input.regex === true) params.regex = '1';
+  if (input.matchCase === true) params.case = '1';
+  if (input.wholeWord === true) params.wholeword = '1';
+  const sort = httpSortParams(input.sort);
+  if (sort && sort.sort) {
+    params.sort = sort.sort;
+    params.ascending = String(sort.ascending);
+  }
+  return params;
+}
+
+/**
+ * Convert a Windows FILETIME string (> 2^53, needs BigInt) into the same
+ * local "YYYY-MM-DDTHH:MM:SS" rendering es.exe -date-format 1 produces.
+ * Returns undefined on garbage input.
+ */
+function fileTimeToLocalIso(fileTime) {
+  try {
+    const n = typeof fileTime === 'bigint' ? fileTime : BigInt(fileTime);
+    const ms = Number((n - 116444736000000000n) / 10000n);
+    const d = new Date(ms);
+    if (Number.isNaN(d.getTime())) return undefined;
+    const p = (x) => String(x).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/** fetch with a timeout, honoring the caller's abort signal. */
+async function fetchHttp(url, { headers, signal, timeoutMs }) {
+  const ctrl = new AbortController();
+  const onAbort = () => ctrl.abort();
+  let timer = null;
+  try {
+    if (signal) {
+      if (signal.aborted) throw new EverythingError('everything_search: the call was aborted (tool timeout or caller cancellation).', 'ES_ABORTED');
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+    timer = setTimeout(() => ctrl.abort(new Error('timeout')), timeoutMs);
+    return await fetch(url, { headers, signal: ctrl.signal });
+  } catch (error) {
+    if (signal?.aborted) throw new EverythingError('everything_search: the call was aborted (tool timeout or caller cancellation).', 'ES_ABORTED');
+    const cause = error?.cause?.code ?? error?.message ?? String(error);
+    throw new EverythingError(`everything_search: the Everything HTTP server on 127.0.0.1 is unreachable (${cause}).`, 'ES_HTTP_UNREACHABLE');
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (signal) signal.removeEventListener('abort', onAbort);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rendering / presentation
+// ---------------------------------------------------------------------------
+
 function formatSize(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
@@ -287,7 +433,7 @@ function formatSize(bytes) {
 
 function renderResults(value) {
   const lines = [];
-  const { query, total, truncated, results, countOnly } = value;
+  const { query, total, truncated, results, countOnly, totalExact, notes } = value;
   if (countOnly) {
     lines.push(total === 0 ? `Everything "${query}": no matches.` : `Everything "${query}": ${total} match(es) (count only).`);
     return lines.join('\n');
@@ -296,7 +442,9 @@ function renderResults(value) {
     lines.push(`Everything "${query}": no matches.`);
     return lines.join('\n');
   }
-  lines.push(`Everything "${query}": ${results.length} of ${total} result(s)${truncated ? ' (truncated, refine the query, raise maxResults, or page with offset)' : ''}:`);
+  const totalText = totalExact === false ? `≥${total}` : String(total);
+  lines.push(`Everything "${query}": ${results.length} of ${totalText} result(s)${truncated ? ' (truncated, refine the query, raise maxResults, or page with offset)' : ''}:`);
+  for (const note of Array.isArray(notes) ? notes : []) lines.push(`  note: ${note}`);
   for (const entry of results) {
     const meta = [entry.size !== undefined ? formatSize(entry.size) : null, entry.dateModified ?? null, entry.dateCreated ? `created ${entry.dateCreated}` : null]
       .filter(Boolean)
@@ -338,7 +486,7 @@ const PARAMETERS_SCHEMA = {
     },
     path: {
       type: 'string',
-      description: 'Restrict the search to this directory and everything below it (absolute path).',
+      description: 'Restrict the search to this directory and everything below it (absolute path; must exist).',
     },
     maxResults: {
       type: 'integer',
@@ -366,13 +514,18 @@ const PARAMETERS_SCHEMA = {
       type: 'boolean',
       description: 'Return only the total number of matches, without listing paths (fastest way to check existence or estimate volume).',
     },
+    exactTotal: {
+      type: 'boolean',
+      description:
+        'When a full page is returned, fetch the exact total match count (default true). Set false to skip that extra round-trip and get a fast "≥N" total.',
+    },
   },
   required: ['query'],
   additionalProperties: false,
 };
 
 const TOOL_DESCRIPTION =
-  'Locate files and folders across every indexed drive on this machine through the local Everything (voidtools) index — answers in milliseconds, far faster than glob or a recursive directory scan. Use this FIRST whenever you need to find a file or folder by name, extension, or path, especially outside the workspace. The query uses Everything search syntax, not a glob: plain words match names, `*`/`?` wildcards, `ext:js;ts` filters extensions, `dm:today` / `dm:thisweek` filter date modified, `size:>10mb` filters size, space means AND, `|` means OR, `!` means NOT. Two quoting quirks: do NOT quote a filename-with-extension like "report.docx" — quoted phrases only match the name part, so pass it unquoted; and quoted phrases must not contain spaces (use regex=true for exact multi-word matching). Combine sort="date-modified-descending" with dm:thisweek for recently changed files, or sort="size-descending" to find the biggest ones first. Restrict scope with the dedicated path parameter rather than a path: prefix inside query. Set regex=true for a full regular expression over the whole path, countOnly=true for a fast match count without paths, dateCreated=true to also return creation dates. Returns absolute paths with size and date modified; non-ASCII names come back intact. Names and paths only, never file contents — use grep for content. Coverage follows the local Everything index: NTFS/reFS drives and explicitly added folders; FAT/exFAT removable drives and network shares are typically not indexed.';
+  'Locate files and folders across every indexed drive on this machine through the local Everything (voidtools) index — answers in milliseconds, far faster than glob or a recursive directory scan. Use this FIRST whenever you need to find a file or folder by name, extension, or path, especially outside the workspace. The query uses Everything search syntax, not a glob: plain words match names, `*`/`?` wildcards, `ext:js;ts` filters extensions, `dm:today` / `dm:thisweek` filter date modified, `size:>10mb` filters size, space means AND, `|` means OR, `!` means NOT. Two quoting quirks: do NOT quote a filename-with-extension like "report.docx" — quoted phrases only match the name part, so pass it unquoted; a whole-query quoted phrase with spaces (exact multi-word match) is auto-converted to a regex. Combine sort="date-modified-descending" with dm:thisweek for recently changed files, or sort="size-descending" to find the biggest ones first. Restrict scope with the dedicated path parameter rather than a path: prefix inside query. Set regex=true for a regular expression over the whole path, countOnly=true for a fast match count without paths, dateCreated=true to also return creation dates, exactTotal=false to trade the exact total for speed on full pages. Returns absolute paths with size and date modified; non-ASCII names come back intact. Names and paths only, never file contents — use grep for content. Coverage follows the local Everything index: NTFS/reFS drives and explicitly added folders; FAT/exFAT removable drives and network shares are typically not indexed.';
 
 const OUTPUT_SCHEMA = {
   type: 'object',
@@ -381,8 +534,11 @@ const OUTPUT_SCHEMA = {
   properties: {
     query: { type: 'string' },
     total: { type: 'integer' },
+    totalExact: { type: 'boolean', description: 'false means total is a page-based lower bound ("≥N").' },
     truncated: { type: 'boolean' },
     countOnly: { type: 'boolean' },
+    channel: { type: 'string', description: 'Which Everything channel served the call: "http" or "es".' },
+    notes: { type: 'array', items: { type: 'string' }, description: 'Non-fatal remarks about how the query was interpreted.' },
     results: {
       type: 'array',
       items: {
@@ -424,11 +580,20 @@ export function apply(ctx, config = {}) {
   const autoInstall = config.autoInstall !== false;
   const maxResults = clampInt(config.maxResults, 1, MAX_RESULTS_CEILING, DEFAULT_MAX_RESULTS);
   const timeoutMs = clampInt(config.timeoutMs, 1000, 60000, DEFAULT_TIMEOUT_MS);
+  const httpPort = clampInt(config.httpPort, 0, 65535, DEFAULT_HTTP_PORT);
+  const httpAutoEnable = config.httpAutoEnable !== false;
+  const httpUsername = typeof config.httpUsername === 'string' ? config.httpUsername.trim() : '';
+  const httpPassword = typeof config.httpPassword === 'string' ? config.httpPassword : '';
 
   // Mutable: auto-install may re-resolve both paths after provisioning.
   let esPath = resolveEsPath(config);
   let everythingPath = resolveEverythingPath(config, esPath ?? 'es.exe');
 
+  // HTTP channel state: cached readiness, a 30s breaker after failures, and
+  // a one-shot flag so an auth failure is logged once, not per call.
+  const httpState = { ready: false, downUntil: 0, authWarned: false };
+  let httpSetupDone = false;
+
   /**
    * One shared provisioning run. Rejects clear the cache so the next call can
    * retry (e.g. after the user approves a UAC prompt on a second attempt).
@@ -451,10 +616,27 @@ export function apply(ctx, config = {}) {
           }
         },
       })
-        .then((result) => {
+        .then(async (result) => {
           esPath = result.esPath;
           everythingPath = result.everythingPath;
           if (result.installed.length > 0) ctx.logger?.info?.(`everything_search: auto-installed ${result.installed.join(', ')} under ${result.installDir}`);
+          // One-time attempt to switch Everything's own config on so its
+          // HTTP JSON server starts (the fast channel). Best effort only.
+          if (httpPort > 0 && httpAutoEnable && !httpSetupDone) {
+            httpSetupDone = true;
+            try {
+              const r = await ensureHttpServer({ port: httpPort, everythingPath, log: ctx.logger, username: httpUsername, password: httpPassword });
+              if (r.enabled || r.alreadyRunning) {
+                httpState.ready = true;
+                httpState.downUntil = 0; // clear the breaker so the next call uses HTTP
+              }
+              if (r.enabled) {
+                ctx.logger?.info?.(`everything_search: HTTP channel enabled (127.0.0.1:${httpPort}); searches will skip per-call es.exe launches.`);
+              }
+            } catch (error) {
+              ctx.logger?.warn?.(`everything_search: HTTP channel setup failed (${error?.message ?? error}); staying on the es.exe channel.`);
+            }
+          }
           return result;
         })
         .catch((error) => {
@@ -517,21 +699,111 @@ export function apply(ctx, config = {}) {
         stdoutBuf = await runEsWithRetry(searchArgv, signal);
         return { flags, results: parseResults(decodeEsStdout(stdoutBuf)) };
       }
-      const exported = readExportText(exportPath);
-      if (!exported.exists) {
-        // No file written: an es.exe that ignores the option printed to stdout.
+      const exported = await readExportText(exportPath);
+      if (!exported.exists || exported.text.length === 0) {
+        // No file written (or an es.exe that ignores the option): fall back
+        // to decoding stdout instead of reporting a fake empty result.
         return { flags, results: parseResults(decodeEsStdout(stdoutBuf)) };
       }
       return { flags, results: parseResults(exported.text) };
     } finally {
       try {
-        unlinkSync(exportPath);
+        await unlink(exportPath);
       } catch {
         /* best effort */
       }
     }
   }
 
+  /** Is the HTTP channel up? Probes lazily; 30s breaker after failures. */
+  async function httpChannelReady() {
+    if (httpPort <= 0) return false;
+    if (httpState.ready) return true;
+    if (Date.now() < httpState.downUntil) return false;
+    try {
+      await probeHttpPort(httpPort, { timeoutMs: 1500, username: httpUsername, password: httpPassword });
+      httpState.ready = true;
+      return true;
+    } catch {
+      httpState.downUntil = Date.now() + HTTP_RETRY_DOWN_MS;
+      // The server is down: one shot per session at switching Everything's
+      // own config on (config patch + GUI restart, never blocks this call).
+      if (httpAutoEnable && !httpSetupDone && (esPath || existsSync(everythingPath))) {
+        void ensureReady().catch(() => {
+          /* logged inside ensureReady */
+        });
+      }
+      return false;
+    }
+  }
+
+  /** One HTTP search (or count). Throws ES_HTTP_* to let the caller fall back to es.exe. */
+  async function httpSearch(input, query, limit, offset, signal) {
+    const params = httpSearchParams(input, query, { limit, offset });
+    const url = `http://127.0.0.1:${httpPort}/?${new URLSearchParams(params).toString()}`;
+    const headers = httpUsername ? { authorization: `Basic ${Buffer.from(`${httpUsername}:${httpPassword}`).toString('base64')}` } : undefined;
+    const res = await fetchHttp(url, { headers, signal, timeoutMs: Math.min(timeoutMs, HTTP_REQUEST_CAP_MS) });
+    if (res.status === 401 || res.status === 403) {
+      throw new EverythingError(`everything_search: the Everything HTTP server rejected the credentials (HTTP ${res.status}); check httpUsername/httpPassword in the plugin config.`, 'ES_HTTP_AUTH');
+    }
+    if (!res.ok) {
+      throw new EverythingError(`everything_search: the Everything HTTP server returned HTTP ${res.status}.`, 'ES_HTTP_UNREACHABLE');
+    }
+    let json;
+    try {
+      json = await res.json();
+    } catch {
+      throw new EverythingError('everything_search: the Everything HTTP server returned a malformed response.', 'ES_HTTP_UNREACHABLE');
+    }
+    if (typeof json?.totalResults !== 'number' || !Array.isArray(json.results)) {
+      throw new EverythingError('everything_search: unexpected JSON from the Everything HTTP server (is another service on that port?).', 'ES_HTTP_UNREACHABLE');
+    }
+    const total = json.totalResults;
+    if (input.countOnly === true) return { total, results: [], truncated: false, totalExact: true, countOnly: true };
+    const results = [];
+    for (const item of json.results) {
+      if (typeof item !== 'object' || item === null) continue;
+      const dir = typeof item.path === 'string' ? item.path : '';
+      const name = typeof item.name === 'string' ? item.name : '';
+      if (name.length === 0 && dir.length === 0) continue;
+      const entry = { path: dir ? (dir.endsWith('\\') ? dir + name : `${dir}\\${name}`) : name };
+      if (typeof item.size === 'string' && item.size.length > 0) {
+        const n = Number(item.size);
+        if (Number.isFinite(n)) entry.size = n;
+      }
+      if (typeof item.date_modified === 'string' && item.date_modified.length > 0) {
+        const iso = fileTimeToLocalIso(item.date_modified);
+        if (iso !== undefined) entry.dateModified = iso;
+      }
+      results.push(entry);
+    }
+    return { total, results, truncated: total > offset + results.length, totalExact: true };
+  }
+
+  /** Reject a local-drive path that does not exist (or is a file) up front. */
+  function validatePathExists(pathArg) {
+    if (/^[a-z]:[\\/]/i.test(pathArg)) {
+      if (!existsSync(pathArg)) {
+        throw new EverythingError(`everything_search: path does not exist: ${pathArg}`, 'ES_INVALID_ARGS');
+      }
+      try {
+        if (statSync(pathArg).isFile()) {
+          throw new EverythingError(`everything_search: path must be a directory, not a file: ${pathArg} (drop the path parameter, or pass its parent directory).`, 'ES_INVALID_ARGS');
+        }
+      } catch (error) {
+        if (error instanceof EverythingError) throw error;
+        /* statSync raced — treat as existing */
+      }
+    }
+  }
+
+  /** UNC paths cannot be stat-checked cheaply up front: check after a miss. */
+  function noteUncMissing(pathArg, results) {
+    if (results.length === 0 && typeof pathArg === 'string' && pathArg.startsWith('\\\\') && !existsSync(pathArg)) {
+      throw new EverythingError(`everything_search: path does not exist: ${pathArg}`, 'ES_INVALID_ARGS');
+    }
+  }
+
   async function execute(args, exec) {
     const input = typeof args === 'object' && args !== null ? args : {};
     const signal = exec?.signal;
@@ -539,34 +811,96 @@ export function apply(ctx, config = {}) {
     if (query.length === 0) throw new EverythingError('everything_search: "query" must be a non-empty Everything search expression.', 'ES_INVALID_ARGS');
     const limit = clampInt(input.maxResults, 1, MAX_RESULTS_CEILING, maxResults);
     const offset = clampInt(input.offset, 0, Number.MAX_SAFE_INTEGER, 0);
+    if (typeof input.sort === 'string' && input.sort.trim().length > 0 && !SORT_NAME_RE.test(input.sort.trim())) {
+      throw new EverythingError(`everything_search: invalid sort "${input.sort.trim()}"; use e.g. "date-modified-descending", "size", "name-ascending".`, 'ES_INVALID_ARGS');
+    }
+
+    // Exact-phrase upgrade (a whole-query quoted phrase with spaces becomes
+    // an equivalent regex — the only way to express it on either channel).
+    const prep = prepareQuery(query);
+    const effectiveQuery = prep.query;
+    const regexMode = input.regex === true || prep.regex;
+    const notes = prep.note ? [prep.note] : [];
+
+    const pathArg = typeof input.path === 'string' ? input.path.trim() : '';
+    if (pathArg.length > 0) validatePathExists(pathArg);
+    const flagsInput = { ...input, regex: regexMode };
+
+    // Channel choice. The HTTP server has no date_created column, supports
+    // only a subset of sort keys, and its regex mode does not interpret
+    // path:/folder:/file: prefixes — those combinations go to es.exe.
+    const httpSortOk = httpSortParams(input.sort) !== null;
+    const httpEligible =
+      httpSortOk &&
+      (input.countOnly === true || input.dateCreated !== true) &&
+      !(regexMode && (pathArg.length > 0 || input.foldersOnly === true || input.filesOnly === true));
+
+    if (httpEligible && (await httpChannelReady())) {
+      try {
+        const res = await httpSearch(flagsInput, effectiveQuery, limit, offset, signal);
+        noteUncMissing(pathArg, res.results);
+        return { query, ...res, channel: 'http', ...(notes.length > 0 ? { notes } : {}) };
+      } catch (error) {
+        if (error instanceof EverythingError && error.code === 'ES_ABORTED') throw error;
+        if (error instanceof EverythingError && (error.code === 'ES_HTTP_UNREACHABLE' || error.code === 'ES_HTTP_AUTH')) {
+          // Circuit-break the HTTP channel for 30s and fall back to es.exe.
+          httpState.ready = false;
+          httpState.downUntil = Date.now() + HTTP_RETRY_DOWN_MS;
+          if (error.code === 'ES_HTTP_AUTH' && !httpState.authWarned) {
+            httpState.authWarned = true;
+            ctx.logger?.warn?.(error.message);
+          }
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    // es.exe channel. Report phrases that had to be degraded to ANDed words.
+    if (!regexMode) {
+      const { degraded } = tokenizeQuery(effectiveQuery);
+      for (const phrase of degraded) {
+        notes.push(`quoted phrase "${phrase}" contains spaces; matched as ANDed words instead (use regex=true, or a whole-query quoted phrase, for exact multi-word matching)`);
+      }
+    }
 
     // Count-only mode: one IPC round-trip, no paths listed.
     if (input.countOnly === true) {
-      const flags = buildSearchFlags(input, query);
+      const flags = buildSearchFlags(flagsInput, effectiveQuery);
       const countOut = await runEsWithRetry(['-get-result-count', ...flags], signal);
       const total = Number.parseInt(String(countOut).trim(), 10);
       if (!Number.isFinite(total) || total < 0) {
         throw new EverythingError(`everything_search: could not parse the result count ("${countOut}").`, 'ES_PARSE_FAILED');
       }
-      return { query, total, truncated: false, results: [], countOnly: true };
+      return { query, total, truncated: false, results: [], countOnly: true, totalExact: true, channel: 'es', ...(notes.length > 0 ? { notes } : {}) };
     }
 
-    const { flags, results } = await searchOnce(input, query, limit, offset, signal);
+    const { flags, results } = await searchOnce(flagsInput, effectiveQuery, limit, offset, signal);
+    noteUncMissing(pathArg, results);
 
     // The exact total costs a second IPC round-trip; only fetch it when the
-    // page is full and truncation is actually possible.
+    // page is full and the caller has not opted out (exactTotal=false).
     let total = offset + results.length;
-    if (results.length === limit) {
+    let totalExact = results.length < limit;
+    if (results.length === limit && input.exactTotal !== false) {
       try {
         const countOut = await runEs(esPath, ['-get-result-count', ...flags], timeoutMs, signal);
         const parsed = Number.parseInt(String(countOut).trim(), 10);
-        if (Number.isFinite(parsed) && parsed >= total) total = parsed;
+        if (Number.isFinite(parsed) && parsed >= total) {
+          total = parsed;
+          totalExact = true;
+        }
       } catch {
         /* count is cosmetic; keep the page-based estimate */
       }
     }
 
-    return { query, total, truncated: total > offset + results.length, results };
+    // With an exact total, "truncated" means more results exist past this
+    // page; with a page-based estimate (exactTotal=false) a full page always
+    // reports as truncated because more results may exist.
+    const truncated = totalExact ? total > offset + results.length : results.length === limit;
+
+    return { query, total, truncated, totalExact, results, channel: 'es', ...(notes.length > 0 ? { notes } : {}) };
   }
 
   ctx.tools.register({
@@ -595,8 +929,13 @@ export {
   buildSearchFlags,
   clampInt,
   decodeEsStdout,
+  fileTimeToLocalIso,
   formatSize,
+  httpSearchParams,
+  httpSortParams,
   parseResults,
+  phraseToRegex,
+  prepareQuery,
   presentCall,
   presentResult,
   renderResults,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-everything",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "DeepSeek Harness plugin: millisecond whole-disk file search for agents via the local Everything (voidtools) index",
   "keywords": ["dsh", "deepseek-harness", "everything", "voidtools", "file-search", "agent-tool"],
   "license": "MIT",

package/setup.js

@@ -23,7 +23,7 @@
 
 import { execFile, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { createWriteStream, existsSync, mkdirSync } from 'node:fs';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { win32 as win32path } from 'node:path';
 
@@ -412,13 +412,30 @@ export function findEverythingInstall() {
   return null;
 }
 
+/**
+ * Fresh installs ship with the HTTP server feature locked off
+ * (allow_http_server=0 in the ini next to Everything.exe). Open it once at
+ * install time so the fast channel can come up later.
+ */
+function allowHttpInLocalIni(everythingPath, log) {
+  try {
+    const localIni = win32path.join(win32path.dirname(everythingPath), 'Everything.ini');
+    patchIniValue(localIni, 'allow_http_server', 1, { create: true });
+  } catch (error) {
+    log?.warn?.(`everything_search: could not unlock the HTTP server in the Everything.ini next to ${everythingPath} (${error?.message ?? error}).`);
+  }
+}
+
 async function installEverything(installDir, log, proxy) {
   // Strategy 1: winget (present on most Windows 10/11 desktops).
   try {
     log?.info?.('everything_search: installing Everything via winget (a UAC prompt may appear)…');
     await run('winget', buildWingetInstallArgs(), WINGET_TIMEOUT_MS);
     const found = findEverythingInstall();
-    if (found) return { everythingPath: found, via: 'winget' };
+    if (found) {
+      allowHttpInLocalIni(found, log);
+      return { everythingPath: found, via: 'winget' };
+    }
   } catch (error) {
     log?.warn?.(`everything_search: winget install failed (${error?.message ?? error}); falling back to the official setup.`);
   }
@@ -438,6 +455,7 @@ async function installEverything(installDir, log, proxy) {
       'ES_SETUP_FAILED'
     );
   }
+  allowHttpInLocalIni(found, log);
   return { everythingPath: found, via: 'setup' };
 }
 
@@ -520,3 +538,136 @@ export async function ensureBackend({ config = {}, log = null, proxy, probe = nu
 export function launchDetached(binaryPath, argv) {
   spawn(binaryPath, argv, { detached: true, stdio: 'ignore', windowsHide: true }).unref();
 }
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Replace (or append) one `key=value` line in an Everything .ini file.
+ * `onlyIfEmpty` keeps an existing non-empty value (used for bindings so a
+ * user's explicit choice is never overridden). Returns true when the file
+ * was written.
+ */
+export function patchIniValue(filePath, key, value, { create = false, onlyIfEmpty = false } = {}) {
+  let text = '';
+  if (existsSync(filePath)) text = readFileSync(filePath, 'utf8');
+  else if (!create) return false;
+  const line = `${key}=${value}`;
+  const re = new RegExp(`^${key}=.*$`, 'm');
+  if (re.test(text)) {
+    const current = text.match(re)[0];
+    if (onlyIfEmpty && current !== `${key}=`) return false;
+    writeFileSync(filePath, text.replace(re, line), 'utf8');
+    return true;
+  }
+  const out = text.length === 0 ? `[Everything]\n${line}\n` : `${text.endsWith('\n') ? text : `${text}\n`}${line}\n`;
+  writeFileSync(filePath, out, 'utf8');
+  return true;
+}
+
+/**
+ * Probe the Everything HTTP JSON server on 127.0.0.1:<port>. Validates the
+ * `totalResults` field so a foreign service on the same port is detected,
+ * not silently used. Resolves true, or throws ES_HTTP_UNREACHABLE.
+ */
+export async function probeHttpPort(port, { timeoutMs = 1500, username = '', password = '' } = {}) {
+  const url = `http://127.0.0.1:${port}/?${new URLSearchParams({ json: '1', search: '_dsh_probe_', count: '1' }).toString()}`;
+  const headers = username ? { authorization: `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}` } : undefined;
+  let res;
+  try {
+    res = await fetch(url, { headers, signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    throw new EverythingError(`everything_search setup: no Everything HTTP server on 127.0.0.1:${port} (${error?.cause?.code ?? error?.message ?? error}).`, 'ES_HTTP_UNREACHABLE');
+  }
+  if (!res.ok) {
+    throw new EverythingError(`everything_search setup: HTTP probe on 127.0.0.1:${port} returned ${res.status}.`, 'ES_HTTP_UNREACHABLE');
+  }
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    throw new EverythingError(`everything_search setup: the service on 127.0.0.1:${port} is not the Everything HTTP server.`, 'ES_HTTP_UNREACHABLE');
+  }
+  if (typeof json?.totalResults !== 'number') {
+    throw new EverythingError(`everything_search setup: the service on 127.0.0.1:${port} is not the Everything HTTP server.`, 'ES_HTTP_UNREACHABLE');
+  }
+  return true;
+}
+
+/** Kill the Everything GUI (session > 0); the background service is left alone. */
+async function stopEverythingGui() {
+  const script = 'Get-Process Everything -ErrorAction SilentlyContinue | Where-Object { $_.SessionId -ne 0 } | Stop-Process -Force';
+  try {
+    await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], 20000);
+    await sleep(500);
+  } catch {
+    /* best effort — the config patch still applies at next Everything start */
+  }
+}
+
+/**
+ * Turn on Everything's built-in HTTP JSON server.
+ *
+ * Everything 1.4 ships it disabled AND locked: the per-machine policy switch
+ * `allow_http_server` in the Everything.ini next to Everything.exe defaults
+ * to 0 (installed builds), and the per-user %APPDATA% ini only honors
+ * http_server_* when the local lock is open. The server cannot be enabled
+ * through the GUI on locked installs, so we patch both files directly and
+ * restart the GUI (the background index service keeps running untouched).
+ *
+ * Idempotent: returns {enabled: false, alreadyRunning: true} when the server
+ * already answers. All failures are returned, never thrown — the caller
+ * stays on the es.exe channel.
+ */
+export async function ensureHttpServer({ port = 5151, everythingPath, log = null, username = '', password = '' } = {}) {
+  try {
+    await probeHttpPort(port, { username, password });
+    return { enabled: false, alreadyRunning: true };
+  } catch {
+    /* not up yet — continue below */
+  }
+
+  if (!everythingPath || !existsSync(everythingPath)) {
+    return { enabled: false, reason: 'Everything.exe path unknown' };
+  }
+
+  log?.info?.(`everything_search: enabling the Everything HTTP server on 127.0.0.1:${port} (the Everything GUI restarts once)…`);
+  await stopEverythingGui();
+
+  // 1. Unlock the feature in the ini next to Everything.exe (machine policy).
+  const localIni = win32path.join(win32path.dirname(everythingPath), 'Everything.ini');
+  try {
+    patchIniValue(localIni, 'allow_http_server', 1, { create: true });
+  } catch (error) {
+    log?.warn?.(`everything_search: could not patch ${localIni} (${error?.message ?? error}).`);
+  }
+
+  // 2. Enable + configure it in the per-user ini. Bind loopback only when the
+  //    user has not chosen something else.
+  const appDataDir = process.env.APPDATA ?? win32path.join(process.env.USERPROFILE ?? '.', 'AppData', 'Roaming');
+  const appDataIni = win32path.join(appDataDir, 'Everything', 'Everything.ini');
+  try {
+    mkdirSync(win32path.dirname(appDataIni), { recursive: true });
+    patchIniValue(appDataIni, 'http_server_enabled', 1, { create: true });
+    patchIniValue(appDataIni, 'http_server_port', port, { create: true });
+    patchIniValue(appDataIni, 'http_server_username', username, { create: true });
+    patchIniValue(appDataIni, 'http_server_password', password, { create: true });
+    patchIniValue(appDataIni, 'http_server_bindings', '127.0.0.1', { create: true, onlyIfEmpty: true });
+  } catch (error) {
+    log?.warn?.(`everything_search: could not patch ${appDataIni} (${error?.message ?? error}).`);
+  }
+
+  // 3. Restart the GUI detached and wait for the server to answer.
+  launchDetached(everythingPath, ['-startup']);
+  const deadline = Date.now() + 15000;
+  while (Date.now() < deadline) {
+    await sleep(250);
+    try {
+      await probeHttpPort(port, { username, password });
+      return { enabled: true };
+    } catch {
+      /* retry until the deadline */
+    }
+  }
+  log?.warn?.(`everything_search: the Everything HTTP server did not come up on 127.0.0.1:${port} within 15s; staying on the es.exe channel.`);
+  return { enabled: false, reason: 'timeout' };
+}