neuralos 3.2.18 → 3.3.0

package/bin/gybackend.cjs

@@ -15957,7 +15957,11 @@ function resolveHistoryStorageDir() {
   if (overrideDir) {
     return import_node_path4.default.resolve(overrideDir);
   }
-  return import_node_path4.default.join(process.cwd(), ".gybackend-data");
+  const gybackendDataDir = (process.env.GYBACKEND_DATA_DIR || "").trim();
+  if (gybackendDataDir) {
+    return import_node_path4.default.resolve(gybackendDataDir);
+  }
+  return import_node_path4.default.join(import_node_os.default.homedir(), ".gybackend-data");
 }
 function ensureHistoryStorageDir(baseDir = resolveHistoryStorageDir()) {
   import_node_fs2.default.mkdirSync(baseDir, { recursive: true });
@@ -15978,11 +15982,12 @@ function resolveHistoryStoragePaths(baseDir = resolveHistoryStorageDir()) {
     )
   };
 }
-var import_node_fs2, import_node_path4, HISTORY_SQLITE_FILE_NAME, LEGACY_CHAT_HISTORY_FILE_NAME, LEGACY_UI_HISTORY_FILE_NAME;
+var import_node_fs2, import_node_os, import_node_path4, HISTORY_SQLITE_FILE_NAME, LEGACY_CHAT_HISTORY_FILE_NAME, LEGACY_UI_HISTORY_FILE_NAME;
 var init_historyStoragePaths = __esm({
   "../../packages/backend/src/services/history/historyStoragePaths.ts"() {
     "use strict";
     import_node_fs2 = __toESM(require("node:fs"), 1);
+    import_node_os = __toESM(require("node:os"), 1);
     import_node_path4 = __toESM(require("node:path"), 1);
     HISTORY_SQLITE_FILE_NAME = "gyshell-history.sqlite";
     LEGACY_CHAT_HISTORY_FILE_NAME = "gyshell-chat-history.json";
@@ -27263,11 +27268,11 @@ var require_pdf_worker = __commonJS({
                     var nameTree = new NameTree(nameTreeRef, xref);
                     var names = nameTree.getAll();
                     for (var name in names) {
-                      var fs22 = new FileSpec(names[name], xref);
+                      var fs23 = new FileSpec(names[name], xref);
                       if (!attachments) {
                         attachments = /* @__PURE__ */ Object.create(null);
                       }
-                      attachments[(0, _util.stringToPDFString)(name)] = fs22.serializable;
+                      attachments[(0, _util.stringToPDFString)(name)] = fs23.serializable;
                     }
                   }
                   return (0, _util.shadow)(this, "attachments", attachments);
@@ -77119,7 +77124,7 @@ var require_pdf = __commonJS({
                 throw new TypeError("Cannot call a class as a function");
               }
             }
-            var fs22 = require("fs");
+            var fs23 = require("fs");
             var http2 = require("http");
             var https2 = require("https");
             var url2 = require("url");
@@ -77453,7 +77458,7 @@ var require_pdf = __commonJS({
                 _classCallCheck(this, PDFNodeStreamFsFullReader2);
                 var _this7 = _possibleConstructorReturn(this, (PDFNodeStreamFsFullReader2.__proto__ || Object.getPrototypeOf(PDFNodeStreamFsFullReader2)).call(this, stream));
                 var path32 = decodeURI(_this7._url.path);
-                fs22.lstat(path32, function(error40, stat) {
+                fs23.lstat(path32, function(error40, stat) {
                   if (error40) {
                     _this7._errored = true;
                     _this7._reason = error40;
@@ -77461,7 +77466,7 @@ var require_pdf = __commonJS({
                     return;
                   }
                   _this7._contentLength = stat.size;
-                  _this7._setReadableStream(fs22.createReadStream(path32));
+                  _this7._setReadableStream(fs23.createReadStream(path32));
                   _this7._headersCapability.resolve();
                 });
                 return _this7;
@@ -77473,7 +77478,7 @@ var require_pdf = __commonJS({
               function PDFNodeStreamFsRangeReader2(stream, start, end) {
                 _classCallCheck(this, PDFNodeStreamFsRangeReader2);
                 var _this8 = _possibleConstructorReturn(this, (PDFNodeStreamFsRangeReader2.__proto__ || Object.getPrototypeOf(PDFNodeStreamFsRangeReader2)).call(this, stream));
-                _this8._setReadableStream(fs22.createReadStream(decodeURI(_this8._url.path), {
+                _this8._setReadableStream(fs23.createReadStream(decodeURI(_this8._url.path), {
                   start,
                   end: end - 1
                 }));
@@ -89467,11 +89472,11 @@ var require_pdf_worker2 = __commonJS({
                     var nameTree = new NameTree(nameTreeRef, xref);
                     var names = nameTree.getAll();
                     for (var name in names) {
-                      var fs22 = new FileSpec(names[name], xref);
+                      var fs23 = new FileSpec(names[name], xref);
                       if (!attachments) {
                         attachments = /* @__PURE__ */ Object.create(null);
                       }
-                      attachments[(0, _util.stringToPDFString)(name)] = fs22.serializable;
+                      attachments[(0, _util.stringToPDFString)(name)] = fs23.serializable;
                     }
                   }
                   return (0, _util.shadow)(this, "attachments", attachments);
@@ -138955,7 +138960,7 @@ var require_pdf2 = __commonJS({
                 throw new TypeError("Cannot call a class as a function");
               }
             }
-            var fs22 = require("fs");
+            var fs23 = require("fs");
             var http2 = require("http");
             var https2 = require("https");
             var url2 = require("url");
@@ -139289,7 +139294,7 @@ var require_pdf2 = __commonJS({
                 _classCallCheck(this, PDFNodeStreamFsFullReader2);
                 var _this7 = _possibleConstructorReturn(this, (PDFNodeStreamFsFullReader2.__proto__ || Object.getPrototypeOf(PDFNodeStreamFsFullReader2)).call(this, stream));
                 var path32 = decodeURI(_this7._url.path);
-                fs22.lstat(path32, function(error40, stat) {
+                fs23.lstat(path32, function(error40, stat) {
                   if (error40) {
                     _this7._errored = true;
                     _this7._reason = error40;
@@ -139297,7 +139302,7 @@ var require_pdf2 = __commonJS({
                     return;
                   }
                   _this7._contentLength = stat.size;
-                  _this7._setReadableStream(fs22.createReadStream(path32));
+                  _this7._setReadableStream(fs23.createReadStream(path32));
                   _this7._headersCapability.resolve();
                 });
                 return _this7;
@@ -139309,7 +139314,7 @@ var require_pdf2 = __commonJS({
               function PDFNodeStreamFsRangeReader2(stream, start, end) {
                 _classCallCheck(this, PDFNodeStreamFsRangeReader2);
                 var _this8 = _possibleConstructorReturn(this, (PDFNodeStreamFsRangeReader2.__proto__ || Object.getPrototypeOf(PDFNodeStreamFsRangeReader2)).call(this, stream));
-                _this8._setReadableStream(fs22.createReadStream(decodeURI(_this8._url.path), {
+                _this8._setReadableStream(fs23.createReadStream(decodeURI(_this8._url.path), {
                   start,
                   end: end - 1
                 }));
@@ -161693,11 +161698,11 @@ var require_pdf_worker3 = __commonJS({
                     var nameTree = new NameTree(nameTreeRef, xref);
                     var names = nameTree.getAll();
                     for (var name in names) {
-                      var fs22 = new FileSpec(names[name], xref);
+                      var fs23 = new FileSpec(names[name], xref);
                       if (!attachments) {
                         attachments = /* @__PURE__ */ Object.create(null);
                       }
-                      attachments[(0, _util.stringToPDFString)(name)] = fs22.serializable;
+                      attachments[(0, _util.stringToPDFString)(name)] = fs23.serializable;
                     }
                   }
                   return (0, _util.shadow)(this, "attachments", attachments);
@@ -203578,11 +203583,11 @@ var require_pdf_worker4 = __commonJS({
                     var nameTree = new NameTree(nameTreeRef, xref);
                     var names = nameTree.getAll();
                     for (var name in names) {
-                      var fs22 = new FileSpec(names[name], xref);
+                      var fs23 = new FileSpec(names[name], xref);
                       if (!attachments) {
                         attachments = /* @__PURE__ */ Object.create(null);
                       }
-                      attachments[(0, _util.stringToPDFString)(name)] = fs22.serializable;
+                      attachments[(0, _util.stringToPDFString)(name)] = fs23.serializable;
                     }
                   }
                   return (0, _util.shadow)(this, "attachments", attachments);
@@ -253965,7 +253970,7 @@ var require_pdf4 = __commonJS({
                 throw new TypeError("Cannot call a class as a function");
               }
             }
-            var fs22 = require("fs");
+            var fs23 = require("fs");
             var http2 = require("http");
             var https2 = require("https");
             var url2 = require("url");
@@ -254323,7 +254328,7 @@ var require_pdf4 = __commonJS({
                 if (fileUriRegex.test(_this7._url.href)) {
                   path32 = path32.replace(/^\//, "");
                 }
-                fs22.lstat(path32, function(error40, stat) {
+                fs23.lstat(path32, function(error40, stat) {
                   if (error40) {
                     _this7._errored = true;
                     _this7._reason = error40;
@@ -254331,7 +254336,7 @@ var require_pdf4 = __commonJS({
                     return;
                   }
                   _this7._contentLength = stat.size;
-                  _this7._setReadableStream(fs22.createReadStream(path32));
+                  _this7._setReadableStream(fs23.createReadStream(path32));
                   _this7._headersCapability.resolve();
                 });
                 return _this7;
@@ -254347,7 +254352,7 @@ var require_pdf4 = __commonJS({
                 if (fileUriRegex.test(_this8._url.href)) {
                   path32 = path32.replace(/^\//, "");
                 }
-                _this8._setReadableStream(fs22.createReadStream(path32, {
+                _this8._setReadableStream(fs23.createReadStream(path32, {
                   start,
                   end: end - 1
                 }));
@@ -255452,6 +255457,105 @@ var require_pdf_parse2 = __commonJS({
   }
 });
 
+// ../../packages/backend/src/services/AgentHelper/utils/subAgent.ts
+var subAgent_exports = {};
+__export(subAgent_exports, {
+  renderSubAgentSummary: () => renderSubAgentSummary,
+  runSubAgents: () => runSubAgents,
+  validateSubAgentSpec: () => validateSubAgentSpec
+});
+function validateSubAgentSpec(spec) {
+  if (!spec || typeof spec !== "object") return { ok: false, error: "spec must be an object" };
+  const s = spec;
+  if (!Array.isArray(s.tasks) || s.tasks.length === 0) {
+    return { ok: false, error: "tasks must be a non-empty array" };
+  }
+  if (s.tasks.length > 20) {
+    return { ok: false, error: `too many tasks (${s.tasks.length}); max 20 per fan-out` };
+  }
+  for (let i = 0; i < s.tasks.length; i++) {
+    const t = s.tasks[i];
+    if (!t || typeof t !== "object") return { ok: false, error: `task ${i + 1} must be an object` };
+    if (typeof t.prompt !== "string" || !t.prompt.trim()) {
+      return { ok: false, error: `task ${i + 1} needs a non-empty prompt` };
+    }
+    if (t.label !== void 0 && typeof t.label !== "string") {
+      return { ok: false, error: `task ${i + 1} label must be a string` };
+    }
+  }
+  if (s.maxConcurrent !== void 0 && (!Number.isFinite(s.maxConcurrent) || s.maxConcurrent < 1)) {
+    return { ok: false, error: "maxConcurrent must be >= 1" };
+  }
+  if (s.timeoutMs !== void 0 && (!Number.isFinite(s.timeoutMs) || s.timeoutMs < 1e3)) {
+    return { ok: false, error: "timeoutMs must be >= 1000" };
+  }
+  return { ok: true };
+}
+async function runWithTimeout(task2, run, timeoutMs) {
+  const started = Date.now();
+  return await new Promise((resolve2) => {
+    let settled = false;
+    const finish = (r) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve2(r);
+      }
+    };
+    const timer = setTimeout(() => {
+      finish({ label: task2.label, ok: false, error: "timed out", durationMs: Date.now() - started, timedOut: true });
+    }, timeoutMs);
+    run(task2).then((output) => finish({ label: task2.label, ok: true, output, durationMs: Date.now() - started, timedOut: false })).catch((e) => finish({
+      label: task2.label,
+      ok: false,
+      error: e instanceof Error ? e.message : String(e),
+      durationMs: Date.now() - started,
+      timedOut: false
+    }));
+  });
+}
+async function runSubAgents(spec, run) {
+  const maxConcurrent = Math.max(1, spec.maxConcurrent ?? 3);
+  const timeoutMs = spec.timeoutMs ?? 3e5;
+  const results = [];
+  for (let i = 0; i < spec.tasks.length; i += maxConcurrent) {
+    const batch = spec.tasks.slice(i, i + maxConcurrent);
+    const batchResults = await Promise.all(
+      batch.map((t) => runWithTimeout(t, run, timeoutMs))
+    );
+    results.push(...batchResults);
+  }
+  const succeeded = results.filter((r) => r.ok).length;
+  return {
+    ok: succeeded === results.length,
+    total: results.length,
+    succeeded,
+    failed: results.length - succeeded,
+    results
+  };
+}
+function renderSubAgentSummary(summary) {
+  const lines = [
+    `Sub-agent fan-out: ${summary.succeeded}/${summary.total} succeeded.`,
+    ""
+  ];
+  for (const r of summary.results) {
+    const status = r.ok ? "\u2713" : r.timedOut ? "\u23F1" : "\u2717";
+    const detail = r.ok ? (r.output ?? "").slice(0, 400) : `${r.error ?? "failed"}${r.timedOut ? ` (after ${Math.round(r.durationMs / 1e3)}s)` : ""}`;
+    lines.push(`${status} ${r.label}: ${detail}`);
+    lines.push("");
+  }
+  if (summary.failed > 0) {
+    lines.push(`${summary.failed} task(s) failed \u2014 consider retrying those individually.`);
+  }
+  return lines.join("\n");
+}
+var init_subAgent = __esm({
+  "../../packages/backend/src/services/AgentHelper/utils/subAgent.ts"() {
+    "use strict";
+  }
+});
+
 // ../../packages/backend/src/services/automation/templateEngine.ts
 var templateEngine_exports = {};
 __export(templateEngine_exports, {
@@ -257990,6 +258094,90 @@ var init_etwService = __esm({
   }
 });
 
+// ../../packages/backend/src/services/AgentHelper/utils/modelFailover.ts
+var modelFailover_exports = {};
+__export(modelFailover_exports, {
+  buildFailoverChain: () => buildFailoverChain,
+  isFailoverEligible: () => isFailoverEligible,
+  withModelFailover: () => withModelFailover
+});
+function isFailoverEligible(error40) {
+  const message = error40 instanceof Error ? error40.message : String(error40 ?? "");
+  for (const re of NON_FAILOVER_PATTERNS) {
+    if (re.test(message)) return { eligible: false, reason: "non-failover-error" };
+  }
+  for (const { re: pattern, reason } of FAILOVER_ERROR_PATTERNS) {
+    if (pattern.test(message)) return { eligible: true, reason };
+  }
+  return { eligible: true, reason: "unknown-error" };
+}
+function buildFailoverChain(primary, fallbacks) {
+  const chain = [primary];
+  if (!Array.isArray(fallbacks)) return chain;
+  const seen = /* @__PURE__ */ new Set([primary.model]);
+  for (const f of fallbacks) {
+    if (!f || !f.model) continue;
+    if (seen.has(f.model)) continue;
+    seen.add(f.model);
+    chain.push(f);
+  }
+  return chain;
+}
+async function withModelFailover(chain, operation, opts = {}) {
+  const attempts = [];
+  let lastError;
+  if (chain.length === 0) {
+    return {
+      error: new Error("model failover chain is empty \u2014 no candidates to try"),
+      attempts
+    };
+  }
+  for (const candidate of chain) {
+    const started = Date.now();
+    try {
+      const value = await operation(candidate);
+      const attempt = { model: candidate.model, ok: true, durationMs: Date.now() - started };
+      attempts.push(attempt);
+      opts.onAttempt?.(attempt);
+      return { value, attempts, usedModel: candidate.model };
+    } catch (error40) {
+      const decision = isFailoverEligible(error40);
+      const attempt = {
+        model: candidate.model,
+        ok: false,
+        reason: decision.reason,
+        durationMs: Date.now() - started
+      };
+      attempts.push(attempt);
+      opts.onAttempt?.(attempt);
+      if (!decision.eligible) {
+        return { error: error40, attempts };
+      }
+      lastError = error40;
+    }
+  }
+  return { error: lastError, attempts };
+}
+var FAILOVER_ERROR_PATTERNS, NON_FAILOVER_PATTERNS;
+var init_modelFailover = __esm({
+  "../../packages/backend/src/services/AgentHelper/utils/modelFailover.ts"() {
+    "use strict";
+    FAILOVER_ERROR_PATTERNS = [
+      { re: /\b429\b|rate.?limit|too many requests|quota/i, reason: "rate-limited" },
+      { re: /\b5\d\d\b|internal server error|bad gateway|service unavailable|upstream/i, reason: "provider-5xx" },
+      { re: /network|fetch failed|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|socket hang up/i, reason: "network" },
+      { re: /\b401\b|unauthorized|invalid api key|authentication/i, reason: "auth" },
+      { re: /overloaded|capacity|model .* not found|no such model/i, reason: "model-unavailable" }
+    ];
+    NON_FAILOVER_PATTERNS = [
+      /context.?length|token limit|maximum context/i,
+      /invalid request|malformed|bad request|\b400\b/i,
+      /aborted|AbortError/i
+      // user cancelled — never retry
+    ];
+  }
+});
+
 // ../../packages/backend/src/services/history/HistorySqliteStore.ts
 var HistorySqliteStore_exports = {};
 __export(HistorySqliteStore_exports, {
@@ -261975,6 +262163,136 @@ var require_websocket_server = __commonJS({
   }
 });
 
+// ../../packages/backend/src/services/history/historySearch.ts
+var historySearch_exports = {};
+__export(historySearch_exports, {
+  buildSnippet: () => buildSnippet,
+  extractMessageText: () => extractMessageText2,
+  findMatches: () => findMatches,
+  normalizeMessages: () => normalizeMessages,
+  searchChatHistory: () => searchChatHistory
+});
+function extractMessageText2(data) {
+  if (!data || typeof data !== "object") return "";
+  let obj = data;
+  for (let i = 0; i < 3 && obj.data && typeof obj.data === "object" && !Array.isArray(obj.data); i++) {
+    const inner = obj.data;
+    if (inner.content !== void 0 || inner.data !== void 0) {
+      obj = inner;
+    } else {
+      break;
+    }
+  }
+  const content = obj.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map((part) => {
+      if (typeof part === "string") return part;
+      if (part && typeof part === "object") {
+        const p = part;
+        if (typeof p.text === "string") return p.text;
+      }
+      return "";
+    }).join(" ");
+  }
+  return "";
+}
+function buildSnippet(text, offset, length) {
+  const start = Math.max(0, offset - SNIPPET_CONTEXT);
+  const end = Math.min(text.length, offset + length + SNIPPET_CONTEXT);
+  const prefix = start > 0 ? "\u2026" : "";
+  const suffix = end < text.length ? "\u2026" : "";
+  return prefix + text.slice(start, end).replace(/\s+/g, " ").trim() + suffix;
+}
+function findMatches(text, query, wholeWord) {
+  if (!text || !query) return [];
+  const haystack = text.toLowerCase();
+  const needle = query.toLowerCase();
+  const out = [];
+  if (wholeWord) {
+    const re = new RegExp(`\\b${needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "gi");
+    let m2;
+    while ((m2 = re.exec(haystack)) !== null) {
+      out.push({ offset: m2.index, length: m2[0].length });
+      if (m2.index === re.lastIndex) re.lastIndex++;
+    }
+  } else {
+    let idx = haystack.indexOf(needle);
+    while (idx !== -1) {
+      out.push({ offset: idx, length: needle.length });
+      idx = haystack.indexOf(needle, idx + needle.length);
+    }
+  }
+  return out;
+}
+function normalizeMessages(messages) {
+  if (!messages) return [];
+  if (Array.isArray(messages)) return messages;
+  if (messages instanceof Map) return [...messages.values()];
+  if (typeof messages === "object") return Object.values(messages);
+  return [];
+}
+function searchChatHistory(sessions, query, options = {}) {
+  const sessionLimit = options.sessionLimit ?? DEFAULT_SESSION_LIMIT;
+  const snippetLimit = options.snippetLimit ?? DEFAULT_SNIPPET_LIMIT;
+  const wholeWord = options.wholeWord ?? false;
+  const includeTitles = options.includeTitles ?? true;
+  const trimmed = (query ?? "").trim();
+  if (!trimmed) {
+    return { query: trimmed, totalSessions: 0, totalMatches: 0, sessions: [], truncated: false };
+  }
+  const results = [];
+  let totalMatches = 0;
+  for (const session of sessions) {
+    let matchCount = 0;
+    const matches = [];
+    const titleHit = includeTitles && session.title ? findMatches(session.title, trimmed, wholeWord) : [];
+    for (const message of normalizeMessages(session.messages)) {
+      const text = extractMessageText2(message?.data);
+      if (!text) continue;
+      const hits = findMatches(text, trimmed, wholeWord);
+      for (const hit of hits) {
+        matchCount++;
+        totalMatches++;
+        if (matches.length < snippetLimit) {
+          matches.push({
+            messageId: String(message?.id ?? ""),
+            type: String(message?.type ?? ""),
+            snippet: buildSnippet(text, hit.offset, hit.length),
+            offset: hit.offset
+          });
+        }
+      }
+    }
+    if (matchCount === 0 && titleHit.length === 0) continue;
+    results.push({
+      sessionId: session.id,
+      sessionTitle: session.title,
+      updatedAt: session.updatedAt,
+      matchCount: matchCount + titleHit.length,
+      matches
+    });
+  }
+  results.sort((a, b) => b.matchCount - a.matchCount || b.updatedAt - a.updatedAt);
+  const truncated = results.length > sessionLimit;
+  return {
+    query: trimmed,
+    totalSessions: results.length,
+    totalMatches,
+    sessions: results.slice(0, sessionLimit),
+    truncated
+  };
+}
+var SNIPPET_CONTEXT, DEFAULT_SESSION_LIMIT, DEFAULT_SNIPPET_LIMIT;
+var init_historySearch = __esm({
+  "../../packages/backend/src/services/history/historySearch.ts"() {
+    "use strict";
+    SNIPPET_CONTEXT = 60;
+    DEFAULT_SESSION_LIMIT = 20;
+    DEFAULT_SNIPPET_LIMIT = 3;
+  }
+});
+
 // ../../node_modules/@modelcontextprotocol/sdk/node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS({
   "../../node_modules/@modelcontextprotocol/sdk/node_modules/ajv/dist/compile/codegen/code.js"(exports2) {
@@ -274408,12 +274726,12 @@ var require_dist2 = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs22, exportName) {
+    function addFormats(ajv, list, fs23, exportName) {
       var _a3;
       var _b;
       (_a3 = (_b = ajv.opts.code).formats) !== null && _a3 !== void 0 ? _a3 : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs22[f]);
+        ajv.addFormat(f, fs23[f]);
     }
     module2.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -274426,7 +274744,7 @@ var require_windows = __commonJS({
   "../../node_modules/isexe/windows.js"(exports2, module2) {
     module2.exports = isexe;
     isexe.sync = sync;
-    var fs22 = require("fs");
+    var fs23 = require("fs");
     function checkPathExt(path32, options) {
       var pathext = options.pathExt !== void 0 ? options.pathExt : process.env.PATHEXT;
       if (!pathext) {
@@ -274451,12 +274769,12 @@ var require_windows = __commonJS({
       return checkPathExt(path32, options);
     }
     function isexe(path32, options, cb) {
-      fs22.stat(path32, function(er, stat) {
+      fs23.stat(path32, function(er, stat) {
         cb(er, er ? false : checkStat(stat, path32, options));
       });
     }
     function sync(path32, options) {
-      return checkStat(fs22.statSync(path32), path32, options);
+      return checkStat(fs23.statSync(path32), path32, options);
     }
   }
 });
@@ -274466,14 +274784,14 @@ var require_mode = __commonJS({
   "../../node_modules/isexe/mode.js"(exports2, module2) {
     module2.exports = isexe;
     isexe.sync = sync;
-    var fs22 = require("fs");
+    var fs23 = require("fs");
     function isexe(path32, options, cb) {
-      fs22.stat(path32, function(er, stat) {
+      fs23.stat(path32, function(er, stat) {
         cb(er, er ? false : checkStat(stat, options));
       });
     }
     function sync(path32, options) {
-      return checkStat(fs22.statSync(path32), options);
+      return checkStat(fs23.statSync(path32), options);
     }
     function checkStat(stat, options) {
       return stat.isFile() && checkMode(stat, options);
@@ -274497,7 +274815,7 @@ var require_mode = __commonJS({
 // ../../node_modules/isexe/index.js
 var require_isexe = __commonJS({
   "../../node_modules/isexe/index.js"(exports2, module2) {
-    var fs22 = require("fs");
+    var fs23 = require("fs");
     var core2;
     if (process.platform === "win32" || global.TESTING_WINDOWS) {
       core2 = require_windows();
@@ -274761,16 +275079,16 @@ var require_shebang_command = __commonJS({
 var require_readShebang = __commonJS({
   "../../node_modules/cross-spawn/lib/util/readShebang.js"(exports2, module2) {
     "use strict";
-    var fs22 = require("fs");
+    var fs23 = require("fs");
     var shebangCommand = require_shebang_command();
     function readShebang(command) {
       const size = 150;
       const buffer = Buffer.alloc(size);
       let fd;
       try {
-        fd = fs22.openSync(command, "r");
-        fs22.readSync(fd, buffer, 0, size, 0);
-        fs22.closeSync(fd);
+        fd = fs23.openSync(command, "r");
+        fs23.readSync(fd, buffer, 0, size, 0);
+        fs23.closeSync(fd);
       } catch (e) {
       }
       return shebangCommand(buffer.toString());
@@ -275398,7 +275716,7 @@ var require_has_flag = __commonJS({
 var require_supports_color = __commonJS({
   "../../node_modules/supports-color/index.js"(exports2, module2) {
     "use strict";
-    var os7 = require("os");
+    var os8 = require("os");
     var tty = require("tty");
     var hasFlag = require_has_flag();
     var { env } = process;
@@ -275446,7 +275764,7 @@ var require_supports_color = __commonJS({
         return min;
       }
       if (process.platform === "win32") {
-        const osRelease = os7.release().split(".");
+        const osRelease = os8.release().split(".");
         if (Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
           return Number(osRelease[2]) >= 14931 ? 3 : 2;
         }
@@ -286297,11 +286615,11 @@ var require_jsmconsumer_api = __commonJS({
           consumerName = cfg.name ?? cfg.durable_name ?? "";
         }
         if (consumerName !== "") {
-          let fs22 = cfg.filter_subject ?? void 0;
-          if (fs22 === ">") {
-            fs22 = void 0;
+          let fs23 = cfg.filter_subject ?? void 0;
+          if (fs23 === ">") {
+            fs23 = void 0;
           }
-          subj = fs22 !== void 0 ? `${this.prefix}.CONSUMER.CREATE.${stream}.${consumerName}.${fs22}` : `${this.prefix}.CONSUMER.CREATE.${stream}.${consumerName}`;
+          subj = fs23 !== void 0 ? `${this.prefix}.CONSUMER.CREATE.${stream}.${consumerName}.${fs23}` : `${this.prefix}.CONSUMER.CREATE.${stream}.${consumerName}`;
         } else {
           subj = cfg.durable_name ? `${this.prefix}.CONSUMER.DURABLE.CREATE.${stream}.${cfg.durable_name}` : `${this.prefix}.CONSUMER.CREATE.${stream}`;
         }
@@ -290852,6 +291170,7 @@ var init_natsEventBus = __esm({
 
 // ../../packages/backend/src/runtimes/gybackend/startGyBackend.ts
 var import_node_path28 = __toESM(require("node:path"), 1);
+var import_node_fs12 = __toESM(require("node:fs"), 1);
 var import_node_process2 = __toESM(require("node:process"), 1);
 
 // ../../packages/backend/src/services/TerminalService.ts
@@ -293693,19 +294012,19 @@ var SSHBackend = class _SSHBackend {
           ),
           this.execCollect(client2, "hostname", 8e3)
         ]);
-        let os7 = "unix";
+        let os8 = "unix";
         const releaseMatch = osRelease.stdout.match(/^ID=(.*)$/m);
         if (releaseMatch) {
-          os7 = releaseMatch[1].replace(/"/g, "");
+          os8 = releaseMatch[1].replace(/"/g, "");
         } else {
           const unameS2 = uname.stdout.split(" ")[0].toLowerCase();
-          os7 = unameS2 || "unix";
+          os8 = unameS2 || "unix";
         }
         const unameS = uname.stdout.split(" ")[0].toLowerCase();
         const platform2 = unameS.includes("darwin") ? "darwin" : unameS.includes("linux") ? "linux" : "unix";
         const parts = uname.stdout.split(" ");
         const next = {
-          os: os7,
+          os: os8,
           platform: platform2,
           release: parts[2] || "",
           arch: parts[parts.length - 2] || "",
@@ -300516,6 +300835,9 @@ var TerminalService = class _TerminalService {
   terminalIdsBeingKilled = /* @__PURE__ */ new Set();
   autoReconnect = new AutoReconnect({ maxAttempts: 10 });
   terminalClosedListeners = /* @__PURE__ */ new Set();
+  /** v3.2.18: idle-timeout tracking hooks. */
+  terminalCreatedListeners = /* @__PURE__ */ new Set();
+  terminalDataListeners = /* @__PURE__ */ new Set();
   /** Optional session logger (records terminal output to disk per session). */
   sessionLogger = null;
   sessionLogStarted = /* @__PURE__ */ new Set();
@@ -300565,6 +300887,38 @@ var TerminalService = class _TerminalService {
       this.terminalClosedListeners.delete(listener);
     };
   }
+  /** v3.2.18: fires when a terminal tab is created (idle-timeout tracking). */
+  onTerminalCreated(listener) {
+    this.terminalCreatedListeners.add(listener);
+    return () => {
+      this.terminalCreatedListeners.delete(listener);
+    };
+  }
+  /** v3.2.18: fires on any terminal data event (idle-timeout activity). */
+  onTerminalData(listener) {
+    this.terminalDataListeners.add(listener);
+    return () => {
+      this.terminalDataListeners.delete(listener);
+    };
+  }
+  /** v3.2.18: notify created-listeners (called from createTerminal paths). */
+  notifyTerminalCreated(terminalId) {
+    for (const listener of this.terminalCreatedListeners) {
+      try {
+        listener(terminalId);
+      } catch {
+      }
+    }
+  }
+  /** v3.2.18: notify data-listeners (called from the data pump). */
+  notifyTerminalData(terminalId) {
+    for (const listener of this.terminalDataListeners) {
+      try {
+        listener(terminalId);
+      } catch {
+      }
+    }
+  }
   listRenderableTerminals() {
     return Array.from(this.terminals.values()).map((terminal) => ({
       id: terminal.id,
@@ -300883,6 +301237,7 @@ var TerminalService = class _TerminalService {
     }
     this.publishTerminalTabsChanged();
     this.schedulePersistTerminalState();
+    this.notifyTerminalCreated(tab.id);
     return tab;
   }
   async reconnectTerminal(terminalId) {
@@ -301076,6 +301431,7 @@ var TerminalService = class _TerminalService {
             }
             this.sessionLogger.write(terminalId, captureData);
           }
+          this.notifyTerminalData(terminalId);
         });
       }
     }
@@ -301397,6 +301753,7 @@ ${promptPrefix}`;
       const backend = this.getBackend(terminal.type);
       backend.write(terminal.ptyId, data);
       this.pendingWriteRetries.delete(terminalId);
+      this.notifyTerminalData(terminalId);
     } else if (terminal) {
       if (terminal.runtimeState === "exited") {
         this.pendingWrites.delete(terminalId);
@@ -350077,6 +350434,11 @@ var CLOSE_TERMINAL_TAB_DESCRIPTION = [
   "Use this to clean up tabs the task no longer needs \u2014 e.g. after a transfer finished, or after a one-off probe on a server. Close tabs you opened yourself when the work is done; do not close tabs the user was actively using unless asked.",
   "Guarded: it refuses to close the last remaining terminal tab (at least one tab must stay open) and reports how many tabs remain after the close. If the tab is running a command, the command is terminated by the close."
 ].join("\n");
+var SPAWN_SUBAGENTS_DESCRIPTION = [
+  "Fan work out to concurrent child agent sessions. Each task gets its own session running its prompt to completion; results are collected into one summary.",
+  "Use this when you have MULTIPLE INDEPENDENT tasks that would otherwise run one at a time \u2014 e.g. 'check disk usage on these 6 servers', 'analyze these 3 files', or 'research these 4 questions'. Do NOT use it for sequential work where each step depends on the previous one's output.",
+  "Each task needs a self-contained prompt (the child has no context from this conversation) and a short label. Guards: max 20 tasks per fan-out, per-child timeout 5 minutes (configurable), concurrency cap 3 (configurable). One child failing or timing out does not affect the others \u2014 you get a per-task result with \u2713/\u2717 status."
+].join("\n");
 var COPY_BETWEEN_TABS_DESCRIPTION = [
   "Start an asynchronous file copy between two different terminal tabs on different machines. Use this only for cross-terminal-tab file transfer; do not use it for copying within one tab or between two tabs connected to the same machine.",
   "If either source or target terminal is disconnected or not ready, this tool returns an explicit terminal_status for that side and does not start a transfer.",
@@ -350214,6 +350576,11 @@ var BUILTIN_TOOL_INFO = [
     description: CLOSE_TERMINAL_TAB_DESCRIPTION,
     shortDescription: "Close a terminal tab"
   },
+  {
+    name: "spawn_subagents",
+    description: SPAWN_SUBAGENTS_DESCRIPTION,
+    shortDescription: "Fan out to concurrent child agents"
+  },
   {
     name: "create_or_edit",
     description: CREATE_OR_EDIT_TOOL_DESCRIPTION,
@@ -351869,6 +352236,69 @@ async function closeTerminalTab(args, context2) {
   }
 }
 
+// ../../packages/backend/src/services/AgentHelper/tools/subAgent_tools.ts
+init_zod();
+var spawnSubAgentsSchema = external_exports.object({
+  tasks: external_exports.array(
+    external_exports.object({
+      label: external_exports.string().min(1).describe('Short label for reporting, e.g. "server-1"'),
+      prompt: external_exports.string().min(1).describe("The self-contained prompt for the child agent.")
+    })
+  ).min(1).max(20).describe("The tasks to fan out. Each child gets its own session. Max 20."),
+  maxConcurrent: external_exports.number().int().min(1).max(10).optional().describe("Max children running concurrently (default 3)."),
+  timeoutMs: external_exports.number().int().min(1e3).optional().describe("Per-child timeout in ms (default 300000 = 5 minutes).")
+});
+async function spawnSubAgents(args, context2) {
+  abortIfNeeded(context2.signal);
+  const { sendEvent, sessionId, messageId } = context2;
+  sendEvent(sessionId, {
+    messageId,
+    type: "sub_tool_started",
+    toolName: "spawn_subagents",
+    title: `Fan out ${args.tasks.length} sub-agent(s)`,
+    hint: `concurrency ${args.maxConcurrent ?? 3}`,
+    input: JSON.stringify(args)
+  });
+  const finish = (output) => {
+    sendEvent(sessionId, { messageId, type: "sub_tool_delta", outputDelta: output });
+    sendEvent(sessionId, { messageId, type: "sub_tool_finished" });
+    return output;
+  };
+  try {
+    const { validateSubAgentSpec: validateSubAgentSpec2, runSubAgents: runSubAgents2, renderSubAgentSummary: renderSubAgentSummary2 } = await Promise.resolve().then(() => (init_subAgent(), subAgent_exports));
+    const validation = validateSubAgentSpec2(args);
+    if (!validation.ok) {
+      return finish(`Invalid sub-agent spec: ${validation.error}`);
+    }
+    const agentService = context2.agentService;
+    if (!agentService?.startTask) {
+      return finish(
+        "Sub-agent delegation is not available in this runtime (no agent service bridge)."
+      );
+    }
+    const summary = await runSubAgents2(
+      {
+        tasks: args.tasks.map((t) => ({ label: t.label, prompt: t.prompt })),
+        maxConcurrent: args.maxConcurrent,
+        timeoutMs: args.timeoutMs
+      },
+      async (task2) => {
+        const childSession = await agentService.createSession();
+        const result = await agentService.startTask({
+          sessionId: childSession.sessionId,
+          userInput: task2.prompt
+        });
+        const text = typeof result === "string" ? result : String(result?.answer ?? result?.output ?? result);
+        return text;
+      }
+    );
+    return finish(renderSubAgentSummary2(summary));
+  } catch (error40) {
+    if (error40 instanceof Error && error40.name === "AbortError") throw error40;
+    return finish(`Sub-agent fan-out failed: ${error40 instanceof Error ? error40.message : String(error40)}`);
+  }
+}
+
 // ../../packages/backend/src/services/AgentHelper/tools/wait_tools.ts
 init_zod();
 var waitSchema = external_exports.object({
@@ -354243,6 +354673,11 @@ var CORE_METHODS = [
   m("gateway:isSameMachine", "gateway", "Whether the caller is on the same machine as the backend.", "1.0.0"),
   m("gateway:createSession", "session", "Create an agent session (returns sessionId).", "1.0.0"),
   m("session:list", "session", "List chat sessions.", "1.0.0"),
+  m("history:search", "session", "Full-text search across ALL stored chat sessions (v3.2.18). Params: {query, wholeWord?, includeTitles?, sessionLimit?, snippetLimit?}. Returns matching sessions ranked by match count with snippets.", "3.2.18"),
+  m("settings:listBackups", "settings", "List timestamped settings backups (v3.2.18). Returns [{name, at, size}] newest-first.", "3.2.18"),
+  m("settings:restoreBackup", "settings", "Restore settings from a named backup (v3.2.18). Takes a SAFETY backup of the current state first. Params: {name}.", "3.2.18"),
+  m("settings:export", "settings", "Export the current settings.json content as a portable JSON string (v3.2.18).", "3.2.18"),
+  m("settings:import", "settings", "Import settings JSON (v3.2.18). Validates it is a JSON object; takes a SAFETY backup before replacing. Params: {content}.", "3.2.18"),
   m("session:get", "session", "Get one chat session by id.", "1.0.0", { sessionId: { type: "string" } }),
   m("agent:startTask", "agent", "Start an AI agent task (blocking) and return the final answer.", "1.0.0", { sessionId: { type: "string" }, userInput: { type: "string" } }),
   m("agent:startTaskAsync", "agent", "Start an AI agent task (async; watch events for progress).", "1.0.0", { sessionId: { type: "string" }, userInput: { type: "string" } }),
@@ -355212,6 +355647,11 @@ function buildToolsForModel(readFileSupport) {
       description: BUILTIN_TOOL_INFO.find((t) => t.name === "close_terminal_tab")?.description ?? "",
       schema: closeTerminalTabSchema
     },
+    {
+      name: "spawn_subagents",
+      description: BUILTIN_TOOL_INFO.find((t) => t.name === "spawn_subagents")?.description ?? "",
+      schema: spawnSubAgentsSchema
+    },
     {
       name: WRITE_FILE_TOOL_NAME,
       description: WRITE_FILE_TOOL_DESCRIPTION,
@@ -355450,6 +355890,7 @@ var toolImplementations = {
   reconnectTerminalTab,
   openTerminalTab,
   closeTerminalTab,
+  spawnSubAgents,
   wait,
   waitTerminalIdle,
   copyBetweenTabs,
@@ -368370,7 +368811,7 @@ Missing image attachments (kept as references only): ${missingNames.join(", ")}`
 // ../../packages/backend/src/services/PassChatTempExportService.ts
 var import_node_fs4 = __toESM(require("node:fs"), 1);
 var import_promises6 = __toESM(require("node:fs/promises"), 1);
-var import_node_os = __toESM(require("node:os"), 1);
+var import_node_os2 = __toESM(require("node:os"), 1);
 var import_node_path6 = __toESM(require("node:path"), 1);
 var import_node_crypto15 = __toESM(require("node:crypto"), 1);
 var DEFAULT_MAX_FILES = 50;
@@ -368379,7 +368820,7 @@ var PassChatTempExportService = class {
   maxFiles;
   groupBySession;
   constructor(options) {
-    this.baseDir = options?.baseDir || import_node_path6.default.join(import_node_os.default.tmpdir(), "gyshell-pass-chats");
+    this.baseDir = options?.baseDir || import_node_path6.default.join(import_node_os2.default.tmpdir(), "gyshell-pass-chats");
     this.maxFiles = options?.maxFiles === null ? null : Number.isInteger(options?.maxFiles) && Number(options?.maxFiles) > 0 ? Number(options?.maxFiles) : DEFAULT_MAX_FILES;
     this.groupBySession = options?.groupBySession === true;
   }
@@ -369002,6 +369443,20 @@ var AgentService_v2 = class {
   isAbortError(error40) {
     return this.helpers.isAbortError(error40);
   }
+  /**
+   * v3.2.18: resolve a fallback model id to its ModelDefinition from the
+   * session's settings. Returns null when the model isn't configured.
+   */
+  resolveFallbackModelItem(modelId) {
+    try {
+      const settings = this.options?.getSettings?.() ?? null;
+      const items = settings?.models?.items ?? [];
+      const hit = items.find((m2) => m2.model === modelId || m2.id === modelId || m2.name === modelId);
+      return hit ?? null;
+    } catch {
+      return null;
+    }
+  }
   /**
    * v3.2.12: true when the given run's final_output node already emitted the
    * `done` event. GatewayService uses this to avoid broadcasting a duplicate
@@ -369142,6 +369597,22 @@ var AgentService_v2 = class {
     const actionModel = actionItem?.apiKey ? this.helpers.createChatModel(actionItem, 0.1, profile) : model;
     const thinkingModel = thinkingItem?.apiKey ? this.helpers.createChatModel(thinkingItem, 0.2, profile) : model;
     const compactionModel = compactionItem?.apiKey ? this.helpers.createChatModel(compactionItem, 0.2, profile) : thinkingItem?.apiKey ? thinkingModel : model;
+    const fallbackModels = [];
+    const seenFallbackIds = /* @__PURE__ */ new Set([profile.globalModelId]);
+    for (const fallbackId of Array.isArray(profile.fallbackModels) ? profile.fallbackModels : []) {
+      if (typeof fallbackId !== "string" || !fallbackId.trim()) continue;
+      if (seenFallbackIds.has(fallbackId)) continue;
+      const item = settings.models.items.find((m2) => m2.id === fallbackId);
+      if (!item || !item.apiKey) {
+        console.warn(
+          "[AgentService_v2] Fallback model is invalid or has no API key \u2014 skipping:",
+          { profileId, fallbackId }
+        );
+        continue;
+      }
+      seenFallbackIds.add(fallbackId);
+      fallbackModels.push({ model: item.model, label: item.name ?? item.model });
+    }
     const actionModelSupportsStructuredOutput = actionItem?.apiKey ? actionItem.supportsStructuredOutput === true : globalItem.supportsStructuredOutput === true;
     const actionModelSupportsObjectToolChoice = actionItem?.apiKey ? actionItem.supportsObjectToolChoice === true : globalItem.supportsObjectToolChoice === true;
     const thinkingModelSupportsStructuredOutput = thinkingItem?.apiKey ? thinkingItem.supportsStructuredOutput === true : globalItem.supportsStructuredOutput === true;
@@ -369162,6 +369633,7 @@ var AgentService_v2 = class {
       actionModel,
       thinkingModel,
       compactionModel,
+      fallbackModels,
       actionModelSupportsStructuredOutput,
       actionModelSupportsObjectToolChoice,
       thinkingModelSupportsStructuredOutput,
@@ -369549,172 +370021,231 @@ var AgentService_v2 = class {
       let reasoningContent = "";
       let debugRawChunks = [];
       const llmTraceStart = Date.now();
-      const fullResponse = await invokeWithRetryAndSanitizedInput({
-        helpers: this.helpers,
-        messages: modelInputMessages,
-        modelSupportsImage: sessionBinding.readFileSupport.image,
-        signal: config2?.signal,
-        operation: async (streamInputMessages) => {
-          const stream = await modelWithTools.stream(streamInputMessages, {
-            signal: config2?.signal
+      const fallbacks = sessionBinding.fallbackModels;
+      let fullResponse;
+      if (Array.isArray(fallbacks) && fallbacks.length > 0) {
+        const { withModelFailover: withModelFailover2 } = await Promise.resolve().then(() => (init_modelFailover(), modelFailover_exports));
+        const primaryModel = baseModel?.model ?? baseModel?.modelName ?? "unknown";
+        const chain = [{ model: primaryModel }, ...fallbacks.map((f) => ({ model: f.model, label: f.label }))];
+        const failover = await withModelFailover2(chain, async (candidate) => {
+          let modelToUse = modelWithTools;
+          if (candidate.model !== primaryModel) {
+            const fallbackItem = this.resolveFallbackModelItem(candidate.model);
+            if (!fallbackItem) {
+              throw new Error(`fallback model "${candidate.model}" is not configured`);
+            }
+            const fallbackChat = this.helpers.createChatModel(
+              fallbackItem,
+              shouldUseThinkingModelOnThisPass ? 0.2 : 0.7,
+              null
+            );
+            modelToUse = fallbackChat.bindTools([...builtInTools, ...mcpTools]);
+          }
+          return await invokeWithRetryAndSanitizedInput({
+            helpers: this.helpers,
+            messages: modelInputMessages,
+            modelSupportsImage: sessionBinding.readFileSupport.image,
+            signal: config2?.signal,
+            operation: async (streamInputMessages) => {
+              const stream = await modelToUse.stream(streamInputMessages, { signal: config2?.signal });
+              let response = null;
+              for await (const chunk2 of stream) {
+                response = response ? response.concat(chunk2) : chunk2;
+              }
+              if (!response) throw new Error("Model stream ended without a usable response.");
+              return response;
+            },
+            onRetry: (attempt) => {
+              this.helpers.sendEvent(sessionId, {
+                type: "alert",
+                message: `Retrying (${attempt}/${MODEL_RETRY_MAX})...`,
+                level: "info",
+                messageId: `retry-${messageId}-${attempt}`
+              });
+            },
+            maxRetries: MODEL_RETRY_MAX,
+            delaysMs: MODEL_RETRY_DELAYS_MS
           });
-          let response = null;
-          let skippedEmptyGenericChunks = 0;
-          const streamReasoningExtractor = createStreamReasoningExtractor();
-          const attemptDebugRawChunks = [];
-          let activeReasoningBannerId = null;
-          const startReasoningBanner = () => {
-            if (activeReasoningBannerId) return;
-            activeReasoningBannerId = v4_default();
-            this.helpers.sendEvent(sessionId, {
-              messageId: activeReasoningBannerId,
-              type: "sub_tool_started",
-              title: "Reasoning...",
-              hint: ""
-            });
-          };
-          const appendReasoningDelta = (delta) => {
-            if (!delta) return;
-            startReasoningBanner();
-            this.helpers.sendEvent(sessionId, {
-              messageId: activeReasoningBannerId,
-              type: "sub_tool_delta",
-              outputDelta: delta
-            });
-          };
-          const finishReasoningBanner = () => {
-            if (!activeReasoningBannerId) return;
-            this.helpers.sendEvent(sessionId, {
-              messageId: activeReasoningBannerId,
-              type: "sub_tool_finished"
+        }, {
+          onAttempt: (a) => {
+            if (!a.ok) {
+              console.warn(`[AgentService_v2] model failover: ${a.model} failed (${a.reason}) after ${a.durationMs}ms`);
+            }
+          }
+        });
+        if (failover.value !== void 0) {
+          fullResponse = failover.value;
+        } else {
+          throw failover.error ?? new Error("model failover exhausted all candidates");
+        }
+      } else {
+        fullResponse = await invokeWithRetryAndSanitizedInput({
+          helpers: this.helpers,
+          messages: modelInputMessages,
+          modelSupportsImage: sessionBinding.readFileSupport.image,
+          signal: config2?.signal,
+          operation: async (streamInputMessages) => {
+            const stream = await modelWithTools.stream(streamInputMessages, {
+              signal: config2?.signal
             });
-            activeReasoningBannerId = null;
-          };
-          try {
-            for await (const chunk2 of stream) {
-              const rawChunk = captureRawResponseChunk(
-                chunk2,
-                attemptDebugRawChunks
-              );
-              const extracted = streamReasoningExtractor.processChunk(
-                chunk2,
-                rawChunk
-              );
-              const appendResult = appendStreamedModelResponseChunk(
-                response,
-                chunk2,
-                rawChunk
-              );
-              response = appendResult.response;
-              if (appendResult.skippedEmptyGenericChunk) {
-                skippedEmptyGenericChunks += 1;
-              }
-              const rawDelta = this.helpers.extractText(chunk2.content);
-              if (rawDelta) {
-                partialText += rawDelta;
-              }
-              if (extracted.reasoning) {
-                appendReasoningDelta(extracted.reasoning);
-              } else {
-                finishReasoningBanner();
+            let response = null;
+            let skippedEmptyGenericChunks = 0;
+            const streamReasoningExtractor = createStreamReasoningExtractor();
+            const attemptDebugRawChunks = [];
+            let activeReasoningBannerId = null;
+            const startReasoningBanner = () => {
+              if (activeReasoningBannerId) return;
+              activeReasoningBannerId = v4_default();
+              this.helpers.sendEvent(sessionId, {
+                messageId: activeReasoningBannerId,
+                type: "sub_tool_started",
+                title: "Reasoning...",
+                hint: ""
+              });
+            };
+            const appendReasoningDelta = (delta) => {
+              if (!delta) return;
+              startReasoningBanner();
+              this.helpers.sendEvent(sessionId, {
+                messageId: activeReasoningBannerId,
+                type: "sub_tool_delta",
+                outputDelta: delta
+              });
+            };
+            const finishReasoningBanner = () => {
+              if (!activeReasoningBannerId) return;
+              this.helpers.sendEvent(sessionId, {
+                messageId: activeReasoningBannerId,
+                type: "sub_tool_finished"
+              });
+              activeReasoningBannerId = null;
+            };
+            try {
+              for await (const chunk2 of stream) {
+                const rawChunk = captureRawResponseChunk(
+                  chunk2,
+                  attemptDebugRawChunks
+                );
+                const extracted = streamReasoningExtractor.processChunk(
+                  chunk2,
+                  rawChunk
+                );
+                const appendResult = appendStreamedModelResponseChunk(
+                  response,
+                  chunk2,
+                  rawChunk
+                );
+                response = appendResult.response;
+                if (appendResult.skippedEmptyGenericChunk) {
+                  skippedEmptyGenericChunks += 1;
+                }
+                const rawDelta = this.helpers.extractText(chunk2.content);
+                if (rawDelta) {
+                  partialText += rawDelta;
+                }
+                if (extracted.reasoning) {
+                  appendReasoningDelta(extracted.reasoning);
+                } else {
+                  finishReasoningBanner();
+                }
+                if (extracted.content) {
+                  this.helpers.sendEvent(sessionId, {
+                    messageId,
+                    type: "say",
+                    content: extracted.content
+                  });
+                }
               }
-              if (extracted.content) {
+              const pendingContent = streamReasoningExtractor.flushPendingContent();
+              if (pendingContent) {
                 this.helpers.sendEvent(sessionId, {
                   messageId,
                   type: "say",
-                  content: extracted.content
+                  content: pendingContent
                 });
               }
+              finishReasoningBanner();
+            } catch (err) {
+              finishReasoningBanner();
+              if (partialText.trim()) {
+                this.lastAbortedMessage = new AIMessage({
+                  content: partialText,
+                  additional_kwargs: {
+                    _gyshellMessageId: messageId,
+                    _gyshellAborted: true
+                  }
+                });
+                console.log(
+                  "[AgentService_v2] Captured partial message from error/abort in instance variable."
+                );
+              }
+              throw err;
             }
-            const pendingContent = streamReasoningExtractor.flushPendingContent();
-            if (pendingContent) {
-              this.helpers.sendEvent(sessionId, {
-                messageId,
-                type: "say",
-                content: pendingContent
-              });
+            if (!response) {
+              throw new Error("Model stream ended without a usable response.");
             }
-            finishReasoningBanner();
-          } catch (err) {
-            finishReasoningBanner();
-            if (partialText.trim()) {
-              this.lastAbortedMessage = new AIMessage({
-                content: partialText,
-                additional_kwargs: {
-                  _gyshellMessageId: messageId,
-                  _gyshellAborted: true
+            if (skippedEmptyGenericChunks > 0) {
+              response.additional_kwargs = {
+                ...response.additional_kwargs || {},
+                [SKIPPED_EMPTY_GENERIC_CHUNKS_KEY]: skippedEmptyGenericChunks
+              };
+            }
+            reasoningContent = streamReasoningExtractor.getReasoningContent();
+            if (isEmptyMalformedToolCallFinish(response, attemptDebugRawChunks) && typeof modelWithTools.invoke === "function") {
+              console.warn(
+                `[AgentService_v2] Stream ended with malformed empty tool-call finish; retrying same request with non-stream invoke (sessionId=${sessionId}).`
+              );
+              const invokeResponse = await modelWithTools.invoke(
+                streamInputMessages,
+                {
+                  signal: config2?.signal
                 }
-              });
-              console.log(
-                "[AgentService_v2] Captured partial message from error/abort in instance variable."
               );
-            }
-            throw err;
-          }
-          if (!response) {
-            throw new Error("Model stream ended without a usable response.");
-          }
-          if (skippedEmptyGenericChunks > 0) {
-            response.additional_kwargs = {
-              ...response.additional_kwargs || {},
-              [SKIPPED_EMPTY_GENERIC_CHUNKS_KEY]: skippedEmptyGenericChunks
-            };
-          }
-          reasoningContent = streamReasoningExtractor.getReasoningContent();
-          if (isEmptyMalformedToolCallFinish(response, attemptDebugRawChunks) && typeof modelWithTools.invoke === "function") {
-            console.warn(
-              `[AgentService_v2] Stream ended with malformed empty tool-call finish; retrying same request with non-stream invoke (sessionId=${sessionId}).`
-            );
-            const invokeResponse = await modelWithTools.invoke(
-              streamInputMessages,
-              {
-                signal: config2?.signal
-              }
-            );
-            captureRawResponseChunk(
-              invokeResponse,
-              attemptDebugRawChunks
-            );
-            if (!isEmptyMalformedToolCallFinish(
-              invokeResponse,
-              attemptDebugRawChunks
-            )) {
-              const invokeText = this.helpers.extractText(
-                invokeResponse.content
+              captureRawResponseChunk(
+                invokeResponse,
+                attemptDebugRawChunks
               );
-              if (invokeText) {
-                this.helpers.sendEvent(sessionId, {
-                  messageId,
-                  type: "say",
-                  content: invokeText
-                });
+              if (!isEmptyMalformedToolCallFinish(
+                invokeResponse,
+                attemptDebugRawChunks
+              )) {
+                const invokeText = this.helpers.extractText(
+                  invokeResponse.content
+                );
+                if (invokeText) {
+                  this.helpers.sendEvent(sessionId, {
+                    messageId,
+                    type: "say",
+                    content: invokeText
+                  });
+                }
+                response = invokeResponse;
               }
-              response = invokeResponse;
             }
-          }
-          if (!isEmptyMalformedToolCallFinish(response, attemptDebugRawChunks) && isEmptyUnusableModelResponse(response, attemptDebugRawChunks)) {
-            const finishReason = describeStreamedResponseFinish(
-              response,
-              attemptDebugRawChunks
-            );
-            throw new Error(
-              `Model stream ended with an empty unusable response (finish_reason=${finishReason}).`
-            );
-          }
-          debugRawChunks = attemptDebugRawChunks;
-          return response;
-        },
-        onRetry: (attempt) => {
-          this.helpers.sendEvent(sessionId, {
-            type: "alert",
-            message: `Retrying (${attempt}/${MODEL_RETRY_MAX})...`,
-            level: "info",
-            messageId: `retry-${messageId}-${attempt}`
-          });
-        },
-        maxRetries: MODEL_RETRY_MAX,
-        delaysMs: MODEL_RETRY_DELAYS_MS
-      });
+            if (!isEmptyMalformedToolCallFinish(response, attemptDebugRawChunks) && isEmptyUnusableModelResponse(response, attemptDebugRawChunks)) {
+              const finishReason = describeStreamedResponseFinish(
+                response,
+                attemptDebugRawChunks
+              );
+              throw new Error(
+                `Model stream ended with an empty unusable response (finish_reason=${finishReason}).`
+              );
+            }
+            debugRawChunks = attemptDebugRawChunks;
+            return response;
+          },
+          onRetry: (attempt) => {
+            this.helpers.sendEvent(sessionId, {
+              type: "alert",
+              message: `Retrying (${attempt}/${MODEL_RETRY_MAX})...`,
+              level: "info",
+              messageId: `retry-${messageId}-${attempt}`
+            });
+          },
+          maxRetries: MODEL_RETRY_MAX,
+          delaysMs: MODEL_RETRY_DELAYS_MS
+        });
+      }
       fullResponse.additional_kwargs = {
         ...fullResponse.additional_kwargs || {},
         _gyshellMessageId: messageId
@@ -370110,6 +370641,22 @@ Actually, your intention might be different. Please re-read the description of t
           }
           break;
         }
+        case "spawn_subagents": {
+          try {
+            const validatedArgs = spawnSubAgentsSchema.parse(
+              toolCall.args || {}
+            );
+            result = await toolImplementations.spawnSubAgents(
+              validatedArgs,
+              // The sub-agent tool needs the agent service to create child
+              // sessions — inject it into the execution context.
+              { ...executionContext, agentService: this }
+            );
+          } catch (err) {
+            result = `Parameter validation error for spawn_subagents: ${err.message}`;
+          }
+          break;
+        }
         case "manage_ssh_connection": {
           try {
             const validatedArgs = manageSshConnectionSchema.parse(
@@ -374652,13 +375199,16 @@ var WebSocketGatewayAdapter = class {
     }
     const token = this.extractAccessToken(request);
     if (!token) {
+      this.options.rateLimiter?.recordAuthFailure(this.clientKeyForRequest(request));
       return "missing access token";
     }
     try {
       const valid = await auth2.verifyToken(token);
       if (!valid) {
+        this.options.rateLimiter?.recordAuthFailure(this.clientKeyForRequest(request));
         return "invalid access token";
       }
+      this.options.rateLimiter?.recordAuthSuccess(this.clientKeyForRequest(request));
       return null;
     } catch (error40) {
       this.logger.warn(
@@ -374668,6 +375218,15 @@ var WebSocketGatewayAdapter = class {
       return "token verification failed";
     }
   }
+  /** v3.2.18: a stable per-client key for rate limiting (IP or token id). */
+  clientKeyForRequest(request) {
+    return String(request?.socket?.remoteAddress || "unknown");
+  }
+  /** v3.2.18: per-client key from a live socket connection. */
+  clientKeyForSocket(socket) {
+    const remote = socket.remoteAddress;
+    return String(remote || "unknown");
+  }
   extractAccessToken(request) {
     const fromAuthHeader = this.readBearerToken(
       request?.headers?.authorization
@@ -374828,6 +375387,17 @@ var WebSocketGatewayAdapter = class {
     try {
       const parsed = this.parseRequest(raw);
       requestId = parsed.id !== void 0 ? String(parsed.id) : void 0;
+      const limiter = this.options.rateLimiter;
+      if (limiter) {
+        const clientKey = this.clientKeyForSocket(socket);
+        const decision = limiter.check(clientKey);
+        if (!decision.allowed) {
+          throw new WebSocketRpcError(
+            "RATE_LIMITED",
+            decision.reason === "locked-out" ? `locked out; retry in ${Math.ceil((decision.retryAfterMs ?? 0) / 1e3)}s` : `rate limited; retry in ${Math.ceil((decision.retryAfterMs ?? 1e3) / 1e3)}s`
+          );
+        }
+      }
       const result = await this.executeRequest(parsed, socket);
       if (requestId) {
         this.sendRpcSuccess(socket, requestId, result);
@@ -374885,6 +375455,26 @@ var WebSocketGatewayAdapter = class {
       "Unsupported websocket payload type."
     );
   }
+  /**
+   * v3.2.18: public dispatch for non-WebSocket callers (the REST API layer).
+   * Executes a gateway method with a synthetic loopback socket — same
+   * validation and error mapping as a WS request, no socket required.
+   */
+  async handleRequest(method, params) {
+    const syntheticSocket = {
+      send: () => {
+      },
+      close: () => {
+      },
+      on: () => {
+      },
+      readyState: 1
+    };
+    return await this.executeRequest(
+      { id: `rest-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`, method, params },
+      syntheticSocket
+    );
+  }
   async executeRequest(request, socket) {
     const params = request.params ?? {};
     if (request.method.startsWith("observability:")) {
@@ -374961,6 +375551,61 @@ var WebSocketGatewayAdapter = class {
         }
         return { session };
       }
+      case "history:search": {
+        const bridge = this.options.historyBridge;
+        if (!bridge?.getAllSessions) {
+          throw new WebSocketRpcError(
+            "METHOD_NOT_FOUND",
+            "history:search is not available on this gateway (no history bridge)."
+          );
+        }
+        const { searchChatHistory: searchChatHistory2 } = await Promise.resolve().then(() => (init_historySearch(), historySearch_exports));
+        const sessions = await bridge.getAllSessions();
+        const query = this.readStringParam(params, "query");
+        const wholeWord = params?.wholeWord === true;
+        const includeTitles = params?.includeTitles !== false;
+        const sessionLimit = typeof params?.sessionLimit === "number" ? params.sessionLimit : void 0;
+        const snippetLimit = typeof params?.snippetLimit === "number" ? params.snippetLimit : void 0;
+        return searchChatHistory2(sessions, query, { wholeWord, includeTitles, sessionLimit, snippetLimit });
+      }
+      case "settings:listBackups": {
+        const bridge = this.options.settingsBridge;
+        if (!bridge?.listBackups) {
+          throw new WebSocketRpcError("METHOD_NOT_FOUND", "settings backups are not available on this gateway.");
+        }
+        return { backups: await bridge.listBackups() };
+      }
+      case "settings:restoreBackup": {
+        const bridge = this.options.settingsBridge;
+        if (!bridge?.restoreBackup) {
+          throw new WebSocketRpcError("METHOD_NOT_FOUND", "settings backups are not available on this gateway.");
+        }
+        const name = this.readStringParam(params, "name");
+        const result = await bridge.restoreBackup(name);
+        if (result && typeof result === "object" && "ok" in result && !result.ok) {
+          throw new WebSocketRpcError("BAD_REQUEST", String(result.error ?? "restore failed"));
+        }
+        return { restored: name };
+      }
+      case "settings:export": {
+        const bridge = this.options.settingsBridge;
+        if (!bridge?.export) {
+          throw new WebSocketRpcError("METHOD_NOT_FOUND", "settings export is not available on this gateway.");
+        }
+        return { content: await bridge.export() };
+      }
+      case "settings:import": {
+        const bridge = this.options.settingsBridge;
+        if (!bridge?.import) {
+          throw new WebSocketRpcError("METHOD_NOT_FOUND", "settings import is not available on this gateway.");
+        }
+        const content = this.readStringParam(params, "content");
+        const result = await bridge.import(content);
+        if (result && typeof result === "object" && "ok" in result && !result.ok) {
+          throw new WebSocketRpcError("BAD_REQUEST", String(result.error ?? "import failed"));
+        }
+        return { imported: true };
+      }
       case "agent:exportHistory": {
         const bridge = this.options.agentBridge;
         if (!bridge?.exportHistory) {
@@ -383611,7 +384256,7 @@ var NodeMcpToolService = class extends McpRuntimeCore {
 
 // ../../packages/backend/src/adapters/node/NodeSkillService.ts
 var import_node_path16 = __toESM(require("node:path"), 1);
-var import_node_os3 = __toESM(require("node:os"), 1);
+var import_node_os4 = __toESM(require("node:os"), 1);
 
 // ../../packages/backend/src/skills/FileSkillStore.ts
 var import_promises9 = __toESM(require("node:fs/promises"), 1);
@@ -383916,10 +384561,10 @@ ${files}`;
 
 // ../../packages/backend/src/skills/scanRoots.ts
 var import_node_path15 = __toESM(require("node:path"), 1);
-var import_node_os2 = __toESM(require("node:os"), 1);
+var import_node_os3 = __toESM(require("node:os"), 1);
 function resolveDefaultSkillScanRoots(options) {
   const primaryRoot = import_node_path15.default.resolve(options.primaryRoot);
-  const homeDir = (options.homeDir || import_node_os2.default.homedir() || "").trim();
+  const homeDir = (options.homeDir || import_node_os3.default.homedir() || "").trim();
   const platform2 = options.platform || process.platform;
   const appData = (options.appData || process.env.APPDATA || "").trim();
   const codexHome = (options.codexHome || process.env.CODEX_HOME || "").trim();
@@ -383991,7 +384636,7 @@ var NodeSkillService = class {
   resolveScanRoots() {
     return resolveDefaultSkillScanRoots({
       primaryRoot: this.skillsDir,
-      homeDir: import_node_os3.default.homedir(),
+      homeDir: import_node_os4.default.homedir(),
       platform: process.platform,
       appData: process.env.APPDATA,
       codexHome: process.env.CODEX_HOME
@@ -386114,6 +386759,367 @@ var SessionLogService = class _SessionLogService {
 
 // ../../packages/backend/src/runtimes/gybackend/startGyBackend.ts
 init_schedulerService();
+
+// ../../packages/backend/src/services/settings/settingsBackup.ts
+var BACKUP_PREFIX = "settings-backup-";
+var BACKUP_SUFFIX = ".json";
+function backupNameFor(date6) {
+  const pad = (n2, w = 2) => String(n2).padStart(w, "0");
+  return `${BACKUP_PREFIX}${date6.getUTCFullYear()}${pad(date6.getUTCMonth() + 1)}${pad(date6.getUTCDate())}-${pad(date6.getUTCHours())}${pad(date6.getUTCMinutes())}${pad(date6.getUTCSeconds())}${BACKUP_SUFFIX}`;
+}
+function parseBackupName(name) {
+  if (!name.startsWith(BACKUP_PREFIX) || !name.endsWith(BACKUP_SUFFIX)) return null;
+  const stem = name.slice(BACKUP_PREFIX.length, -BACKUP_SUFFIX.length);
+  const m2 = stem.match(/^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})$/);
+  if (!m2) return null;
+  const [, y, mo, d, h, mi, s] = m2.map(Number);
+  const date6 = new Date(Date.UTC(y, mo - 1, d, h, mi, s));
+  return Number.isNaN(date6.getTime()) ? null : date6;
+}
+var SettingsBackupService = class {
+  constructor(io, opts = {}) {
+    this.io = io;
+    this.keep = opts.keep ?? 20;
+    this.now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  keep;
+  now;
+  /** Take a backup of the CURRENT settings content, then rotate. */
+  backup() {
+    const content = this.io.read();
+    const name = backupNameFor(this.now());
+    this.io.writeBackup(name, content);
+    this.rotate();
+    return { name, at: this.now(), size: content.length };
+  }
+  /** Delete oldest backups beyond the keep limit. Returns names removed. */
+  rotate() {
+    const names = this.io.listBackups().map((n2) => ({ n: n2, at: parseBackupName(n2) })).filter((x) => x.at !== null).sort((a, b) => a.at.getTime() - b.at.getTime());
+    const excess = names.slice(0, Math.max(0, names.length - this.keep));
+    for (const { n: n2 } of excess) this.io.deleteBackup(n2);
+    return excess.map((x) => x.n);
+  }
+  /** List backups, newest first. */
+  list() {
+    return this.io.listBackups().map((n2) => ({ n: n2, at: parseBackupName(n2) })).filter((x) => x.at !== null).sort((a, b) => b.at.getTime() - a.at.getTime()).map(({ n: n2, at }) => ({ name: n2, at, size: this.io.readBackup(n2).length }));
+  }
+  /** Restore a backup by name (writes it to the live settings path). */
+  restore(name) {
+    if (!this.io.listBackups().includes(name)) {
+      return { ok: false, error: `no backup named "${name}"` };
+    }
+    this.backup();
+    const content = this.io.readBackup(name);
+    this.io.write(content);
+    return { ok: true };
+  }
+  /** Export the current settings as a portable JSON string. */
+  export() {
+    return this.io.read();
+  }
+  /** Validate + import settings JSON. Refuses non-object / empty content. */
+  import(content) {
+    const trimmed = (content ?? "").trim();
+    if (!trimmed) return { ok: false, error: "empty settings content" };
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (e) {
+      return { ok: false, error: `invalid JSON: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { ok: false, error: "settings content must be a JSON object" };
+    }
+    this.backup();
+    this.io.write(trimmed);
+    return { ok: true };
+  }
+};
+
+// ../../packages/backend/src/services/terminal/idleTimeout.ts
+var IdleTimeoutService = class {
+  idleMs;
+  protectedIds;
+  now;
+  lastActivity = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.idleMs = Math.max(0, (opts.idleMinutes ?? 30) * 6e4);
+    this.protectedIds = new Set(opts.protectedIds ?? []);
+    this.now = opts.now ?? (() => Date.now());
+  }
+  /** Record activity for a terminal. */
+  touch(terminalId) {
+    this.lastActivity.set(terminalId, this.now());
+  }
+  /** Register a terminal (starts its idle clock). */
+  register(terminalId) {
+    if (!this.lastActivity.has(terminalId)) {
+      this.lastActivity.set(terminalId, this.now());
+    }
+  }
+  /** Forget a terminal (on close). */
+  forget(terminalId) {
+    this.lastActivity.delete(terminalId);
+  }
+  /** Is this terminal idle past the threshold? */
+  isIdle(terminalId) {
+    if (this.protectedIds.has(terminalId)) return false;
+    const last = this.lastActivity.get(terminalId);
+    if (last === void 0) return false;
+    return this.now() - last >= this.idleMs;
+  }
+  /** All currently-idle terminals (among the known ones). */
+  idleTerminals(knownIds) {
+    const t = this.now();
+    const out = [];
+    for (const id of knownIds) {
+      if (this.protectedIds.has(id)) continue;
+      const last = this.lastActivity.get(id);
+      if (last === void 0) continue;
+      const idleMin = (t - last) / 6e4;
+      if (idleMin * 6e4 >= this.idleMs) {
+        out.push({ terminalId: id, idleMinutes: Math.round(idleMin * 10) / 10 });
+      }
+    }
+    return out;
+  }
+  /** Configure the threshold at runtime. */
+  setIdleMinutes(minutes) {
+    this.idleMs = Math.max(0, minutes * 6e4);
+  }
+  get idleMinutes() {
+    return this.idleMs / 6e4;
+  }
+};
+
+// ../../packages/backend/src/services/Gateway/restApi.ts
+function matchRestRoute(routes, method, path32) {
+  const normalized = path32.replace(/\/+$/, "") || "/";
+  for (const route of routes) {
+    if (route.method !== method.toUpperCase()) continue;
+    const patternParts = route.path.split("/").filter(Boolean);
+    const pathParts = normalized.split("/").filter(Boolean);
+    if (patternParts.length !== pathParts.length) continue;
+    const params = {};
+    let matched = true;
+    for (let i = 0; i < patternParts.length; i++) {
+      const p = patternParts[i];
+      if (p.startsWith(":")) {
+        params[p.slice(1)] = decodeURIComponent(pathParts[i]);
+      } else if (p !== pathParts[i]) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) return { route, pathParams: params };
+  }
+  return null;
+}
+function defaultRestRoutes() {
+  return [
+    {
+      method: "GET",
+      path: "/api/v1/health",
+      gatewayMethod: "gateway:ping",
+      description: "Liveness check"
+    },
+    {
+      method: "GET",
+      path: "/api/v1/methods",
+      gatewayMethod: "gateway:describe",
+      description: "List all gateway methods (self-describing)"
+    },
+    {
+      method: "GET",
+      path: "/api/v1/terminals",
+      gatewayMethod: "terminal:list",
+      description: "List terminal tabs"
+    },
+    {
+      method: "GET",
+      path: "/api/v1/sessions",
+      gatewayMethod: "session:list",
+      description: "List chat sessions"
+    },
+    {
+      method: "GET",
+      path: "/api/v1/skills",
+      gatewayMethod: "skills:getAll",
+      description: "List loaded skills"
+    },
+    {
+      method: "GET",
+      path: "/api/v1/observability/metrics",
+      gatewayMethod: "observability:metricsPrometheus",
+      description: "Host metrics (Prometheus text or summary)"
+    },
+    {
+      method: "GET",
+      path: "/api/v1/observability/dashboard",
+      gatewayMethod: "observability:liveDashboardState",
+      description: "Live dashboard state"
+    },
+    {
+      method: "GET",
+      path: "/api/v1/observability/apm",
+      gatewayMethod: "observability:apmSummary",
+      description: "APM summary (LLM + app traces)"
+    },
+    {
+      method: "GET",
+      path: "/api/v1/history/search",
+      gatewayMethod: "history:search",
+      description: "Cross-session history search (?q=...)",
+      buildParams: (_p, body) => {
+        const b = body ?? {};
+        return { query: b.q ?? b.query ?? "" };
+      }
+    },
+    {
+      method: "POST",
+      path: "/api/v1/terminals/:id/write",
+      gatewayMethod: "terminal:write",
+      description: "Write data to a terminal tab",
+      buildParams: (p, body) => {
+        const b = body ?? {};
+        return { terminalId: p.id, data: b.data ?? "" };
+      }
+    },
+    {
+      method: "GET",
+      path: "/api/v1/terminals/:id/buffer",
+      gatewayMethod: "terminal:getBufferDelta",
+      description: "Read a terminal tab output delta",
+      buildParams: (p, body) => {
+        const b = body ?? {};
+        return { terminalId: p.id, fromOffset: b.fromOffset ?? 0 };
+      }
+    },
+    {
+      method: "POST",
+      path: "/api/v1/sessions/:id/chat",
+      gatewayMethod: "agent:startTask",
+      description: "Send a message to the agent (blocking)",
+      buildParams: (p, body) => {
+        const b = body ?? {};
+        return { sessionId: p.id, userInput: b.message ?? b.userInput ?? "" };
+      }
+    },
+    {
+      method: "POST",
+      path: "/api/v1/rpc",
+      gatewayMethod: "",
+      description: "Escape hatch: dispatch any gateway method",
+      buildParams: (_p, body) => {
+        const b = body ?? {};
+        return { __rpcMethod: b.method ?? "", ...b.params ?? {} };
+      }
+    }
+  ];
+}
+async function handleRestRequest(routes, dispatch, req) {
+  const match = matchRestRoute(routes, req.method, req.path);
+  if (!match) {
+    return {
+      status: 404,
+      body: { error: "not_found", message: `No REST route for ${req.method} ${req.path}` }
+    };
+  }
+  let gatewayMethod = match.route.gatewayMethod;
+  let params;
+  if (gatewayMethod === "") {
+    const raw = req.body ?? {};
+    if (!raw.method) {
+      return { status: 400, body: { error: "bad_request", message: 'POST /api/v1/rpc needs {"method": "...", "params": {...}}' } };
+    }
+    gatewayMethod = raw.method;
+    params = raw.params ?? {};
+  } else {
+    params = match.route.buildParams?.(match.pathParams, req.body) ?? match.pathParams;
+  }
+  try {
+    const result = await dispatch(gatewayMethod, params);
+    return { status: 200, body: result ?? { ok: true } };
+  } catch (error40) {
+    const message = error40 instanceof Error ? error40.message : String(error40);
+    const status = /not found|no terminal|no session|no playbook/i.test(message) ? 404 : /invalid|bad request|must be|requires/i.test(message) ? 400 : 500;
+    return { status, body: { error: "gateway_error", message } };
+  }
+}
+
+// ../../packages/backend/src/services/Gateway/gatewayRateLimit.ts
+var GatewayRateLimiter = class {
+  capacity;
+  refillPerSecond;
+  authFailureLimit;
+  authLockoutMs;
+  now;
+  buckets = /* @__PURE__ */ new Map();
+  authTrackers = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.capacity = opts.capacity ?? 60;
+    this.refillPerSecond = opts.refillPerSecond ?? 1;
+    this.authFailureLimit = opts.authFailureLimit ?? 5;
+    this.authLockoutMs = opts.authLockoutMs ?? 6e4;
+    this.now = opts.now ?? (() => Date.now());
+  }
+  refill(bucket) {
+    const t = this.now();
+    const elapsed2 = (t - bucket.lastRefill) / 1e3;
+    if (elapsed2 <= 0) return;
+    bucket.tokens = Math.min(this.capacity, bucket.tokens + elapsed2 * this.refillPerSecond);
+    bucket.lastRefill = t;
+  }
+  /** Check (and consume) one token for a client. */
+  check(clientKey) {
+    const t = this.now();
+    const bucket = this.buckets.get(clientKey) ?? { tokens: this.capacity, lastRefill: t };
+    this.refill(bucket);
+    this.buckets.set(clientKey, bucket);
+    if (bucket.tokens >= 1) {
+      bucket.tokens -= 1;
+      return { allowed: true, remaining: Math.floor(bucket.tokens) };
+    }
+    const msToNextToken = Math.ceil((1 - bucket.tokens) / this.refillPerSecond * 1e3);
+    return { allowed: false, remaining: 0, retryAfterMs: msToNextToken, reason: "rate-limited" };
+  }
+  /** Record a failed authentication attempt; returns the lockout decision. */
+  recordAuthFailure(clientKey) {
+    const t = this.now();
+    const tracker = this.authTrackers.get(clientKey) ?? { failures: 0, lockedUntil: 0 };
+    tracker.failures += 1;
+    if (tracker.failures >= this.authFailureLimit) {
+      tracker.lockedUntil = t + this.authLockoutMs;
+      tracker.failures = 0;
+    }
+    this.authTrackers.set(clientKey, tracker);
+    if (t < tracker.lockedUntil) {
+      return { allowed: false, remaining: 0, retryAfterMs: tracker.lockedUntil - t, reason: "locked-out" };
+    }
+    return { allowed: true, remaining: this.authFailureLimit - tracker.failures };
+  }
+  /** Clear auth failures on successful authentication. */
+  recordAuthSuccess(clientKey) {
+    this.authTrackers.delete(clientKey);
+  }
+  /** Is this client currently locked out? */
+  isLockedOut(clientKey) {
+    const tracker = this.authTrackers.get(clientKey);
+    if (!tracker) return false;
+    return this.now() < tracker.lockedUntil;
+  }
+  /** Drop state for a client (on disconnect). */
+  forget(clientKey) {
+    this.buckets.delete(clientKey);
+    this.authTrackers.delete(clientKey);
+  }
+  /** Number of tracked clients (for monitoring/tests). */
+  get clientCount() {
+    return this.buckets.size;
+  }
+};
+
+// ../../packages/backend/src/runtimes/gybackend/startGyBackend.ts
 init_scheduledTaskRunner();
 
 // ../../packages/backend/src/services/history/HistoryStorageMigration.ts
@@ -393608,11 +394614,11 @@ function createObservability(deps) {
   const policyEngine = new AgtPolicyEngine({
     loadPolicy: async () => {
       const req = (0, import_node_module5.createRequire)(typeof __filename !== "undefined" ? __filename : import_meta7.url);
-      const fs22 = req("node:fs");
+      const fs23 = req("node:fs");
       const path32 = req("node:path");
       const policyPath = path32.join(".", "policy.yaml");
-      if (fs22.existsSync(policyPath)) {
-        return parsePolicyYaml(fs22.readFileSync(policyPath, "utf8"));
+      if (fs23.existsSync(policyPath)) {
+        return parsePolicyYaml(fs23.readFileSync(policyPath, "utf8"));
       }
       return {
         name: "rterm-default",
@@ -393654,18 +394660,18 @@ function createObservability(deps) {
   const scanRoots = [pluginScanRoot, "./plugins"];
   try {
     const req = (0, import_node_module5.createRequire)(typeof __filename !== "undefined" ? __filename : import_meta7.url);
-    const fs22 = req("node:fs");
-    if (fs22.existsSync(bundlePluginRoot)) scanRoots.push(bundlePluginRoot);
+    const fs23 = req("node:fs");
+    if (fs23.existsSync(bundlePluginRoot)) scanRoots.push(bundlePluginRoot);
   } catch {
   }
   try {
     const req = (0, import_node_module5.createRequire)(typeof __filename !== "undefined" ? __filename : import_meta7.url);
-    const fs22 = req("node:fs");
+    const fs23 = req("node:fs");
     const path32 = req("node:path");
     const resourcesPath = process.resourcesPath;
     if (resourcesPath) {
       const resourcesPlugins = path32.join(resourcesPath, "plugins");
-      if (fs22.existsSync(resourcesPlugins)) scanRoots.push(resourcesPlugins);
+      if (fs23.existsSync(resourcesPlugins)) scanRoots.push(resourcesPlugins);
     }
   } catch {
   }
@@ -396631,434 +397637,581 @@ async function startGyBackend() {
     gatewayService.broadcastRaw("skills:updated", result.skills);
     gatewayService.broadcastRaw("memory:updated", result.memory);
   };
-  const wsGatewayControlService = new WebSocketGatewayControlService({
-    createAdapter: (host, port, ipFilter) => new WebSocketGatewayAdapter(gatewayService, {
-      host,
-      port,
-      accessTokenAuth: {
-        verifyToken: (token) => accessTokenService.verifyToken(token),
-        allowLocalhostWithoutToken: true
+  const gatewayRateLimiter = new GatewayRateLimiter({
+    capacity: Number(import_node_process2.default.env.RTERM_RATE_LIMIT_BURST ?? 60) || 60,
+    refillPerSecond: Number(import_node_process2.default.env.RTERM_RATE_LIMIT_REFILL ?? 1) || 1,
+    authFailureLimit: 5,
+    authLockoutMs: 6e4
+  });
+  const settingsDir = import_node_path28.default.dirname(settingsService.getSettingsPath?.() ?? "");
+  const backupsDir = settingsDir ? import_node_path28.default.join(settingsDir, "backups") : "";
+  const settingsBackupService = new SettingsBackupService(
+    backupsDir ? {
+      read: () => import_node_fs12.default.readFileSync(settingsService.getSettingsPath(), "utf8"),
+      write: (c) => import_node_fs12.default.writeFileSync(settingsService.getSettingsPath(), c),
+      listBackups: () => import_node_fs12.default.existsSync(backupsDir) ? import_node_fs12.default.readdirSync(backupsDir) : [],
+      readBackup: (n2) => import_node_fs12.default.readFileSync(import_node_path28.default.join(backupsDir, n2), "utf8"),
+      writeBackup: (n2, c) => {
+        import_node_fs12.default.mkdirSync(backupsDir, { recursive: true });
+        import_node_fs12.default.writeFileSync(import_node_path28.default.join(backupsDir, n2), c);
       },
-      ipFilter,
-      // Browser dashboard on the SAME port as the WS gateway: /dashboard serves
-      // a live page (WS push via observability:liveDashboardSubscribe, with a
-      // /dashboard/json polling fallback). Auth mirrors the WS gateway —
-      // loopback open, remote needs a valid access token.
-      httpRoutes: [
-        {
-          path: "/dashboard",
-          handler: async (req, res) => {
-            if (!await dashboardHttpAuthorized(req, (t) => accessTokenService.verifyToken(t))) {
-              res.writeHead(401, { "content-type": "text/plain; charset=utf-8" });
-              res.end("missing/invalid access token");
-              return;
+      deleteBackup: (n2) => {
+        const p = import_node_path28.default.join(backupsDir, n2);
+        if (import_node_fs12.default.existsSync(p)) import_node_fs12.default.unlinkSync(p);
+      }
+    } : { read: () => "", write: () => {
+    }, listBackups: () => [], readBackup: () => "", writeBackup: () => {
+    }, deleteBackup: () => {
+    } },
+    { keep: 20 }
+  );
+  const originalSetSettings = settingsService.setSettings.bind(settingsService);
+  settingsService.setSettings = ((next) => {
+    try {
+      settingsBackupService.backup();
+    } catch {
+    }
+    return originalSetSettings(next);
+  });
+  const idleTimeoutService = new IdleTimeoutService({
+    idleMinutes: Number(import_node_process2.default.env.RTERM_IDLE_TIMEOUT_MINUTES ?? 30) || 30,
+    protectedIds: [import_node_process2.default.env.GYBACKEND_TERMINAL_ID || "local-main"]
+  });
+  for (const t of terminalService.getAllTerminals()) idleTimeoutService.register(t.id);
+  terminalService.onTerminalCreated?.((id) => idleTimeoutService.register(id));
+  terminalService.onTerminalData?.((id) => idleTimeoutService.touch(id));
+  terminalService.onTerminalClosed?.((id) => idleTimeoutService.forget(id));
+  const idleSweeper = setInterval(() => {
+    try {
+      const idle = idleTimeoutService.idleTerminals(terminalService.getAllTerminals().map((t) => t.id));
+      for (const { terminalId, idleMinutes } of idle) {
+        console.log(`[gybackend] closing idle terminal ${terminalId} (${idleMinutes}min idle)`);
+        try {
+          terminalService.kill(terminalId);
+        } catch {
+        }
+        idleTimeoutService.forget(terminalId);
+      }
+    } catch {
+    }
+  }, 6e4);
+  if (typeof idleSweeper.unref === "function") idleSweeper.unref();
+  let restDispatchTarget = null;
+  const restDispatch = async (method, params) => {
+    const target = restDispatchTarget;
+    if (!target?.handleRequest) {
+      throw new Error("REST API is not ready yet (gateway still starting)");
+    }
+    return await target.handleRequest(method, params);
+  };
+  const buildRestHttpRoutesSync = (opts) => {
+    const routes = defaultRestRoutes();
+    const staticRoutes = routes.filter((r) => !r.path.includes(":")).map((route) => ({
+      path: route.path,
+      handler: makeRestHandler(routes, opts)
+    }));
+    return staticRoutes;
+  };
+  const makeRestHandler = (routes, opts) => {
+    return async (req, res) => {
+      const r = req;
+      const s = res;
+      try {
+        if (!await opts.isAuthorized(r)) {
+          s.writeHead?.(401, { "content-type": "application/json" });
+          s.end?.(JSON.stringify({ error: "unauthorized" }));
+          return;
+        }
+        const url2 = new URL(r.url ?? "/", "http://localhost");
+        const body = r.method === "POST" ? await readJsonBody(r) : Object.fromEntries(url2.searchParams.entries());
+        const result = await handleRestRequest(routes, opts.dispatch, {
+          method: r.method ?? "GET",
+          path: url2.pathname,
+          body
+        });
+        s.writeHead?.(result.status, { "content-type": "application/json" });
+        s.end?.(JSON.stringify(result.body));
+      } catch (e) {
+        s.writeHead?.(500, { "content-type": "application/json" });
+        s.end?.(JSON.stringify({ error: "internal", message: e instanceof Error ? e.message : String(e) }));
+      }
+    };
+  };
+  const readJsonBody = (req) => new Promise((resolve2) => {
+    let data = "";
+    req.on?.("data", (d) => {
+      data += String(d ?? "");
+    });
+    req.on?.("end", () => {
+      try {
+        resolve2(data ? JSON.parse(data) : {});
+      } catch {
+        resolve2({});
+      }
+    });
+  });
+  const wsGatewayControlService = new WebSocketGatewayControlService({
+    createAdapter: (host, port, ipFilter) => {
+      const adapter = new WebSocketGatewayAdapter(gatewayService, {
+        host,
+        port,
+        accessTokenAuth: {
+          verifyToken: (token) => accessTokenService.verifyToken(token),
+          allowLocalhostWithoutToken: true
+        },
+        // v3.2.18: per-client rate limiting (token bucket + auth lockout).
+        rateLimiter: gatewayRateLimiter,
+        ipFilter,
+        // Browser dashboard on the SAME port as the WS gateway: /dashboard serves
+        // a live page (WS push via observability:liveDashboardSubscribe, with a
+        // /dashboard/json polling fallback). Auth mirrors the WS gateway —
+        // loopback open, remote needs a valid access token.
+        // v3.2.18: REST API routes (/api/v1/*) are prepended so curl/CI can
+        // drive the gateway without a WS client.
+        httpRoutes: [
+          ...buildRestHttpRoutesSync({
+            isAuthorized: (req) => dashboardHttpAuthorized(req, (t) => accessTokenService.verifyToken(t)),
+            dispatch: restDispatch
+          }),
+          {
+            path: "/dashboard",
+            handler: async (req, res) => {
+              if (!await dashboardHttpAuthorized(req, (t) => accessTokenService.verifyToken(t))) {
+                res.writeHead(401, { "content-type": "text/plain; charset=utf-8" });
+                res.end("missing/invalid access token");
+                return;
+              }
+              const state = await observability.dashboard.state();
+              res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+              res.end(
+                renderLiveDashboardHtml(state, {
+                  title: "RTerm \xB7 Unified Dashboard",
+                  dataUrl: "/dashboard/json"
+                })
+              );
+            }
+          },
+          {
+            path: "/dashboard/json",
+            handler: async (req, res) => {
+              if (!await dashboardHttpAuthorized(req, (t) => accessTokenService.verifyToken(t))) {
+                res.writeHead(401, { "content-type": "text/plain; charset=utf-8" });
+                res.end("missing/invalid access token");
+                return;
+              }
+              const state = await observability.dashboard.state();
+              res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+              res.end(JSON.stringify(state));
             }
-            const state = await observability.dashboard.state();
-            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-            res.end(
-              renderLiveDashboardHtml(state, {
-                title: "RTerm \xB7 Unified Dashboard",
-                dataUrl: "/dashboard/json"
-              })
-            );
           }
-        },
-        {
-          path: "/dashboard/json",
-          handler: async (req, res) => {
-            if (!await dashboardHttpAuthorized(req, (t) => accessTokenService.verifyToken(t))) {
-              res.writeHead(401, { "content-type": "text/plain; charset=utf-8" });
-              res.end("missing/invalid access token");
-              return;
+        ],
+        terminalBridge: {
+          listTerminals: () => terminalService.getDisplayTerminals().map((terminal) => ({
+            id: terminal.id,
+            title: terminal.title,
+            type: terminal.type,
+            cols: terminal.cols,
+            rows: terminal.rows,
+            runtimeState: terminal.runtimeState,
+            lastExitCode: terminal.lastExitCode,
+            monitorIdentity: terminalService.getMonitorIdentity(terminal.id) ?? void 0
+          })),
+          createTab: async (config2) => {
+            const snapshot = terminalService.getDisplayTerminals();
+            const normalized = createAutoTerminalConfig(snapshot, config2);
+            const tab = await terminalService.createTerminal(normalized);
+            return { id: tab.id };
+          },
+          write: async (terminalId, data) => {
+            terminalService.write(terminalId, data);
+          },
+          writePaths: async (terminalId, paths) => {
+            terminalService.writePaths(terminalId, paths);
+          },
+          resize: async (terminalId, cols, rows) => {
+            terminalService.resize(terminalId, cols, rows);
+          },
+          kill: async (terminalId) => {
+            if (terminalService.getDisplayTerminals().length <= 1) {
+              throw new Error("Cannot close the last terminal tab.");
             }
-            const state = await observability.dashboard.state();
-            res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-            res.end(JSON.stringify(state));
+            terminalService.kill(terminalId);
+          },
+          reconnect: async (terminalId) => {
+            const tab = await terminalService.reconnectTerminal(terminalId);
+            return { id: tab.id };
+          },
+          setTitle: async (terminalId, title) => {
+            terminalService.setTitle(terminalId, title);
+          },
+          setSelection: async (terminalId, selectionText) => {
+            terminalService.setSelection(terminalId, selectionText);
+          },
+          getBufferDelta: async (terminalId, fromOffset) => {
+            const data = terminalService.getBufferDelta(terminalId, fromOffset);
+            const offset = terminalService.getCurrentOffset(terminalId);
+            return { data, offset };
+          },
+          generateCommandDraft: async (terminalId, prompt, profileId) => {
+            return await terminalCommandDraftService.generateCommandDraft({
+              terminalId,
+              prompt,
+              profileId
+            });
           }
-        }
-      ],
-      terminalBridge: {
-        listTerminals: () => terminalService.getDisplayTerminals().map((terminal) => ({
-          id: terminal.id,
-          title: terminal.title,
-          type: terminal.type,
-          cols: terminal.cols,
-          rows: terminal.rows,
-          runtimeState: terminal.runtimeState,
-          lastExitCode: terminal.lastExitCode,
-          monitorIdentity: terminalService.getMonitorIdentity(terminal.id) ?? void 0
-        })),
-        createTab: async (config2) => {
-          const snapshot = terminalService.getDisplayTerminals();
-          const normalized = createAutoTerminalConfig(snapshot, config2);
-          const tab = await terminalService.createTerminal(normalized);
-          return { id: tab.id };
-        },
-        write: async (terminalId, data) => {
-          terminalService.write(terminalId, data);
         },
-        writePaths: async (terminalId, paths) => {
-          terminalService.writePaths(terminalId, paths);
-        },
-        resize: async (terminalId, cols, rows) => {
-          terminalService.resize(terminalId, cols, rows);
-        },
-        kill: async (terminalId) => {
-          if (terminalService.getDisplayTerminals().length <= 1) {
-            throw new Error("Cannot close the last terminal tab.");
+        filesystemBridge: {
+          listDirectory: async (terminalId, dirPath) => {
+            return await fileSystemService.listDirectory(terminalId, dirPath);
+          },
+          readTextFile: async (terminalId, filePath, options) => {
+            return await fileSystemService.readTextFile(
+              terminalId,
+              filePath,
+              options
+            );
+          },
+          readFileBase64: async (terminalId, filePath, options) => {
+            return await fileSystemService.readFileBase64(
+              terminalId,
+              filePath,
+              options
+            );
+          },
+          writeTextFile: async (terminalId, filePath, content) => {
+            await fileSystemService.writeTextFile(
+              terminalId,
+              filePath,
+              content
+            );
+          },
+          writeFileBase64: async (terminalId, filePath, contentBase64, options) => {
+            await fileSystemService.writeFileBase64(
+              terminalId,
+              filePath,
+              contentBase64,
+              options
+            );
+          },
+          transferEntries: async (sourceTerminalId, sourcePaths, targetTerminalId, targetDirPath, options) => {
+            return await fileSystemService.transferEntries(
+              sourceTerminalId,
+              sourcePaths,
+              targetTerminalId,
+              targetDirPath,
+              options
+            );
+          },
+          startTransfer: async (input) => {
+            return fileTransferService.startTransfer(input);
+          },
+          getTransfer: async (transferId) => {
+            return fileTransferService.getTransfer(transferId);
+          },
+          listTransfers: async (options) => {
+            return fileTransferService.listTransfers(options);
+          },
+          cancelTransfer: async (transferId) => {
+            return fileTransferService.cancelTransfer(transferId);
+          },
+          cancelTransferTask: async (transferId) => {
+            return fileTransferService.cancelTransfer(transferId);
+          },
+          createDirectory: async (terminalId, dirPath) => {
+            await fileSystemService.createDirectory(terminalId, dirPath);
+          },
+          createFile: async (terminalId, filePath) => {
+            await fileSystemService.createFile(terminalId, filePath);
+          },
+          deletePath: async (terminalId, targetPath, options) => {
+            await fileSystemService.deletePath(terminalId, targetPath, options);
+          },
+          renamePath: async (terminalId, sourcePath, targetPath) => {
+            await fileSystemService.renamePath(
+              terminalId,
+              sourcePath,
+              targetPath
+            );
           }
-          terminalService.kill(terminalId);
-        },
-        reconnect: async (terminalId) => {
-          const tab = await terminalService.reconnectTerminal(terminalId);
-          return { id: tab.id };
-        },
-        setTitle: async (terminalId, title) => {
-          terminalService.setTitle(terminalId, title);
-        },
-        setSelection: async (terminalId, selectionText) => {
-          terminalService.setSelection(terminalId, selectionText);
-        },
-        getBufferDelta: async (terminalId, fromOffset) => {
-          const data = terminalService.getBufferDelta(terminalId, fromOffset);
-          const offset = terminalService.getCurrentOffset(terminalId);
-          return { data, offset };
-        },
-        generateCommandDraft: async (terminalId, prompt, profileId) => {
-          return await terminalCommandDraftService.generateCommandDraft({
-            terminalId,
-            prompt,
-            profileId
-          });
-        }
-      },
-      filesystemBridge: {
-        listDirectory: async (terminalId, dirPath) => {
-          return await fileSystemService.listDirectory(terminalId, dirPath);
-        },
-        readTextFile: async (terminalId, filePath, options) => {
-          return await fileSystemService.readTextFile(
-            terminalId,
-            filePath,
-            options
-          );
-        },
-        readFileBase64: async (terminalId, filePath, options) => {
-          return await fileSystemService.readFileBase64(
-            terminalId,
-            filePath,
-            options
-          );
-        },
-        writeTextFile: async (terminalId, filePath, content) => {
-          await fileSystemService.writeTextFile(
-            terminalId,
-            filePath,
-            content
-          );
-        },
-        writeFileBase64: async (terminalId, filePath, contentBase64, options) => {
-          await fileSystemService.writeFileBase64(
-            terminalId,
-            filePath,
-            contentBase64,
-            options
-          );
-        },
-        transferEntries: async (sourceTerminalId, sourcePaths, targetTerminalId, targetDirPath, options) => {
-          return await fileSystemService.transferEntries(
-            sourceTerminalId,
-            sourcePaths,
-            targetTerminalId,
-            targetDirPath,
-            options
-          );
-        },
-        startTransfer: async (input) => {
-          return fileTransferService.startTransfer(input);
-        },
-        getTransfer: async (transferId) => {
-          return fileTransferService.getTransfer(transferId);
-        },
-        listTransfers: async (options) => {
-          return fileTransferService.listTransfers(options);
-        },
-        cancelTransfer: async (transferId) => {
-          return fileTransferService.cancelTransfer(transferId);
-        },
-        cancelTransferTask: async (transferId) => {
-          return fileTransferService.cancelTransfer(transferId);
-        },
-        createDirectory: async (terminalId, dirPath) => {
-          await fileSystemService.createDirectory(terminalId, dirPath);
         },
-        createFile: async (terminalId, filePath) => {
-          await fileSystemService.createFile(terminalId, filePath);
-        },
-        deletePath: async (terminalId, targetPath, options) => {
-          await fileSystemService.deletePath(terminalId, targetPath, options);
-        },
-        renamePath: async (terminalId, sourcePath, targetPath) => {
-          await fileSystemService.renamePath(
-            terminalId,
-            sourcePath,
-            targetPath
-          );
-        }
-      },
-      profileBridge: {
-        getProfiles: () => {
-          const snapshot = settingsService.getSettings();
-          const modelNameById = new Map(
-            snapshot.models.items.map((item) => [item.id, item.model])
-          );
-          return {
-            activeProfileId: snapshot.models.activeProfileId,
-            profiles: snapshot.models.profiles.map((profile) => ({
-              id: profile.id,
-              name: profile.name,
-              globalModelId: profile.globalModelId,
-              modelName: modelNameById.get(profile.globalModelId)
-            }))
-          };
-        },
-        setActiveProfile: (profileId) => {
-          const snapshot = settingsService.getSettings();
-          const exists = snapshot.models.profiles.some(
-            (profile) => profile.id === profileId
-          );
-          if (!exists) {
-            throw new Error(`Profile not found: ${profileId}`);
-          }
-          settingsService.setSettings({
-            models: {
-              items: snapshot.models.items,
-              profiles: snapshot.models.profiles,
-              activeProfileId: profileId
+        profileBridge: {
+          getProfiles: () => {
+            const snapshot = settingsService.getSettings();
+            const modelNameById = new Map(
+              snapshot.models.items.map((item) => [item.id, item.model])
+            );
+            return {
+              activeProfileId: snapshot.models.activeProfileId,
+              profiles: snapshot.models.profiles.map((profile) => ({
+                id: profile.id,
+                name: profile.name,
+                globalModelId: profile.globalModelId,
+                modelName: modelNameById.get(profile.globalModelId)
+              }))
+            };
+          },
+          setActiveProfile: (profileId) => {
+            const snapshot = settingsService.getSettings();
+            const exists = snapshot.models.profiles.some(
+              (profile) => profile.id === profileId
+            );
+            if (!exists) {
+              throw new Error(`Profile not found: ${profileId}`);
             }
-          });
-          const next = settingsService.getSettings();
-          agentService.updateSettings(next);
-          const modelNameById = new Map(
-            next.models.items.map((item) => [item.id, item.model])
-          );
-          return {
-            activeProfileId: next.models.activeProfileId,
-            profiles: next.models.profiles.map((profile) => ({
-              id: profile.id,
-              name: profile.name,
-              globalModelId: profile.globalModelId,
-              modelName: modelNameById.get(profile.globalModelId)
-            }))
-          };
-        },
-        probeModel: async (model) => {
-          return await modelCapabilityService.probe(model);
-        }
-      },
-      agentBridge: {
-        exportHistory: async (sessionId, mode) => {
-          await gatewayService.waitForRunCompletion(sessionId);
-          const backendSession = agentService.exportChatSession(sessionId);
-          if (!backendSession) {
-            throw new Error(`Session with ID ${sessionId} not found`);
-          }
-          const uiSession = uiHistoryService.getSession(sessionId);
-          if (mode === "simple") {
-            const markdown = uiHistoryService.toReadableMarkdown(
-              uiSession?.messages || [],
-              uiSession?.title || backendSession.title
+            settingsService.setSettings({
+              models: {
+                items: snapshot.models.items,
+                profiles: snapshot.models.profiles,
+                activeProfileId: profileId
+              }
+            });
+            const next = settingsService.getSettings();
+            agentService.updateSettings(next);
+            const modelNameById = new Map(
+              next.models.items.map((item) => [item.id, item.model])
             );
             return {
-              sessionId,
-              mode,
-              title: uiSession?.title || backendSession.title,
-              content: markdown
+              activeProfileId: next.models.activeProfileId,
+              profiles: next.models.profiles.map((profile) => ({
+                id: profile.id,
+                name: profile.name,
+                globalModelId: profile.globalModelId,
+                modelName: modelNameById.get(profile.globalModelId)
+              }))
             };
+          },
+          probeModel: async (model) => {
+            return await modelCapabilityService.probe(model);
           }
-          return {
-            sessionId: backendSession.id,
-            mode,
-            title: uiSession?.title || backendSession.title,
-            lastCheckpointOffset: backendSession.lastCheckpointOffset,
-            createdAt: new Date(backendSession.createdAt).toISOString(),
-            updatedAt: new Date(backendSession.updatedAt).toISOString(),
-            frontendMessages: uiSession?.messages || [],
-            backendMessages: backendSession.messages.map((msg) => ({
-              messageId: msg.id,
-              messageType: msg.type,
-              messageData: msg.data
-            }))
-          };
-        },
-        getAllChatHistory: () => agentService.getAllChatHistory(),
-        loadChatSession: (sessionId) => agentService.loadChatSession(sessionId),
-        getUiMessages: (sessionId) => uiHistoryService.getMessages(sessionId)
-      },
-      systemBridge: {
-        saveImageAttachment: async (payload) => {
-          return await imageAttachmentService.saveImageAttachment(payload);
-        }
-      },
-      skillBridge: {
-        reload: async () => {
-          return await skillService.reload();
-        },
-        getAll: async () => {
-          return await skillService.getAll();
-        },
-        getEnabled: async () => {
-          return await skillService.getEnabledSkills();
         },
-        create: async () => {
-          return await skillService.createSkillFromTemplate();
-        },
-        delete: async (fileName) => {
-          await skillService.deleteSkillFile(fileName);
-          return await skillService.getAll();
-        },
-        listSkills: async () => {
-          const snapshot = settingsService.getSettings();
-          const enabledMap = snapshot.tools?.skills ?? {};
-          const skills = await skillService.getAll();
-          return skills.map((skill) => ({
-            name: skill.name,
-            description: skill.description,
-            enabled: enabledMap[skill.name] !== false
-          }));
-        },
-        setSkillEnabled: async (name, enabled) => {
-          const snapshot = settingsService.getSettings();
-          const nextSkills = { ...snapshot.tools?.skills ?? {} };
-          nextSkills[name] = enabled;
-          settingsService.setSettings({
-            tools: {
-              builtIn: snapshot.tools?.builtIn ?? {},
-              skills: nextSkills
+        agentBridge: {
+          exportHistory: async (sessionId, mode) => {
+            await gatewayService.waitForRunCompletion(sessionId);
+            const backendSession = agentService.exportChatSession(sessionId);
+            if (!backendSession) {
+              throw new Error(`Session with ID ${sessionId} not found`);
+            }
+            const uiSession = uiHistoryService.getSession(sessionId);
+            if (mode === "simple") {
+              const markdown = uiHistoryService.toReadableMarkdown(
+                uiSession?.messages || [],
+                uiSession?.title || backendSession.title
+              );
+              return {
+                sessionId,
+                mode,
+                title: uiSession?.title || backendSession.title,
+                content: markdown
+              };
             }
-          });
-          const next = settingsService.getSettings();
-          agentService.updateSettings(next);
-          const skills = await skillService.getAll();
-          const summary = buildSkillStatusSummary(skills, next.tools?.skills);
-          gatewayService.broadcastRaw("skills:updated", summary);
-          return summary;
-        }
-      },
-      memoryBridge: {
-        get: async () => {
-          return await memoryService.getMemorySnapshot(
-            settingsService.getSettings().agentSettings?.activeProfileId || null
-          );
-        },
-        setContent: async (content) => {
-          const snapshot = await memoryService.writeMemory(
-            content,
-            settingsService.getSettings().agentSettings?.activeProfileId || null
-          );
-          gatewayService.broadcastRaw("memory:updated", snapshot);
-          return snapshot;
-        },
-        search: async (query, limit2) => {
-          const { content } = await memoryService.getMemorySnapshot(
-            settingsService.getSettings().agentSettings?.activeProfileId || null
-          );
-          return searchMemory(content, query, limit2 ?? 10);
-        },
-        append: async (note) => {
-          const profileId = settingsService.getSettings().agentSettings?.activeProfileId || null;
-          const { content } = await memoryService.getMemorySnapshot(profileId);
-          const next = appendMemoryNote(content, note);
-          const snapshot = await memoryService.writeMemory(next, profileId);
-          gatewayService.broadcastRaw("memory:updated", snapshot);
-          return snapshot;
-        }
-      },
-      agentSettingsBridge: {
-        get: () => agentSettingProfileService.getState(),
-        saveCurrent: async () => {
-          const result = await agentSettingProfileService.saveCurrent();
-          broadcastAgentSettingResult(result);
-          return result;
+            return {
+              sessionId: backendSession.id,
+              mode,
+              title: uiSession?.title || backendSession.title,
+              lastCheckpointOffset: backendSession.lastCheckpointOffset,
+              createdAt: new Date(backendSession.createdAt).toISOString(),
+              updatedAt: new Date(backendSession.updatedAt).toISOString(),
+              frontendMessages: uiSession?.messages || [],
+              backendMessages: backendSession.messages.map((msg) => ({
+                messageId: msg.id,
+                messageType: msg.type,
+                messageData: msg.data
+              }))
+            };
+          },
+          getAllChatHistory: () => agentService.getAllChatHistory(),
+          loadChatSession: (sessionId) => agentService.loadChatSession(sessionId),
+          getUiMessages: (sessionId) => uiHistoryService.getMessages(sessionId)
         },
-        apply: async (profileId) => {
-          const result = await agentSettingProfileService.apply(profileId);
-          broadcastAgentSettingResult(result);
-          return result;
+        systemBridge: {
+          saveImageAttachment: async (payload) => {
+            return await imageAttachmentService.saveImageAttachment(payload);
+          }
         },
-        overwrite: async (profileId) => {
-          const result = await agentSettingProfileService.overwrite(profileId);
-          broadcastAgentSettingResult(result);
-          return result;
+        skillBridge: {
+          reload: async () => {
+            return await skillService.reload();
+          },
+          getAll: async () => {
+            return await skillService.getAll();
+          },
+          getEnabled: async () => {
+            return await skillService.getEnabledSkills();
+          },
+          create: async () => {
+            return await skillService.createSkillFromTemplate();
+          },
+          delete: async (fileName) => {
+            await skillService.deleteSkillFile(fileName);
+            return await skillService.getAll();
+          },
+          listSkills: async () => {
+            const snapshot = settingsService.getSettings();
+            const enabledMap = snapshot.tools?.skills ?? {};
+            const skills = await skillService.getAll();
+            return skills.map((skill) => ({
+              name: skill.name,
+              description: skill.description,
+              enabled: enabledMap[skill.name] !== false
+            }));
+          },
+          setSkillEnabled: async (name, enabled) => {
+            const snapshot = settingsService.getSettings();
+            const nextSkills = { ...snapshot.tools?.skills ?? {} };
+            nextSkills[name] = enabled;
+            settingsService.setSettings({
+              tools: {
+                builtIn: snapshot.tools?.builtIn ?? {},
+                skills: nextSkills
+              }
+            });
+            const next = settingsService.getSettings();
+            agentService.updateSettings(next);
+            const skills = await skillService.getAll();
+            const summary = buildSkillStatusSummary(skills, next.tools?.skills);
+            gatewayService.broadcastRaw("skills:updated", summary);
+            return summary;
+          }
         },
-        delete: async (profileId) => {
-          const result = await agentSettingProfileService.delete(profileId);
-          broadcastAgentSettingResult(result);
-          return result;
-        }
-      },
-      settingsBridge: {
-        getSettings: () => settingsService.getSettings(),
-        setSettings: async (patch) => {
-          if (patch?.gateway?.ws) {
-            throw new Error(
-              "settings.gateway.ws is not configurable via websocket RPC."
+        memoryBridge: {
+          get: async () => {
+            return await memoryService.getMemorySnapshot(
+              settingsService.getSettings().agentSettings?.activeProfileId || null
             );
+          },
+          setContent: async (content) => {
+            const snapshot = await memoryService.writeMemory(
+              content,
+              settingsService.getSettings().agentSettings?.activeProfileId || null
+            );
+            gatewayService.broadcastRaw("memory:updated", snapshot);
+            return snapshot;
+          },
+          search: async (query, limit2) => {
+            const { content } = await memoryService.getMemorySnapshot(
+              settingsService.getSettings().agentSettings?.activeProfileId || null
+            );
+            return searchMemory(content, query, limit2 ?? 10);
+          },
+          append: async (note) => {
+            const profileId = settingsService.getSettings().agentSettings?.activeProfileId || null;
+            const { content } = await memoryService.getMemorySnapshot(profileId);
+            const next = appendMemoryNote(content, note);
+            const snapshot = await memoryService.writeMemory(next, profileId);
+            gatewayService.broadcastRaw("memory:updated", snapshot);
+            return snapshot;
           }
-          settingsService.setSettings(patch);
-          const next = settingsService.getSettings();
-          agentService.updateSettings(next);
-          return next;
-        }
-      },
-      commandPolicyBridge: {
-        getLists: async () => {
-          return await commandPolicyService.getLists();
         },
-        addRule: async (listName, rule) => {
-          return await commandPolicyService.addRule(listName, rule);
+        agentSettingsBridge: {
+          get: () => agentSettingProfileService.getState(),
+          saveCurrent: async () => {
+            const result = await agentSettingProfileService.saveCurrent();
+            broadcastAgentSettingResult(result);
+            return result;
+          },
+          apply: async (profileId) => {
+            const result = await agentSettingProfileService.apply(profileId);
+            broadcastAgentSettingResult(result);
+            return result;
+          },
+          overwrite: async (profileId) => {
+            const result = await agentSettingProfileService.overwrite(profileId);
+            broadcastAgentSettingResult(result);
+            return result;
+          },
+          delete: async (profileId) => {
+            const result = await agentSettingProfileService.delete(profileId);
+            broadcastAgentSettingResult(result);
+            return result;
+          }
         },
-        deleteRule: async (listName, rule) => {
-          return await commandPolicyService.deleteRule(listName, rule);
-        }
-      },
-      toolsBridge: {
-        reloadMcp: async () => {
-          return await mcpToolService.reloadAll();
+        settingsBridge: {
+          getSettings: () => settingsService.getSettings(),
+          setSettings: async (patch) => {
+            if (patch?.gateway?.ws) {
+              throw new Error(
+                "settings.gateway.ws is not configurable via websocket RPC."
+              );
+            }
+            settingsService.setSettings(patch);
+            const next = settingsService.getSettings();
+            agentService.updateSettings(next);
+            return next;
+          },
+          // v3.2.18: settings backup/restore/export/import.
+          listBackups: () => settingsBackupService.list(),
+          restoreBackup: async (name) => settingsBackupService.restore(name),
+          export: () => settingsBackupService.export(),
+          import: async (content) => settingsBackupService.import(content)
         },
-        getMcp: () => mcpToolService.getSummaries(),
-        setMcpEnabled: async (name, enabled) => {
-          return await mcpToolService.setServerEnabled(name, enabled);
+        // v3.2.18: cross-session history search.
+        historyBridge: {
+          getAllSessions: async () => {
+            try {
+              const all = historyStore.listChatSessions();
+              if (Array.isArray(all) && all.length > 0) {
+                return all;
+              }
+            } catch (e) {
+              console.warn(
+                "[history:search] store load failed, falling back to metadata:",
+                e instanceof Error ? e.message : e
+              );
+            }
+            return agentService.getAllChatHistory() ?? [];
+          }
         },
-        getBuiltIn: () => {
-          const settings = settingsService.getSettings();
-          return buildBuiltInToolStatusSummary(settings.tools?.builtIn);
+        commandPolicyBridge: {
+          getLists: async () => {
+            return await commandPolicyService.getLists();
+          },
+          addRule: async (listName, rule) => {
+            return await commandPolicyService.addRule(listName, rule);
+          },
+          deleteRule: async (listName, rule) => {
+            return await commandPolicyService.deleteRule(listName, rule);
+          }
         },
-        setBuiltInEnabled: async (name, enabled) => {
-          const settings = settingsService.getSettings();
-          const nextBuiltIn = { ...settings.tools?.builtIn ?? {} };
-          nextBuiltIn[name] = enabled;
-          settingsService.setSettings({
-            tools: {
-              builtIn: nextBuiltIn,
-              skills: settings.tools?.skills ?? {}
-            }
-          });
-          const next = settingsService.getSettings();
-          agentService.updateSettings(next);
-          const summary = buildBuiltInToolStatusSummary(next.tools?.builtIn);
-          gatewayService.broadcastRaw("tools:builtInUpdated", summary);
-          return summary;
-        }
-      },
-      // Observability bridge (v2.9.x): exposes the 9 platform capabilities
-      // (metrics export, secrets, on-call, cost, recording, gitops, playbooks,
-      // cloud, live dashboard) as observability:* RPC methods.
-      observabilityBridge: createObservabilityBridge({
-        observability: () => observability,
-        terminalService: () => terminalService
-      })
-    })
+        toolsBridge: {
+          reloadMcp: async () => {
+            return await mcpToolService.reloadAll();
+          },
+          getMcp: () => mcpToolService.getSummaries(),
+          setMcpEnabled: async (name, enabled) => {
+            return await mcpToolService.setServerEnabled(name, enabled);
+          },
+          getBuiltIn: () => {
+            const settings = settingsService.getSettings();
+            return buildBuiltInToolStatusSummary(settings.tools?.builtIn);
+          },
+          setBuiltInEnabled: async (name, enabled) => {
+            const settings = settingsService.getSettings();
+            const nextBuiltIn = { ...settings.tools?.builtIn ?? {} };
+            nextBuiltIn[name] = enabled;
+            settingsService.setSettings({
+              tools: {
+                builtIn: nextBuiltIn,
+                skills: settings.tools?.skills ?? {}
+              }
+            });
+            const next = settingsService.getSettings();
+            agentService.updateSettings(next);
+            const summary = buildBuiltInToolStatusSummary(next.tools?.builtIn);
+            gatewayService.broadcastRaw("tools:builtInUpdated", summary);
+            return summary;
+          }
+        },
+        // Observability bridge (v2.9.x): exposes the 9 platform capabilities
+        // (metrics export, secrets, on-call, cost, recording, gitops, playbooks,
+        // cloud, live dashboard) as observability:* RPC methods.
+        observabilityBridge: createObservabilityBridge({
+          observability: () => observability,
+          terminalService: () => terminalService
+        })
+      });
+      restDispatchTarget = adapter;
+      return adapter;
+    }
   });
   await wsGatewayControlService.applyPolicy(startupPolicy);
   const shutdown = async (signal) => {