mixdog 0.9.46 → 0.9.49

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool.mjs

@@ -181,6 +181,32 @@ export function formatShellToolFailure(message) {
     return `Error: [shell-tool-failed] ${text}`;
 }
 
+export function _shellFailureStatus(result, timeout) {
+    // Prefer the signal reported by the process. `killed` is only a fallback
+    // for platforms (notably taskkill on Windows) that close without one.
+    const signal = result.signal || (result.killed ? 'SIGKILL' : null);
+    const exitCode = signal ? null : result.exitCode;
+    const shellToolFailed = result.failurePhase === 'tool' || !!result.outputCaptureError;
+    const killCause = result.killCause || null;
+    const causeDetail = killCause ? ` cause: ${killCause}` : '';
+    const signalDetail = signal ? ` signal: ${signal}` : '';
+    const timeoutHint = result.timedOut
+        ? ` — command killed after ${timeout} ms; if it legitimately needs longer, retry with a larger timeout`
+        : '';
+    const statusDetail = shellToolFailed
+        ? `[${result.outputCaptureError ? 'output capture failed' : (result.failureReason || 'tool failed')}${causeDetail}${signalDetail}]`
+        : (result.timedOut
+            ? `[timeout: ${timeout}ms${signalDetail || ' signal: unknown'}${causeDetail}]${timeoutHint}`
+            : (signal
+                ? `[signal: ${signal}${causeDetail}]`
+                : (exitCode !== 0 && exitCode !== null ? `[exit code: ${exitCode}]` : '')));
+    return { signal, exitCode, shellToolFailed, statusDetail };
+}
+
+export function _composeShellFailure(statusMarker, errorPrefix, warningBlock, payload) {
+    return `${errorPrefix}${statusMarker}${warningBlock ? `\n${warningBlock}` : ''}\n\n${payload}`;
+}
+
 export async function executeBashTool(args, workDir, options = {}) {
     const requestedCwd = args.cwd ?? args.workdir;
     const cwdResult = resolveOptionalCwd(requestedCwd, workDir);
@@ -539,12 +565,9 @@ export async function executeBashTool(args, workDir, options = {}) {
         }
         const stdout = stripAnsi(result.stdout || '');
         const stderr = stripAnsi(result.stderr || '');
-        const signal = result.timedOut
-            ? 'SIGTERM'
-            : (result.killed ? 'SIGKILL' : (result.signal || null));
-        const exitCode = signal ? null : result.exitCode;
+        const failureStatus = _shellFailureStatus(result, timeout);
+        const { signal, exitCode, shellToolFailed } = failureStatus;
         const benignExitOne = _isBenignSearchExitOne(command, exitCode, signal, stderr);
-        const shellToolFailed = result.failurePhase === 'tool' || !!result.outputCaptureError;
         const shellRunFailed = !shellToolFailed && (!!signal || (exitCode !== 0 && exitCode !== null && !benignExitOne));
         const isReallyErrored = shellToolFailed || shellRunFailed;
         const _driftNote = '';
@@ -556,16 +579,7 @@ export async function executeBashTool(args, workDir, options = {}) {
         // Timeout marker carries an inline recovery hint so the caller can
         // act in one round (increase ceiling or detach) instead of repeating
         // the same command and hitting the same wall.
-        const timeoutHint = result.timedOut
-            ? ` — command killed after ${timeout} ms; if it legitimately needs longer, retry with a larger timeout`
-            : '';
-        const statusDetail = shellToolFailed
-            ? `[${result.outputCaptureError ? 'output capture failed' : (result.failureReason || 'tool failed')}]`
-            : (result.timedOut
-                ? `[timeout: ${timeout}ms signal: ${signal || 'SIGTERM'}]${timeoutHint}`
-                : (signal
-                    ? `[signal: ${signal}]`
-                    : (shellRunFailed ? `[exit code: ${exitCode}]` : '')));
+        const statusDetail = failureStatus.statusDetail;
         const statusMarker = shellToolFailed
             ? `[shell-tool-failed] ${statusDetail}`
             : (shellRunFailed ? `[shell-run-failed] ${statusDetail}` : '');
@@ -602,7 +616,7 @@ export async function executeBashTool(args, workDir, options = {}) {
             wmicRewrite?.note || '',
         ].filter(Boolean).join('\n');
         const payload = `${body}${stderrBlock}${spillBlock}${_driftNote}`;
-        if (statusMarker) return _prependDestructiveWarning(command, `${errorPrefix}${warningBlock ? `${warningBlock}\n` : ''}${statusMarker}\n\n${payload}`);
+        if (statusMarker) return _prependDestructiveWarning(command, _composeShellFailure(statusMarker, errorPrefix, warningBlock, payload));
         return _prependDestructiveWarning(command, warningBlock ? `${warningBlock}\n${payload}` : payload);
     }
     finally {

package/src/runtime/agent/orchestrator/tools/code-graph/build.mjs

@@ -155,12 +155,23 @@ export function _postCodeGraphWorkerSuccess(graph, postMessage, drainCache = dra
   postMessage({ ok: true, signature: graph.signature, graph });
 }
 
-export function prewarmCodeGraph(cwd) {
+// Exported for the focused worker-protocol regression test.
+export function _codeGraphWorkerFailure(message) {
+  const error = typeof message?.error === 'string' ? message.error.trim() : '';
+  return new Error(error || 'code-graph prewarm worker failed');
+}
+
+// Exported for the focused best-effort prewarm regression test.
+export function _prewarmCodeGraph(cwd, build = buildCodeGraphAsync) {
   if (!cwd) return;
   // Reuse the buildCodeGraphAsync single-flight path. Fire-and-forget, and
   // best-effort: skip a fresh worker spawn when the child-spawn gate is busy
   // so this warm never queues ahead of real code_graph/find queries.
-  buildCodeGraphAsync(cwd, null, { bestEffort: true }).catch(() => { /* best-effort */ });
+  build(cwd, null, { bestEffort: true }).catch(() => { /* best-effort */ });
+}
+
+export function prewarmCodeGraph(cwd) {
+  _prewarmCodeGraph(cwd);
 }
 
 export function prewarmCodeGraphSymbols(cwd, symbols, { language = null } = {}) {
@@ -248,7 +259,7 @@ export async function buildCodeGraphAsync(cwd, signal = null, { bestEffort = fal
   }
 }
 
-function _spawnCodeGraphWorker(
+export function _spawnCodeGraphWorker(
   cwd,
   graphCwd,
   genAtStart,
@@ -256,6 +267,12 @@ function _spawnCodeGraphWorker(
   preAcquiredRelease = null,
   manifest = null,
   signature = null,
+  {
+    createWorker = (url, options) => new Worker(url, options),
+    getGeneration = _getCodeGraphGen,
+    setMemoryCache = _setCodeGraphCache,
+    setDiskCache = _setDiskCodeGraphEntry,
+  } = {},
 ) {
   let _worker = null;
   return new Promise((resolve, reject) => {
@@ -281,7 +298,7 @@ function _spawnCodeGraphWorker(
       if (signal?.aborted) { settle(new Error('aborted')); return; }
       const workerUrl = new URL('../code-graph-prewarm-worker.mjs', import.meta.url);
       try {
-        _worker = new Worker(workerUrl, {
+        _worker = createWorker(workerUrl, {
           workerData: { cwd, manifest, signature },
           execArgv: [],
         });
@@ -305,14 +322,14 @@ function _spawnCodeGraphWorker(
       w.once('message', (msg) => {
         try {
           if (msg && msg.ok && msg.graph && typeof msg.signature === 'string') {
-            const genStillCurrent = _getCodeGraphGen(graphCwd) === genAtStart;
+            const genStillCurrent = getGeneration(graphCwd) === genAtStart;
             if (genStillCurrent) {
-              _setCodeGraphCache(graphCwd, { ts: Date.now(), signature: msg.signature, graph: msg.graph });
-              _setDiskCodeGraphEntry(graphCwd, msg.graph);
+              setMemoryCache(graphCwd, { ts: Date.now(), signature: msg.signature, graph: msg.graph });
+              setDiskCache(graphCwd, msg.graph);
             }
             settle(genStillCurrent ? msg.graph : new Error('code-graph build invalidated during prewarm'));
           } else {
-            settle(new Error('code-graph prewarm worker failed'));
+            settle(_codeGraphWorkerFailure(msg));
           }
         } catch (e) { settle(e instanceof Error ? e : new Error(String(e))); }
       });

package/src/runtime/agent/orchestrator/tools/code-graph/dispatch.mjs

@@ -50,6 +50,7 @@ function _collectGraphSymbolList(args) {
 }
 
 const CODE_GRAPH_FILE_BATCH_CAP = 20;
+const _AGGREGATE_FILE_WILDCARD_RE = /[*?[\]{}]/;
 
 // Absorb: file/files arriving as a JSON-stringified array
 // (file:"[\"a.mjs\",\"b.mjs\"]") — parse to a real array so the graph lookup
@@ -74,21 +75,21 @@ function _normalizeGraphFileArgs(args) {
   if (fileArr) { out.files = Array.isArray(out.files) ? [...fileArr, ...out.files] : fileArr; delete out.file; }
   if (filesArr) out.files = filesArr;
   // Collapse a lone entry back to the single-file field for the fast path.
-  if (Array.isArray(out.files) && out.files.length === 1 && !out.file) {
+  if (Array.isArray(out.files) && out.files.length === 1 && !out.file && !filesArr) {
     out.file = out.files[0];
     delete out.files;
   }
   return out;
 }
 
-function _collectGraphFileList(args) {
+function _collectGraphFileList(args, { cap = true } = {}) {
   const split = (s) => String(s || '').split(/,+/).map((t) => t.trim()).filter(Boolean);
   const list = [...new Set([
     ...(Array.isArray(args?.files) ? args.files.map((f) => String(f || '').trim()).filter(Boolean) : []),
     ...(typeof args?.files === 'string' ? split(args.files) : []),
     ...(typeof args?.file === 'string' && args.file.trim() ? [args.file.trim()] : []),
   ])];
-  if (list.length > CODE_GRAPH_FILE_BATCH_CAP) {
+  if (cap && list.length > CODE_GRAPH_FILE_BATCH_CAP) {
     const capped = list.slice(0, CODE_GRAPH_FILE_BATCH_CAP);
     capped._capped = true;
     return capped;
@@ -96,6 +97,57 @@ function _collectGraphFileList(args) {
   return list;
 }
 
+function _hasAggregateFileArgs(args) {
+  return (Array.isArray(args?.files) && args.files.some((f) => String(f || '').trim()))
+    || (typeof args?.files === 'string' && args.files.trim());
+}
+
+// An invalid caller cwd may be recovered for an explicit files aggregate only
+// when every supplied anchor points at the same detectable project. Do not use
+// the batch cap here: an omitted anchor could belong to another project.
+function _resolveAggregateFileProjectRoot(args, baseCwd) {
+  if (!_hasAggregateFileArgs(args)) return null;
+  // Comma-delimited strings are parsed for normal batch dispatch, but are not
+  // unambiguous enough to select a project root. JSON array strings have
+  // already been normalized to an actual array above.
+  if (typeof args?.files === 'string' && args.files.includes(',')) return null;
+  const files = _collectGraphFileList(args, { cap: false });
+  // Recovery cannot silently discard anchors that normal batch dispatch caps.
+  if (files.length > CODE_GRAPH_FILE_BATCH_CAP) return null;
+  const roots = new Set();
+  for (const file of files) {
+    // Never infer a root from a glob-shaped anchor, including a literal file
+    // whose name contains a glob metacharacter.
+    if (_AGGREGATE_FILE_WILDCARD_RE.test(file)) return null;
+    const abs = isAbsolute(file) ? pathResolve(file) : pathResolve(baseCwd, file);
+    if (!existsSync(abs)) return null;
+    let isDirectory = false;
+    try { isDirectory = statSync(abs).isDirectory(); } catch { return null; }
+    const root = isDirectory ? _findDirProjectRoot(abs) : _resolveFileProjectRoot(abs);
+    if (!root) return null;
+    roots.add(pathResolve(root));
+    if (roots.size > 1) return null;
+  }
+  return roots.size === 1 ? [...roots][0] : null;
+}
+
+// Aggregate recovery resolves relative anchors against the caller's original
+// cwd. Keep those resolved paths when dispatching under the recovered root;
+// otherwise codeGraph resolves them a second time below that root.
+function _absolutizeAggregateFileArgs(args, baseCwd) {
+  const absolutize = (file) => {
+    const trimmed = String(file || '').trim();
+    return trimmed && !isAbsolute(trimmed) ? pathResolve(baseCwd, trimmed) : file;
+  };
+  return {
+    ...args,
+    file: typeof args?.file === 'string' ? absolutize(args.file) : args?.file,
+    files: Array.isArray(args?.files)
+      ? args.files.map(absolutize)
+      : (typeof args?.files === 'string' ? absolutize(args.files) : args?.files),
+  };
+}
+
 async function codeGraph(args, cwd, signal = null, options = {}) {
   let mode = String(args?.mode || '').trim();
   if (!mode) throw new Error('code_graph: "mode" is required');
@@ -539,8 +591,21 @@ export async function executeCodeGraphTool(name, args, cwd, signal = null, optio
     delete args.file;
   }
   const fileArg = (args && typeof args.file === 'string' && args.file.trim()) ? args.file.trim() : '';
+  const hasAggregateFileArgs = _hasAggregateFileArgs(args);
   let effectiveCwd = baseCwd;
-  if (fileArg) {
+  const baseProjectRoot = _findDirProjectRoot(baseCwd);
+  if (hasAggregateFileArgs && !baseProjectRoot) {
+    const aggregateRoot = _resolveAggregateFileProjectRoot(args, baseCwd);
+    if (!aggregateRoot) {
+      throw new Error(
+        `${name}: cwd '${baseCwd}' is not inside a project and aggregate file anchors do not all `
+        + `exist under exactly one detectable project root. Refusing to index an arbitrary tree.`,
+      );
+    }
+    effectiveCwd = aggregateRoot;
+    args = _absolutizeAggregateFileArgs(args, baseCwd);
+  }
+  if (fileArg && !hasAggregateFileArgs) {
     const abs = isAbsolute(fileArg) ? pathResolve(fileArg) : pathResolve(baseCwd, fileArg);
     if (!existsSync(abs)) {
       const elsewhere = findFileByBasename(pathResolve(baseCwd), abs);

package/src/runtime/agent/orchestrator/tools/code-graph-prewarm-worker.mjs

@@ -9,8 +9,8 @@
 //    seeds _codeGraphCache directly. Graph is structuredClone-transferred —
 //    Maps/Sets of plain objects only, runtime caches are empty Maps that
 //    survive the clone.
-//  - On any failure: postMessage({ ok: false }). Main thread propagates
-//    an error — find_symbol / code_graph tools throw. No sync fallback.
+//  - On any failure: postMessage({ ok: false, error }). Main thread propagates
+//    the worker error — find_symbol / code_graph tools throw. No sync fallback.
 import { parentPort, workerData } from 'node:worker_threads';
 import { _buildCodeGraph, _postCodeGraphWorkerSuccess } from './code-graph.mjs';
 
@@ -37,6 +37,7 @@ try {
       parentPort.postMessage({ ok: false });
     }
   }
-} catch {
-  parentPort.postMessage({ ok: false });
+} catch (error) {
+  const message = (error instanceof Error ? error.message : String(error)).trim();
+  parentPort.postMessage(message ? { ok: false, error: message } : { ok: false });
 }

package/src/runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs

@@ -3,7 +3,7 @@ export const CODE_GRAPH_TOOL_DEFS = [
     name: 'code_graph',
     title: 'Code Graph',
     annotations: { title: 'Code Graph', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false, compressibleLossless: true },
-    description: 'Repo code structure/flow over verified source files only. IDs→graph; literal/zero→grep. Exact identifiers: find_symbol/references/callers/callees; keywords: symbol_search/search. Unsupported target arrays are omitted, never silently mixed. Batch symbols[]/files[] by mode.',
+    description: 'Repo code structure/flow over verified source files only. IDs→graph; literal/zero→grep. File modes take files[]; symbol modes find_symbol/symbol_search/search/references/callers/callees take symbols[]. Exact identifiers use find_symbol/references/callers/callees and keywords use symbol_search/search. Unsupported target arrays are omitted, never silently mixed. Batch targets per mode.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/runtime/agent/orchestrator/tools/graph-manifest.json

@@ -1,26 +1,26 @@
 {
-  "version": "0.7.18",
-  "_comment": "Rewritten by .github/workflows/graph-release.yml on each tagged release. assets maps platformKey (process.platform-process.arch, e.g. win32-x64, linux-x64, darwin-arm64) to { url, sha256 } of the mixdog-graph binary on the GitHub release. A local cargo build under native/mixdog-graph/target/release always takes precedence at runtime. (v0.5.236 entries were filled manually after CI's commit step hit detached HEAD; the workflow now checks out ref: main so future releases self-update.)",
+  "version": "0.1.1",
+  "_comment": "Synced from immutable graph-v release assets.",
   "assets": {
     "darwin-arm64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-darwin-arm64",
-      "sha256": "34653a7cdf457295c4835fa9819627e9690c323b6012e6f571259478406bbe04"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.1/mixdog-graph-darwin-arm64",
+      "sha256": "3fb76a5e3064547b68e7bcab6ce2a855ce615a732157d836cb561c5d7c8d86b6"
     },
     "darwin-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-darwin-x64",
-      "sha256": "1c0648ed8a1b9fd2d8bc44d85b91262cb11e0773d2280d6ec351ee1ff1c579f0"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.1/mixdog-graph-darwin-x64",
+      "sha256": "64eeffc17984a76b0fbf7d85f9d84cb5e1bb949a251053feb260f70481235bb1"
     },
     "linux-arm64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-linux-arm64",
-      "sha256": "71c9d69125b97e93466e5a5613c00db2d797c1f25cc4237e776225574c5f6970"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.1/mixdog-graph-linux-arm64",
+      "sha256": "15d5cbb7575b3e0671c6f5fbef3460c5c9353f17968a80faba737fcc15b49c33"
     },
     "linux-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-linux-x64",
-      "sha256": "4800a7ac77b777ddb5862f252cdc00b55230455921e0c58416d7a77b120604a7"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.1/mixdog-graph-linux-x64",
+      "sha256": "5079544c09ae2311295cef21978fda3c1c06f93beaaf666cfe1f68971d5b27ae"
     },
     "win32-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-win32-x64.exe",
-      "sha256": "1d0d62f5b78965c7d5b05ebc7cf7bdef1a3e14cc2600aa205ca762e56c446934"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.1/mixdog-graph-win32-x64.exe",
+      "sha256": "acfbcd02b96154f4fb342a44dec1a4808752944c5941bbb7983d84ed64464830"
     }
   }
 }

package/src/runtime/agent/orchestrator/tools/patch/native-server.mjs

@@ -70,30 +70,35 @@ function nativePatchPersistent() {
   return /^(1|true|yes|server|persistent)$/i.test(nativePatchMode());
 }
 
-export function nativePatchBinPath() {
+export function nativePatchBinPath(options = {}) {
   if (process.env.MIXDOG_PATCH_NATIVE_BIN) return process.env.MIXDOG_PATCH_NATIVE_BIN;
   // Local cargo build first, then a fetched/cached prebuilt; absence is
   // a hard error at dispatch (no JS fallback in native-only mode).
-  if (existsSync(NATIVE_PATCH_DEFAULT_BIN)) return NATIVE_PATCH_DEFAULT_BIN;
-  return findCachedPatchBinary(getPluginData()) || NATIVE_PATCH_DEFAULT_BIN;
+  const defaultBin = options.defaultBin || NATIVE_PATCH_DEFAULT_BIN;
+  if (existsSync(defaultBin)) return defaultBin;
+  const dataDir = options.dataDir || getPluginData();
+  return findCachedPatchBinary(dataDir, options.fetcherOptions) || defaultBin;
 }
 
-export async function ensureNativePatchBinaryAvailable() {
+export async function ensureNativePatchBinaryAvailable(options = {}) {
   if (!nativePatchEnabled()) {
     throw new Error('apply_patch: native engine disabled via MIXDOG_PATCH_NATIVE; set it to "auto" or "1" to apply patches.');
   }
-  const current = nativePatchBinPath();
+  const current = nativePatchBinPath(options);
   if (existsSync(current)) return current;
   if (process.env.MIXDOG_PATCH_NATIVE_BIN) {
     throw new Error(`apply_patch: native patch binary not found at MIXDOG_PATCH_NATIVE_BIN=${current}.`);
   }
   try {
-    const fetched = await ensurePatchBinary(getPluginData());
+    const fetched = await ensurePatchBinary(
+      options.dataDir || getPluginData(),
+      options.fetcherOptions,
+    );
     if (fetched && existsSync(fetched)) return fetched;
   } catch (err) {
     throw new Error(`apply_patch: native patch binary unavailable — ${err?.message || String(err)}`);
   }
-  const resolved = nativePatchBinPath();
+  const resolved = nativePatchBinPath(options);
   if (existsSync(resolved)) return resolved;
   throw new Error(`apply_patch: native patch binary not found at ${resolved}.`);
 }

package/src/runtime/agent/orchestrator/tools/patch-binary-fetcher.mjs

@@ -7,6 +7,8 @@
 //   ensurePatchBinary(dataDir) -> absolute path to the verified binary.
 //     Throws on no-asset / download / verify failure.
 //   findCachedPatchBinary(dataDir) -> path | null (sync, no network).
+// Both accept an optional dependency object used by deterministic tests:
+//   { bundledManifest, download }.
 
 import { createHash } from 'node:crypto';
 import {
@@ -34,16 +36,68 @@ function patchBinDir(dataDir) {
   return join(dataDir, 'patch-bin');
 }
 
-async function loadManifest(dataDir) {
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+
+function manifestVersion(manifest) {
+  const value = String(manifest?.version || '');
+  if (!/^\d+\.\d+\.\d+$/.test(value)) return null;
+  return value.split('.').map(Number);
+}
+
+function compareManifestVersions(a, b) {
+  const av = manifestVersion(a);
+  const bv = manifestVersion(b);
+  if (!av || !bv) return null;
+  for (let i = 0; i < 3; i++) {
+    if (av[i] !== bv[i]) return av[i] > bv[i] ? 1 : -1;
+  }
+  return 0;
+}
+
+function validSha256(value) {
+  return typeof value === 'string' && /^[a-f0-9]{64}$/i.test(value);
+}
+
+function validCachedUpgrade(manifest, pkey) {
+  if (!manifestVersion(manifest)) return false;
+  const asset = manifest.assets?.[pkey];
+  if (!asset || !validSha256(asset.sha256) || typeof asset.url !== 'string') return false;
+  const expectedUrl = `https://github.com/tribgames/mixdog/releases/download/patch-v${manifest.version}`
+    + `/mixdog-patch-${pkey}${binSuffix()}`;
+  return asset.url === expectedUrl;
+}
+
+function bundledManifest(options) {
+  if (options.bundledManifest) return options.bundledManifest;
+  return existsSync(BUNDLED_MANIFEST_PATH) ? readJson(BUNDLED_MANIFEST_PATH) : null;
+}
+
+function selectLocalManifest(dataDir, options = {}) {
+  const bundled = bundledManifest(options);
   const cached = join(patchBinDir(dataDir), 'manifest.json');
-  if (existsSync(cached)) {
-    try { return JSON.parse(readFileSync(cached, 'utf8')); } catch { /* fall through */ }
+  const cachedManifest = existsSync(cached) ? readJson(cached) : null;
+  if (bundled) {
+    // The installed manifest is the minimum policy. A cache may advance it,
+    // but only with a strict newer semver and a trusted, fully hashed asset.
+    if (compareManifestVersions(cachedManifest, bundled) === 1
+      && validCachedUpgrade(cachedManifest, platformKey())) {
+      return cachedManifest;
+    }
+    return bundled;
   }
-  if (existsSync(BUNDLED_MANIFEST_PATH)) {
-    return JSON.parse(readFileSync(BUNDLED_MANIFEST_PATH, 'utf8'));
+  return validCachedUpgrade(cachedManifest, platformKey()) ? cachedManifest : null;
+}
+
+async function loadManifest(dataDir, options = {}) {
+  const local = selectLocalManifest(dataDir, options);
+  if (local) return local;
+  const fetchFn = options.fetch || fetch;
+  const res = await fetchFn(MANIFEST_URL, { signal: AbortSignal.timeout(30_000) });
+  if (!res.ok) {
+    throw new Error(`[patch-fetcher] manifest fetch failed: ${res.status} ${res.statusText}`);
   }
-  const res = await fetch(MANIFEST_URL, { signal: AbortSignal.timeout(30_000) });
-  if (!res.ok) throw new Error(`[patch-fetcher] manifest fetch failed: ${res.status} ${res.statusText}`);
   return res.json();
 }
 
@@ -86,13 +140,18 @@ function gcPatchBin(dir, keepFile) {
   } catch { /* dir may not exist yet */ }
 }
 
-export function findCachedPatchBinary(dataDir) {
+export function findCachedPatchBinary(dataDir, options = {}) {
   try {
     const dir = patchBinDir(dataDir);
-    const hit = readdirSync(dir).find(
-      (n) => n.startsWith('mixdog-patch') && !n.endsWith('.json') && !n.includes('.tmp-'),
-    );
-    return hit ? join(dir, hit) : null;
+    const manifest = selectLocalManifest(dataDir, options);
+    const asset = manifest?.assets?.[platformKey()];
+    const version = manifestVersion(manifest);
+    if (!version || !validSha256(asset?.sha256)) return null;
+    const fileName = `mixdog-patch-${manifest.version}${binSuffix()}`;
+    const hit = join(dir, fileName);
+    if (!existsSync(hit)) return null;
+    const actual = createHash('sha256').update(readFileSync(hit)).digest('hex');
+    return actual === asset.sha256.toLowerCase() ? hit : null;
   } catch {
     return null;
   }
@@ -100,13 +159,13 @@ export function findCachedPatchBinary(dataDir) {
 
 let _inflight = null;
 
-export function ensurePatchBinary(dataDir) {
+export function ensurePatchBinary(dataDir, options = {}) {
   if (_inflight) return _inflight;
   _inflight = (async () => {
-    const manifest = await loadManifest(dataDir);
+    const manifest = await loadManifest(dataDir, options);
     const pkey = platformKey();
     const asset = manifest.assets?.[pkey];
-    if (!asset || !asset.url || !asset.sha256) {
+    if (!asset || !asset.url || !validSha256(asset.sha256) || !manifestVersion(manifest)) {
       // Unsupported platform/arch (e.g. win32-arm64): the manifest has no
       // downloadable asset for this {os}-{arch}. apply_patch is native-only
       // (no JS apply fallback), so this is terminal — surface a single clear,
@@ -125,12 +184,12 @@ export function ensurePatchBinary(dataDir) {
     const fileName = `mixdog-patch-${version}${binSuffix()}`;
     const destPath = join(dir, fileName);
     if (existsSync(destPath)) {
-      try { if (await sha256File(destPath) === asset.sha256) return destPath; } catch { /* re-download */ }
+      try { if (await sha256File(destPath) === asset.sha256.toLowerCase()) return destPath; } catch { /* re-download */ }
     }
     const tmpPath = `${destPath}.tmp-${process.pid}-${Date.now()}`;
-    await downloadWithRetry(asset.url, tmpPath);
+    await (options.download || downloadWithRetry)(asset.url, tmpPath);
     const actual = await sha256File(tmpPath);
-    if (actual !== asset.sha256) {
+    if (actual !== asset.sha256.toLowerCase()) {
       try { rmSync(tmpPath, { force: true }); } catch { /* best-effort */ }
       throw new Error(`[patch-fetcher] sha256 mismatch for ${pkey}: expected ${asset.sha256}, got ${actual}`);
     }

package/src/runtime/agent/orchestrator/tools/patch-manifest.json

@@ -1,26 +1,26 @@
 {
-  "version": "0.7.19",
+  "version": "0.7.20",
   "_comment": "Rewritten by .github/workflows/patch-release.yml on each tagged release. assets maps platformKey (process.platform-process.arch, e.g. win32-x64, linux-x64, darwin-arm64) to { url, sha256 } of the mixdog-patch binary on the GitHub release. A local cargo build under native/mixdog-patch/target/release always takes precedence; otherwise the binary is fetched per this manifest into the data dir (apply is native-only — no JS apply engine).",
   "assets": {
     "darwin-arm64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.19/mixdog-patch-darwin-arm64",
-      "sha256": "c808fcfb69d2817fd7678dd364d2e1dd68f6ef2d9807f618bdf110c03ca00ccb"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.20/mixdog-patch-darwin-arm64",
+      "sha256": "12b9b3ad3365fcde21c83c1b42236f6bd70dbe411d79e5c0f7c3c5743f1a3185"
     },
     "darwin-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.19/mixdog-patch-darwin-x64",
-      "sha256": "7ed0eeff84796559ca865fc93e7a2a94f2c3fa00126f919064bb8273656fcd85"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.20/mixdog-patch-darwin-x64",
+      "sha256": "ff5de6da5fec3abbf617c0c3b1ead8e724d4cb0e9948277253889c83bc27a570"
     },
     "linux-arm64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.19/mixdog-patch-linux-arm64",
-      "sha256": "3cad9c9542f2d97732953a102ef72daf4c79be5361560698d5fd2c5f0c18eda7"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.20/mixdog-patch-linux-arm64",
+      "sha256": "76d7cf54df7face32fb20862425ce25ad44e9800440132dea3f0ad387c92f07e"
     },
     "linux-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.19/mixdog-patch-linux-x64",
-      "sha256": "cb0e30346f437811dff19238e1854bd37d97a78f35b13e0b704ebeaa9499ae87"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.20/mixdog-patch-linux-x64",
+      "sha256": "43f6610beadf25eca752a09775fcb8858818ad2d9f7b8cf6a00deaa47571f3f0"
     },
     "win32-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.19/mixdog-patch-win32-x64.exe",
-      "sha256": "4bf61a99f63e446570d9d2a9c9ef38475d0d70c0a2b632a5f44d4fe9b684b968"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.20/mixdog-patch-win32-x64.exe",
+      "sha256": "4d5d2242f9662aeb968c24df571a498008d9c504fd31214fe9dac31aac669fdd"
     }
   }
 }