bridgerator 1.0.7 → 1.1.0

package/src/policy.mjs

@@ -1,109 +1,293 @@
-// Bridge-side access policy, applied BEFORE a call reaches Desktop Commander and to its results.
-// Desktop Commander itself only knows allowedDirectories; it has no "except these folders" rule,
-// so deniedDirectories is enforced here: input paths are resolved (symlinks/junctions included)
-// and refused when they fall inside a denied folder; result lines that mention a denied path are
-// dropped (search hits, recursive listings).
-// The terminal is NOT covered by folder rules (a shell can read anything the user can); commands
-// that name a denied folder are refused as a courtesy, the real control is disabledTools.
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-
-// Tools the model must never get: they would let it rewrite its own limits or leak telemetry.
-export const ALWAYS_HIDDEN = ['set_config_value', 'give_feedback_to_desktop_commander', 'get_usage_stats'];
-// Argument names that carry filesystem paths in Desktop Commander's tools.
-const PATH_KEYS = /^(path|paths|file_path|source|destination|inputPath|outputPath|directory)$/i;
-
-const expandHome = (p) => (p === '~' || p.startsWith('~/') || p.startsWith('~\\') ? path.join(os.homedir(), p.slice(1)) : p);
-export const norm = (p) => path.resolve(expandHome(String(p))).replace(/[\\/]+$/, '').toLowerCase();
-
-// Resolve symlinks/junctions on the deepest existing ancestor, like Desktop Commander does.
-export function realish(p) {
-  let cur = path.resolve(expandHome(String(p)));
-  const rest = [];
-  for (;;) {
-    try { return path.join(fs.realpathSync.native(cur), ...rest); } catch { /* walk up */ }
-    const up = path.dirname(cur);
-    if (up === cur) return path.resolve(expandHome(String(p)));
-    rest.unshift(path.basename(cur));
-    cur = up;
-  }
-}
-
-const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-// "c:\secret" mentioned as a path (not as the prefix of "c:\secretive"), any slash style / JSON escaping.
-const flat = (s) => String(s).toLowerCase().replace(/[\\/]+/g, '\\');
-const mentionRe = (d) => new RegExp(`${esc(d)}(?![a-z0-9_.\\-])`);
-
-export function createPolicy(cfg = {}) {
-  const denied = (cfg.deniedDirectories || []).map((d) => norm(realish(d)));
-  const res = denied.map(mentionRe);
-  const mentionsDenied = (s) => { const f = flat(s); return res.some((r) => r.test(f)); };
-  const hidden = new Set([...ALWAYS_HIDDEN, ...(cfg.disabledTools || [])]);
-  const inDenied = (p) => {
-    const n = norm(p);
-    return denied.find((d) => n === d || n.startsWith(d + path.sep)) || null;
-  };
-  const deniedFor = (p) => inDenied(p) || inDenied(realish(p));
-
-  function pathsIn(args) {
-    const out = [];
-    for (const [k, v] of Object.entries(args || {})) {
-      if (!PATH_KEYS.test(k)) continue;
-      for (const x of Array.isArray(v) ? v : [v]) if (typeof x === 'string' && x) out.push(x);
-    }
-    return out;
-  }
-
-  return {
-    denied,
-    visible: (tool) => !hidden.has(tool.name),
-    // → null when allowed, otherwise the refusal text returned to the model.
-    check(name, args) {
-      if (hidden.has(name)) return `Tool "${name}" is disabled on this computer.`;
-      for (const p of pathsIn(args)) {
-        if (deniedFor(p)) return `Access denied by Bridgerator: "${p}" is inside an excluded folder.`;
-      }
-      for (const k of ['command', 'input']) {
-        if (typeof args?.[k] === 'string' && mentionsDenied(args[k])) return `Access denied by Bridgerator: the ${k} refers to an excluded folder.`;
-      }
-      return null;
-    },
-    // Drop result lines that reveal anything inside a denied folder. `args` lets a listing of a
-    // parent folder hide the excluded child, whose entries are printed relative to that parent.
-    filter(result, name, args) {
-      if (!denied.length || !result || !Array.isArray(result.content)) return result;
-      const rel = [];
-      if (name === 'list_directory' && typeof args?.path === 'string') {
-        const base = norm(realish(args.path));
-        for (const d of denied) if (d.startsWith(base + path.sep)) rel.push(new RegExp(`^${esc(d.slice(base.length + 1))}(?![a-z0-9_.\\-])`));
-      }
-      const leaks = (line) => mentionsDenied(line) || rel.some((r) => r.test(flat(line).trim().replace(/^\[(dir|file)\]\s*/, '')));
-      let dropped = 0;
-      const content = result.content.map((c) => {
-        if (c?.type !== 'text' || typeof c.text !== 'string') return c;
-        const lines = c.text.split(/\r?\n/);
-        const kept = lines.filter((ln) => !leaks(ln));
-        dropped += lines.length - kept.length;
-        return { ...c, text: kept.join('\n') };
-      });
-      if (dropped) content.push({ type: 'text', text: `[Bridgerator: ${dropped} line(s) hidden — excluded folder]` });
-      return { ...result, content };
-    },
-  };
-}
-
-// The bundled engine's own name and links are not shown to the user: tool titles/descriptions and
-// widget HTML say Bridgerator. Tool RESULTS are never rewritten (they are the user's own data).
-const BRAND = [[/"DC: \.\.\." or /g, ''], [/Desktop ?Commander/g, 'Bridgerator'], [/https?:\/\/(www\.)?desktopcommander\.app[^\s"'\)<]*/g, 'https://bridgerator.recondeck.com']];
-export function debrand(v) {
-  if (typeof v === 'string') return BRAND.reduce((s, [re, to]) => s.replace(re, to), v);
-  if (Array.isArray(v)) return v.map(debrand);
-  if (v && typeof v === 'object') {
-    const o = {};
-    // _meta keys (ui:// template URIs) are identifiers, not user-facing text — keep them as is.
-    for (const [k, x] of Object.entries(v)) o[k] = k === '_meta' || k === 'uri' ? x : debrand(x);
-    return o;
-  }
-  return v;
-}
+// Bridge-side access policy, applied BEFORE a call reaches Desktop Commander and to its results.
+// Desktop Commander itself only knows allowedDirectories; it has no "except these folders" rule,
+// so deniedDirectories is enforced here: input paths are resolved (symlinks/junctions included)
+// and refused when they fall inside a denied folder; result lines that mention a denied path are
+// dropped (search hits, recursive listings).
+// The terminal is NOT covered by folder rules (a shell can read anything the user can); commands
+// that name a denied folder are refused as a courtesy, the real control is disabledTools.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Tools the model must never get: they would let it rewrite its own limits, leak telemetry, read the
+// local log of earlier calls, or fetch from the network (PDF export loads remote content).
+export const ALWAYS_HIDDEN = ['set_config_value', 'give_feedback_to_desktop_commander', 'get_usage_stats', 'write_pdf', 'get_recent_tool_calls'];
+// Tools that change files; refused inside readOnlyDirectories (move_file: on either side).
+export const WRITE_TOOLS = ['write_file', 'edit_block', 'move_file', 'create_directory'];
+// Argument names that carry filesystem paths (at any depth): path, paths, file_path, outputPath, directory, source, destination…
+const MAX_DEPTH = 8, MAX_NODES = 5000;
+const PATH_KEYS = /(path|paths|file|files|dir|directory|folder|source|dest|destination)$/i;
+
+// The terminal: off in the access presets Read only / Files (config disabledTools). The bridge always
+// lists these, refused while off, so turning the terminal on needs no restart.
+export const TERMINAL_TOOLS = ['start_process', 'interact_with_process', 'kill_process'];
+const PKG = fileURLToPath(new URL('..', import.meta.url)).replace(/[\\/]+$/, '');
+
+// LOGIC: see critical-logic/bridge.md. Always excluded, whatever the config says: Bridgerator's own
+// settings, key, snapshots and program files — without this the AI could switch any protection off.
+export function ownDenied(env = process.env, home = os.homedir()) {
+  const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+  const local = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+  const npm = path.join(appData, 'npm');
+  return [path.join(appData, 'Bridgerator'), path.join(local, 'Bridgerator'), path.join(npm, 'node_modules', 'bridgerator'),
+    ...['bridgerator', 'bridgerator.cmd', 'bridgerator.ps1'].map((x) => path.join(npm, x)), PKG];
+}
+// "Protect sensitive folders" (config protectSensitive, off by default since 21.10): autostart folder,
+// shell profiles that run code at start, credentials, the whole AppData.
+export function sensitiveDenied(env = process.env, home = os.homedir()) {
+  const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+  const docs = [path.join(home, 'Documents'), ...(env.OneDrive ? [path.join(env.OneDrive, 'Documents')] : [])];
+  return [
+    path.join(appData, 'npm'), path.join(appData, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup'),
+    ...docs.flatMap((d) => [path.join(d, 'WindowsPowerShell'), path.join(d, 'PowerShell')]),
+    ...['.ssh', '.aws', '.azure', '.kube', '.docker', '.gnupg', '.config', '.npmrc', '.git-credentials', '.gitconfig', '.claude', 'AppData'].map((x) => path.join(home, x)),
+  ];
+}
+/** Built-in exclusions: own folders always; sensitive ones unless protectSensitive is false. */
+export function builtinDenied(env = process.env, home = os.homedir(), { protectSensitive = true } = {}) {
+  return [...ownDenied(env, home), ...(protectSensitive ? sensitiveDenied(env, home) : [])];
+}
+
+const expandHome = (p) => (p === '~' || p.startsWith('~/') || p.startsWith('~\\') ? path.join(os.homedir(), p.slice(1)) : p);
+// base: the folder a relative path is resolved against (default: this process's cwd).
+export const norm = (p, base) => path.resolve(base || '.', expandHome(String(p))).replace(/[\\/]+$/, '').toLowerCase();
+
+// Resolve symlinks/junctions on the deepest existing ancestor, like Desktop Commander does.
+export function realish(p, base) {
+  const start = path.resolve(base || '.', expandHome(String(p)));
+  let cur = start;
+  const rest = [];
+  for (;;) {
+    try { return path.join(fs.realpathSync.native(cur), ...rest); } catch { /* walk up */ }
+    const up = path.dirname(cur);
+    if (up === cur) return start;
+    rest.unshift(path.basename(cur));
+    cur = up;
+  }
+}
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// "c:\secret" mentioned as a path (not as the prefix of "c:\secretive"), any slash style / JSON escaping.
+const flat = (s) => String(s).toLowerCase().replace(/[\\/]+/g, '\\');
+const mentionRe = (d) => new RegExp(`${esc(d)}(?![a-z0-9_.\\-])`);
+
+// Quotes and the escape characters of cmd (^) and PowerShell (`) can split a path in a command.
+export const unquote = (s) => String(s).replace(/["'^`]/g, '');
+// 8.3 short names (C:\Users\3C8A~1\…): the deepest existing part is resolved to its long name.
+// Linear: tokens first (one regex over the whole command backtracks quadratically), at most 50 lookups.
+export const longNames = (s) => {
+  let n = 0;
+  return String(s).replace(/[^\s"'|&;<>]+/g, (tok) => (n < 50 && /~\d/.test(tok) ? tok.replace(/[a-z]:[\\/].*$/i, (m) => (/~\d/.test(m) && ++n <= 50 ? realish(m) : m)) : tok));
+};
+
+// Path-like parts of a command: absolute (C:\…, also after = or >) and relative with a backslash
+// (sub\x, .\x, ..\x), quoted or not. Capped (count and length): this runs on every command.
+const MAX_CMD_PATHS = 64;
+export function commandPaths(s) {
+  const out = [];
+  for (const m of String(s).slice(0, 20000).matchAll(/"([^"]{1,1000})"|'([^']{1,1000})'|([^\s"'|&;<>(),]{1,1000})/g)) {
+    let t = (m[1] ?? m[2] ?? m[3]).trim();
+    const d = /[a-z]:[\\/]/i.exec(t);
+    if (d) t = t.slice(d.index);
+    else if (/^[-/]/.test(t) || !t.includes('\\') || t.includes(':')) continue; // a flag, a switch, no folder part, a URL
+    out.push(t);
+    if (out.length >= MAX_CMD_PATHS) break;
+  }
+  return out;
+}
+// What a command WRITES (a heuristic like the other command checks — the terminal is not a boundary):
+// redirect targets (> / >> / 2> file; not 2>&1, >nul, >$null), the destination of a copy (-Destination
+// or the last path), every path after a move / delete / write verb of its own segment (a move empties
+// its source too). Read sources and paths of other segments (a | b ; c && d) are not targets.
+const COPY_VERB = /^(copy|xcopy|robocopy|cp|cpi|copy-item)$/i;
+const WRITE_VERB = /^(set-content|add-content|out-file|new-item|ni|remove-item|ri|rm|del|erase|rd|rmdir|mkdir|md|move|mv|mi|move-item|copy|xcopy|robocopy|cp|cpi|copy-item|ren|rename|rename-item|rni|clear-content|tee-object|tee|expand-archive|compress-archive|icacls|attrib|takeown)(\.exe)?$/i;
+const NUL_TARGET = /^(\$?null|nul|con)$/i;
+const segments = (s) => {
+  const out = [];
+  let cur = '', q = '';
+  for (const ch of String(s).slice(0, 20000)) {
+    if (q) { if (ch === q) q = ''; cur += ch; continue; }
+    if (ch === '"' || ch === "'") { q = ch; cur += ch; continue; }
+    if (ch === ';' || ch === '|' || ch === '&' || ch === '\n' || ch === '\r') { out.push(cur); cur = ''; continue; }
+    cur += ch;
+  }
+  out.push(cur);
+  return out;
+};
+export function writeTargets(s) {
+  const out = [];
+  const text = String(s).slice(0, 20000);
+  for (const m of text.matchAll(/[*\d]?>>?(?!&)\s*("([^"]{1,1000})"|'([^']{1,1000})'|([^\s"'|&;<>()]{1,1000}))/g)) {
+    const t = (m[2] ?? m[3] ?? m[4]).trim();
+    if (t && !NUL_TARGET.test(t)) out.push(t);
+  }
+  for (const seg of segments(text)) {
+    const words = [...seg.matchAll(/[^\s"'(){}=]+/g)];
+    const v = words.find((w) => WRITE_VERB.test(w[0].replace(/^[.&@]+/, '')));
+    if (!v) continue;
+    const rest = seg.slice(v.index + v[0].length).replace(/[*\d]?>>?(?!&)\s*("[^"]*"|'[^']*'|[^\s"'|&;<>()]+)/g, ' ');
+    const named = commandPaths(rest);
+    if (COPY_VERB.test(v[0].replace(/^[.&@]+|\.exe$/gi, ''))) {
+      const d = /(^|\s)-destination\s+("[^"]{1,1000}"|'[^']{1,1000}'|[^\s"']{1,1000})/i.exec(rest);
+      const dest = d ? commandPaths(d[2])[0] : named.at(-1);
+      if (dest) out.push(dest);
+    } else out.push(...named);
+    if (out.length >= MAX_CMD_PATHS) break;
+  }
+  return out.slice(0, MAX_CMD_PATHS);
+}
+/** %VAR%, $env:VAR, ${env:VAR} and a leading ~ expanded with the real environment (case-insensitive names). */
+export function expandVars(s, env = process.env, home = os.homedir()) {
+  const get = (n) => { const k = Object.keys(env).find((x) => x.toLowerCase() === String(n).toLowerCase()); return k ? env[k] : undefined; };
+  return String(s)
+    .replace(/%([A-Za-z_][\w()]*)%/g, (m, n) => get(n) ?? m)
+    .replace(/\$\{env:([^}]+)\}/gi, (m, n) => get(n) ?? m)
+    .replace(/\$env:([A-Za-z_]\w*)/gi, (m, n) => get(n) ?? m)
+    .replace(/(^|[\s"'(=;,])~(?=[\\/]|$|[\s"'])/g, (m, pre) => pre + home);
+}
+
+// cfg.cwd: the folder the ENGINE resolves relative paths against (its working directory): relative
+// arguments are checked where the engine will open them, never against the bridge's own folder.
+export function createPolicy(cfg = {}) {
+  const base = cfg.cwd || process.cwd();
+  // protectSensitive absent = on (callers that don't say); the bridge passes the person's setting.
+  const denied = [...new Set([...builtinDenied(process.env, os.homedir(), { protectSensitive: cfg.protectSensitive !== false }), ...(cfg.deniedDirectories || [])].map((d) => norm(realish(d))))];
+  const res = denied.map(mentionRe);
+  const mentionsDenied = (s) => { const f = flat(s); return res.some((r) => r.test(f)); };
+  const hidden = new Set([...ALWAYS_HIDDEN, ...(cfg.disabledTools || [])]);
+  const inDenied = (p) => {
+    const n = norm(p, base);
+    return denied.find((d) => n === d || n.startsWith(d + path.sep)) || null;
+  };
+  const deniedFor = (p) => inDenied(p) || inDenied(realish(p, base));
+  const readOnly = (cfg.readOnlyDirectories || []).map((d) => norm(realish(d)));
+  const inRo = (n) => readOnly.some((d) => n === d || n.startsWith(d + path.sep));
+  const readOnlyFor = (p) => inRo(norm(p, base)) || inRo(norm(realish(p, base)));
+  // A folder that CONTAINS an excluded / read-only folder (moving or deleting it takes that folder along).
+  const holds = (list, p) => { const a = norm(p, base), b = norm(realish(p, base)); return list.some((d) => d.startsWith(a + path.sep) || d.startsWith(b + path.sep)); };
+
+  // Every path-like string at any depth — iterative, with caps (deep / huge arguments are refused).
+  function pathsIn(args) {
+    const out = [], stack = [[args, '', 0]];
+    let seen = 0;
+    while (stack.length) {
+      const [v, key, depth] = stack.pop();
+      if (++seen > MAX_NODES || depth > MAX_DEPTH) throw new Error('arguments too deeply nested or too large');
+      if (typeof v === 'string') { if (v && PATH_KEYS.test(key)) out.push(v); }
+      else if (Array.isArray(v)) for (const x of v) stack.push([x, key, depth + 1]);
+      else if (v && typeof v === 'object') for (const [k, x] of Object.entries(v)) stack.push([x, k, depth + 1]);
+    }
+    return out;
+  }
+
+  return {
+    denied,
+    visible: (tool) => !hidden.has(tool.name),
+    // → null when allowed, otherwise the refusal text returned to the model.
+    check(name, args) {
+      if (hidden.has(name)) return TERMINAL_TOOLS.includes(name) ? 'The terminal is off on this PC (access preset Read only or Files). The person can switch to Full in Bridgerator → Safety, or you can ask with bridgerator_settings.' : `Tool "${name}" is disabled on this computer.`;
+      if (name === 'read_file' && args?.isUrl) return 'Reading URLs is disabled on this computer.';
+      let paths;
+      try { paths = pathsIn(args); } catch (e) { return `Refused by Bridgerator: ${e.message}.`; }
+      for (const p of paths) {
+        // UNC / device paths (\\server\share, \\?\, \\.\): network shares and raw devices are out of scope.
+        if (/^[\\/]{2}/.test(p.trim())) return `Access denied by Bridgerator: network and device paths ("${p}") are not allowed.`;
+        if (deniedFor(p)) return `Access denied by Bridgerator: "${p}" is inside an excluded folder.`;
+        if (WRITE_TOOLS.includes(name) && readOnlyFor(p)) return `Access denied by Bridgerator: "${p}" is in a read-only folder — files there can be read, not changed.`;
+        if (WRITE_TOOLS.includes(name) && holds(denied, p)) return `Access denied by Bridgerator: "${p}" contains an excluded folder.`;
+        if (WRITE_TOOLS.includes(name) && holds(readOnly, p)) return `Access denied by Bridgerator: "${p}" contains a read-only folder.`;
+        // A hard link is the same file under another name (maybe inside an excluded folder): no writes.
+        if (WRITE_TOOLS.includes(name)) { try { if (fs.lstatSync(path.resolve(base, expandHome(p))).nlink > 1) return `Access denied by Bridgerator: "${p}" is a hard-linked file — it can't be changed through Bridgerator.`; } catch { /* doesn't exist yet */ } }
+      }
+      for (const k of ['command', 'input']) {
+        if (typeof args?.[k] !== 'string') continue;
+        // Checked as written AND with variables expanded (%APPDATA%, $env:APPDATA, ${env:APPDATA}, ~),
+        // with quotes / escape characters removed ("%USERPROFILE%"\.ssh, .s^sh, .`ssh) and 8.3 short
+        // names of existing folders made long (C:\PROGRA~1).
+        const u = unquote(args[k]);
+        const texts = [args[k], expandVars(args[k]), u, expandVars(u)];
+        texts.push(...texts.map(longNames));
+        if (texts.some(mentionsDenied)) return `Access denied by Bridgerator: the ${k} refers to an excluded folder.`;
+        // Paths in the command resolved like the file tools do (relative → the terminal's folder,
+        // junctions / symbolic links → their target): a link to an excluded folder is refused too.
+        const named = [...new Set([...commandPaths(texts[1]), ...commandPaths(texts[3])])].slice(0, MAX_CMD_PATHS);
+        // UNC / device paths are refused like path arguments — never resolved here (a lookup on a
+        // network path blocks the bridge's main thread).
+        const unc = named.find((p) => /^[\\/]{2}[^\\/]+[\\/]/.test(p));
+        if (unc) return `Access denied by Bridgerator: network and device paths ("${unc}") are not allowed.`;
+        if (named.some((p) => deniedFor(p))) return `Access denied by Bridgerator: the ${k} refers to an excluded folder.`;
+        // Read-only folders, for commands that change files (a courtesy: a script can still write there).
+        // Only what the command writes counts (as written with its quotes and as unquoted).
+        if (readOnly.length) {
+          const targets = [...new Set([...writeTargets(texts[1]), ...writeTargets(texts[3])])].filter((p) => !/^[\\/]{2}/.test(p));
+          if (targets.some((p) => readOnlyFor(p))) return `Access denied by Bridgerator: the ${k} would change a read-only folder — files there can be read, not changed.`;
+        }
+        // Courtesy, like the folder check (the terminal itself is not a boundary): anything about
+        // Bridgerator itself — its commands, files, processes — is for the person at the PC.
+        if (texts.some((x) => /\bbridgerator\b/i.test(x))) return 'Commands about Bridgerator itself (its settings, files or processes) can only be run by the person at this PC. Use request_confirm_off to ask for confirmations to be turned off.';
+      }
+      return null;
+    },
+    /** Refusal text when Bridgerator itself may not remove / restore this path (excluded, read-only, network), else null. */
+    writable(p) {
+      if (/^[\\/]{2}/.test(String(p).trim())) return `Access denied by Bridgerator: network and device paths ("${p}") are not allowed.`;
+      if (deniedFor(p)) return `Access denied by Bridgerator: "${p}" is inside an excluded folder.`;
+      if (readOnlyFor(p)) return `Access denied by Bridgerator: "${p}" is in a read-only folder.`;
+      if (holds(denied, p)) return `Access denied by Bridgerator: "${p}" contains an excluded folder.`;
+      if (holds(readOnly, p)) return `Access denied by Bridgerator: "${p}" contains a read-only folder.`;
+      return null;
+    },
+    // Drop result lines that reveal anything inside a denied folder. `args` lets a listing of a
+    // parent folder hide the excluded child, whose entries are printed relative to that parent.
+    filter(result, name, args) {
+      if (!denied.length || !result || !Array.isArray(result.content)) return result;
+      const rel = [];
+      if (name === 'list_directory' && typeof args?.path === 'string') {
+        const at = norm(realish(args.path, base));
+        for (const d of denied) if (d.startsWith(at + path.sep)) rel.push(new RegExp(`^${esc(d.slice(at.length + 1))}(?![a-z0-9_.\\-])`));
+      }
+      const leaks = (line) => mentionsDenied(line) || rel.some((r) => r.test(flat(line).trim().replace(/^\[(dir|file)\]\s*/, '')));
+      let dropped = 0;
+      const content = result.content.map((c) => {
+        if (c?.type !== 'text' || typeof c.text !== 'string') return c;
+        const lines = c.text.split(/\r?\n/);
+        const kept = lines.filter((ln) => !leaks(ln));
+        dropped += lines.length - kept.length;
+        return { ...c, text: kept.join('\n') };
+      });
+      if (dropped) content.push({ type: 'text', text: `[Bridgerator: ${dropped} line(s) hidden — excluded folder]` });
+      return { ...result, content };
+    },
+  };
+}
+
+// The bundled engine's own name and links are not shown to the user: tool titles/descriptions and
+// widget HTML say Bridgerator. Tool RESULTS are never rewritten (they are the user's own data).
+const BRAND = [[/"DC: \.\.\." or /g, ''], [/Desktop ?Commander/g, 'Bridgerator'], [/https?:\/\/(www\.)?desktopcommander\.app[^\s"'\)<]*/g, 'https://bridgerator.recondeck.com']];
+export function debrand(v) {
+  if (typeof v === 'string') return BRAND.reduce((s, [re, to]) => s.replace(re, to), v);
+  if (Array.isArray(v)) return v.map(debrand);
+  if (v && typeof v === 'object') {
+    const o = {};
+    // _meta keys (ui:// template URIs) are identifiers, not user-facing text — keep them as is.
+    for (const [k, x] of Object.entries(v)) o[k] = k === '_meta' || k === 'uri' ? x : debrand(x);
+    return o;
+  }
+  return v;
+}
+
+// Two results are the engine's own text, not user data: the prompt catalog (get_prompts says
+// "Desktop Commander Prompt Categories") and get_config, whose `version` is the engine's and is
+// shown as "Bridgerator version" — replaced by the bridge's own version.
+export function debrandResult(name, result, version) {
+  if (!result || typeof result !== 'object') return result;
+  if (name === 'get_prompts') return debrand(result);
+  const sc = result.structuredContent, engine = sc?.config?.version;
+  if (name !== 'get_config' || typeof engine !== 'string') return result;
+  const label = `"version": ${JSON.stringify(engine)}`;
+  const content = Array.isArray(result.content)
+    ? result.content.map((c) => (c?.type === 'text' && typeof c.text === 'string' ? { ...c, text: c.text.replace(label, `"version": ${JSON.stringify(version)}`) } : c))
+    : result.content;
+  return { ...result, content, structuredContent: { ...sc, config: { ...sc.config, version } } };
+}

package/src/queue.mjs

@@ -0,0 +1,194 @@
+// Task queue (checklist) on this PC: the person adds steps in the Bridgerator window, ChatGPT works
+// through them with the queue_* tools. Stored only here (%APPDATA%\Bridgerator\queue.json, inside
+// the always-excluded folder); never sent to the server. Tools read/write only this list.
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { writeAtomic } from './confirm.mjs';
+
+export const STATUSES = ['todo', 'doing', 'done', 'failed', 'skipped'];
+const MAX_ITEMS = 500, MAX_TITLE = 200, MAX_DETAILS = 4000, MAX_NOTE = 1000, MAX_PATHS = 20;
+const RULE = 'The usual loop: queue_next, do the task, queue_update with done / failed / skipped and a short note, then the next one until the queue is empty or the person stops. resultPath set: write the result to that file. from set: another AI added it and reads queue_list.';
+const MAX_FROM = 80, MAX_RESULT_PATH = 1000;
+export const STALE_MS = 30 * 60 * 1000;   // "doing" with no update for this long: another chat gave up
+const ID = { type: 'string', description: 'item id' };
+const STR = (n) => ({ type: 'string', maxLength: n });
+const PATHS = { type: 'array', maxItems: MAX_PATHS, items: STR(1000) };
+// AI ↔ AI hand-off (another AI adds tasks for ChatGPT): who added it, and the file for the result. Optional; old items have neither.
+const HANDOFF = { from: { type: 'string', maxLength: MAX_FROM, description: 'Who adds the task when another AI hands work over, e.g. "Claude Code".' }, resultPath: { type: 'string', maxLength: MAX_RESULT_PATH, description: 'Full path of the file where the result should be written.' } };
+
+export const QUEUE_TOOL_DEFS = [
+  { name: 'queue_list', description: `List the task queue the person keeps on this PC (a checklist of things to do): counts and items (id, title, status, note, worker, updatedAt, from, resultPath), optionally only one status.`, inputSchema: { type: 'object', additionalProperties: false, properties: { status: { type: 'string', enum: STATUSES } } } },
+  { name: 'queue_next', description: `Take the next item of the task queue: returns the first "todo" item and marks it "doing" (nothing when the queue is empty). An item left "doing" for 30 minutes without an update (another chat stopped) is returned first, with resumed: true. Several chats can work through one queue at once; each call gets a different item. Pass worker = a short name for this chat (e.g. its title) so the person sees who is on it. ${RULE}`, inputSchema: { type: 'object', additionalProperties: false, properties: { worker: STR(80) } } },
+  { name: 'queue_update', description: `Set an item's status (doing / done / failed / skipped / todo) with a short result note.`, inputSchema: { type: 'object', additionalProperties: false, required: ['id', 'status'], properties: { id: ID, status: { type: 'string', enum: STATUSES }, note: STR(MAX_NOTE) } } },
+  { name: 'queue_add', description: `Add steps to the task queue (e.g. when planning a bigger job with the person): one { title, details?, paths?, from?, resultPath? } or items: [...] (1–100). Another AI handing work to ChatGPT sets from (its name) and resultPath (a file for the result), then reads the outcome with queue_list.`, inputSchema: { type: 'object', additionalProperties: false, properties: { title: STR(MAX_TITLE), details: STR(MAX_DETAILS), paths: PATHS, ...HANDOFF, items: { type: 'array', minItems: 1, maxItems: 100, items: { type: 'object', additionalProperties: false, required: ['title'], properties: { title: STR(MAX_TITLE), details: STR(MAX_DETAILS), paths: PATHS, ...HANDOFF } } } } } },
+  { name: 'queue_clear', description: 'Remove finished items from the task queue: status done, failed or skipped. status "all" removes every item and needs the person\'s OK on the PC.', inputSchema: { type: 'object', additionalProperties: false, properties: { status: { type: 'string', enum: ['done', 'failed', 'skipped', 'all'] } } } },
+  { name: 'queue_edit', description: 'Change the title, details, paths or result file of a queue item.', inputSchema: { type: 'object', additionalProperties: false, required: ['id'], properties: { id: ID, title: STR(MAX_TITLE), details: STR(MAX_DETAILS), paths: PATHS, resultPath: HANDOFF.resultPath } } },
+  { name: 'queue_reorder', description: 'Put queue items in a new order: ids first, in this order; the rest keep their order after them.', inputSchema: { type: 'object', additionalProperties: false, required: ['ids'], properties: { ids: { type: 'array', maxItems: MAX_ITEMS, items: ID } } } },
+];
+export const QUEUE_TOOL_NAMES = new Set(QUEUE_TOOL_DEFS.map((t) => t.name));
+
+const str = (v, n, name, required) => {
+  if (v === undefined || v === null) { if (required) throw new Error(`${name} is required`); return undefined; }
+  if (typeof v !== 'string') throw new Error(`${name} must be text`);
+  const t = v.trim();
+  if (required && !t) throw new Error(`${name} is required`);
+  if (t.length > n) throw new Error(`${name} is longer than ${n} characters`);
+  return t;
+};
+const paths = (v) => {
+  if (v === undefined) return undefined;
+  if (!Array.isArray(v) || v.length > MAX_PATHS || v.some((p) => typeof p !== 'string' || p.length > 1000)) throw new Error(`paths must be a list of at most ${MAX_PATHS} paths`);
+  return v.map((p) => p.trim()).filter(Boolean);
+};
+const fromOf = (v) => { const t = str(v, MAX_FROM, 'from'); if (t && /[\u0000-\u001f]/.test(t)) throw new Error('from must be a short name on one line'); return t || undefined; };
+const resultPathOf = (v) => { const t = str(v, MAX_RESULT_PATH, 'resultPath'); if (t && !/^[a-z]:[\\/]/i.test(t)) throw new Error('resultPath must be a full path like C:\\Users\\Name\\Documents\\result.md'); return t || undefined; };
+const handoff = (x) => { const f = fromOf(x?.from), r = resultPathOf(x?.resultPath); return { ...(f ? { from: f } : {}), ...(r ? { resultPath: r } : {}) }; };
+
+export function createQueue(file, { now = () => new Date().toISOString(), onChange = () => {} } = {}) {
+  let items = [], unreadable = null;
+  // Missing file = empty queue. A file that can't be READ (locked, no access) is never overwritten: saves
+  // fail until a restart reads it. A file that can't be PARSED — or has the wrong shape, or items that
+  // are dropped (no id / title, unknown status) — is kept as queue.json.broken-<content hash> before any
+  // save: once per distinct broken content (the same file at every start is not copied again).
+  let raw = null;
+  const keepCopy = () => {
+    const copy = `${file}.broken-${crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16)}`;
+    try { fs.copyFileSync(file, copy, fs.constants.COPYFILE_EXCL); } catch (e) { if (e.code !== 'EEXIST') unreadable = 'BROKEN'; }
+  };
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (e) { if (e.code !== 'ENOENT') unreadable = e.code || e.message; }
+  if (raw !== null) {
+    try {
+      const j = JSON.parse(raw.replace(/^/, ''));
+      if (Array.isArray(j?.items)) {
+        items = j.items.filter((x) => x && typeof x === 'object' && typeof x.id === 'string' && x.id && typeof x.title === 'string' && STATUSES.includes(x.status))
+          .map((x, i) => ({ ...x, order: Number.isFinite(x.order) ? x.order : i + 1 }));
+        if (items.length !== j.items.length) keepCopy();
+      } else keepCopy();
+    } catch { keepCopy(); }
+  }
+  // Atomic: write a temp file, then rename over queue.json — a crash or a parallel write never leaves
+  // half a file. (Calls run in one process, so the read-modify-write steps never interleave.)
+  const save = () => {
+    if (unreadable) throw new Error(`queue.json could not be read (${unreadable}); restart Bridgerator to load it — nothing was changed`);
+    if (deferSave) return;
+    writeAtomic(file, JSON.stringify({ items }, null, 2)); onChange();
+  };
+  // Every change is all or nothing: a validation or save error leaves the queue as it was.
+  const commit = (fn) => {
+    const before = structuredClone(items);
+    try { return fn(); } catch (e) { items = before; throw e; }
+  };
+  // Several items in one change: ONE save at the end (a failure half-way leaves queue.json as it was).
+  let deferSave = false;
+  const many = (fn) => commit(() => { deferSave = true; let r; try { r = fn(); } finally { deferSave = false; } save(); return r; });
+  const sorted = () => [...items].sort((a, b) => a.order - b.order);
+  const get = (id) => { const it = items.find((x) => x.id === id); if (!it) throw new Error(`no queue item ${id}`); return it; };
+  const renumber = (list) => list.forEach((x, i) => { x.order = i + 1; });
+
+  return {
+    list: (status) => {
+      if (status !== undefined && !STATUSES.includes(status)) throw new Error(`status must be one of ${STATUSES.join(', ')}`);
+      return sorted().filter((x) => !status || x.status === status);
+    },
+    counts: () => Object.fromEntries(STATUSES.map((s) => [s, items.filter((x) => x.status === s).length])),
+    add(x = {}) { return commit(() => this.add0(x)); },
+    add0({ title, details, paths: p, from, resultPath } = {}) {
+      if (items.length >= MAX_ITEMS) throw new Error(`the queue is full (${MAX_ITEMS} items)`);
+      const t = now();
+      const it = { id: crypto.randomUUID().slice(0, 8), title: str(title, MAX_TITLE, 'title', true), ...(details !== undefined ? { details: str(details, MAX_DETAILS, 'details') } : {}), ...(p !== undefined ? { paths: paths(p) } : {}), ...handoff({ from, resultPath }), status: 'todo', order: (Math.max(0, ...items.map((x) => x.order)) + 1), createdAt: t, updatedAt: t };
+      items.push(it); save(); return it;
+    },
+    // Synchronous take: parallel chats calling queue_next never get the same item.
+    next({ worker } = {}) { return commit(() => {
+      const w = str(worker, 80, 'worker');
+      const t = Date.parse(now());
+      const stale = sorted().find((x) => x.status === 'doing' && t - Date.parse(x.updatedAt) >= STALE_MS);
+      const it = stale || sorted().find((x) => x.status === 'todo');
+      if (!it) return null;
+      if (stale) it.resumedFrom = it.worker || 'another chat';
+      it.status = 'doing'; it.updatedAt = now();
+      if (w) it.worker = w; else delete it.worker;
+      save(); return stale ? { ...it, resumed: true } : it;
+    }); },
+    update({ id, status, note } = {}) { return commit(() => {
+      const it = get(str(id, 40, 'id', true));
+      if (!STATUSES.includes(status)) throw new Error(`status must be one of ${STATUSES.join(', ')}`);
+      const n = note !== undefined ? str(note, MAX_NOTE, 'note') : undefined;
+      it.status = status; it.updatedAt = now();
+      if (note !== undefined) it.note = n;
+      if (['done', 'failed', 'skipped'].includes(status)) it.doneAt = it.updatedAt; else delete it.doneAt;
+      if (status !== 'doing') delete it.worker;
+      save(); return it;
+    }); },
+    edit({ id, title, details, paths: p, resultPath } = {}) { return commit(() => {
+      const it = get(str(id, 40, 'id', true));
+      // Everything is checked first, then changed.
+      const t = title !== undefined ? str(title, MAX_TITLE, 'title', true) : undefined;
+      const d = details !== undefined ? str(details, MAX_DETAILS, 'details') : undefined;
+      const ps = p !== undefined ? paths(p) : undefined;
+      const r = resultPath !== undefined ? resultPathOf(resultPath) : undefined;
+      if (title !== undefined) it.title = t;
+      if (details !== undefined) it.details = d;
+      if (p !== undefined) it.paths = ps;
+      if (resultPath !== undefined) { if (r) it.resultPath = r; else delete it.resultPath; }
+      it.updatedAt = now(); save(); return it;
+    }); },
+    reorder({ ids } = {}) { return commit(() => {
+      if (!Array.isArray(ids)) throw new Error('ids must be a list');
+      const first = ids.map((id) => get(String(id)));
+      renumber([...new Set(first), ...sorted().filter((x) => !first.includes(x))]);
+      save(); return sorted();
+    }); },
+    remove({ id } = {}) { return commit(() => { const it = get(String(id)); items = items.filter((x) => x !== it); renumber(sorted()); save(); return it; }); },
+    // Undo of a delete in the window: the item goes back at its old place.
+    restore(x = {}) { return commit(() => this.restore0(x)); },
+    restore0({ item } = {}) {
+      if (!item || typeof item !== 'object' || typeof item.id !== 'string' || items.some((x) => x.id === item.id)) throw new Error('nothing to restore');
+      if (!STATUSES.includes(item.status)) throw new Error('bad item');
+      const it = { ...item, title: str(item.title, MAX_TITLE, 'title', true) };
+      const list = sorted(); list.splice(Math.max(0, Math.min(list.length, (Number(item.order) || 1) - 1)), 0, it);
+      items = list; renumber(items); save(); return it;
+    },
+    clearFinished() { return commit(() => { items = items.filter((x) => !['done', 'failed', 'skipped'].includes(x.status)); renumber(sorted()); save(); return true; }); },
+    // status: done | failed | skipped | finished (all three) | all → the removed items (for Undo).
+    clear({ status = 'finished' } = {}) {
+      const pick = { done: ['done'], failed: ['failed'], skipped: ['skipped'], finished: ['done', 'failed', 'skipped'], 'failed+skipped': ['failed', 'skipped'], all: STATUSES }[status];
+      if (!pick) throw new Error('status must be done, failed, skipped or all');
+      return commit(() => {
+        const gone = sorted().filter((x) => pick.includes(x.status));
+        items = items.filter((x) => !gone.includes(x)); renumber(sorted()); save();
+        return gone;
+      });
+    },
+    restoreMany({ items: list } = {}) {
+      if (!Array.isArray(list)) throw new Error('nothing to restore');
+      return many(() => { for (const it of [...list].sort((a, b) => a.order - b.order)) this.restore0({ item: it }); return sorted(); });
+    },
+    addMany(list) {
+      if (!Array.isArray(list) || !list.length || list.length > 100) throw new Error('items must be a list of 1–100 tasks');
+      if (items.length + list.length > MAX_ITEMS) throw new Error(`the queue would be over ${MAX_ITEMS} items`);
+      // All or nothing: a half-added list would be added twice when the chat retries.
+      list.forEach((x, i) => { str(x?.title, MAX_TITLE, `items[${i}].title`, true); str(x?.details, MAX_DETAILS, `items[${i}].details`); paths(x?.paths); try { handoff(x); } catch (e) { throw new Error(`items[${i}]: ${e.message}`); } });
+      return many(() => list.map((x) => this.add0(x)));
+    },
+  };
+}
+
+/** queue_* tool call → MCP result. */
+export function queueTool(q, name, args = {}) {
+  const ok = (v) => ({ content: [{ type: 'text', text: JSON.stringify(v, null, 2) }] });
+  try {
+    switch (name) {
+      case 'queue_list': return ok({ counts: q.counts(), items: q.list(args.status).map(({ id, title, status, note, worker, updatedAt, details, paths, from, resultPath }) => ({ id, title, status, ...(note ? { note } : {}), ...(worker ? { worker } : {}), updatedAt, ...(details ? { details } : {}), ...(paths ? { paths } : {}), ...(from ? { from } : {}), ...(resultPath ? { resultPath } : {}) })) });
+      case 'queue_next': { const it = q.next(args); return ok(it ? { item: it } : { item: null, message: 'The queue is empty — tell the person and stop.' }); }
+      case 'queue_update': return ok({ item: q.update(args) });
+      case 'queue_add': return args.items ? ok({ items: q.addMany(args.items) }) : ok({ item: q.add(args) });
+      case 'queue_clear': { if (args.status === 'all') throw new Error('clearing every item needs the person\'s OK'); const gone = q.clear({ status: args.status || 'finished' }); return ok({ removed: gone.length, counts: q.counts() }); }
+      case 'queue_edit': return ok({ item: q.edit(args) });
+      case 'queue_reorder': return ok({ items: q.reorder(args) });
+      default: return { content: [{ type: 'text', text: `unknown queue tool ${name}` }], isError: true };
+    }
+  } catch (e) {
+    return { content: [{ type: 'text', text: `Queue: ${e.message}` }], isError: true };
+  }
+}