mixdog 0.7.18 → 0.8.0

package/src/runtime/agent/orchestrator/tools/destructive-warning.mjs

@@ -0,0 +1,323 @@
+'use strict';
+// Destructive command detector.
+//
+// Returns a short human-readable warning string when the command matches
+// a known data-loss / hard-to-reverse pattern. Purely informational —
+// the caller (case 'shell' in builtin.mjs) prepends the warning to the result
+// envelope so the agent sees the risk inline. Does NOT block execution;
+// hard blocks remain in BLOCKED_PATTERNS in builtin.mjs / bash-session.mjs.
+
+import { SHELL_NAMES as _SHELL_NAMES, WRAPPER_NAMES as _WRAPPER_NAMES } from './shell-policy.mjs';
+import { extractPowerShellCommandInner } from './shell-command.mjs';
+
+export function stripQuotedAndHeredoc(s) { return _stripQuotedSpans(s); }
+export function extractShellCInner(s) { return _extractShellCInner(s); }
+
+function _stripQuotedSpans(s) {
+  return String(s || '')
+    .replace(/<<-?\s*['"]?(\w+)['"]?[\s\S]*?\n\1\b/g, '<<HEREDOC>>')
+    .replace(/'[^']*'/g, "''")
+    .replace(/"(?:[^"\\]|\\.)*"/g, '""')
+    .replace(/#[^\n]*/g, '');
+}
+
+// Heredoc bodies (shell-exec contexts route the body through scanning).
+function _extractHeredocBodies(s) {
+  const out = [];
+  const re = /<<-?\s*['"]?(\w+)['"]?([\s\S]*?)\n\1\b/g;
+  let m;
+  while ((m = re.exec(String(s || ''))) !== null) out.push(m[2]);
+  return out;
+}
+
+// Shell-aware tokenizer. Quoted spans stay intact; separators become
+// their own token so callers can split pipeline segments cleanly.
+function _tokenize(s) {
+  const t = [], src = String(s || '');
+  let cur = '', i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "'") { const e = src.indexOf("'", i + 1); if (e === -1) { cur += src.slice(i); break; } cur += src.slice(i, e + 1); i = e + 1; continue; }
+    if (c === '"') { let j = i + 1; while (j < src.length) { if (src[j] === '\\' && j + 1 < src.length) { j += 2; continue; } if (src[j] === '"') break; j++; } if (j >= src.length) { cur += src.slice(i); break; } cur += src.slice(i, j + 1); i = j + 1; continue; }
+    if (c === '\\' && i + 1 < src.length) { cur += src[i] + src[i + 1]; i += 2; continue; }
+    if (c === ' ' || c === '\t') { if (cur) { t.push(cur); cur = ''; } i++; continue; }
+    if (c === '\n' || c === ';') { if (cur) { t.push(cur); cur = ''; } t.push(c); i++; continue; }
+    if (c === '&' || c === '|') { if (cur) { t.push(cur); cur = ''; } if (src[i + 1] === c) { t.push(c + c); i += 2; } else { t.push(c); i++; } continue; }
+    cur += c; i++;
+  }
+  if (cur) t.push(cur);
+  return t;
+}
+
+function _splitSegments(tokens) {
+  const segs = [], SEP = new Set([';', '&', '&&', '|', '||', '\n']);
+  let cur = [];
+  for (const t of tokens) { if (SEP.has(t)) { if (cur.length) segs.push(cur); cur = []; } else cur.push(t); }
+  if (cur.length) segs.push(cur);
+  return segs;
+}
+
+function _stripQuotes(t) {
+  if (t.length >= 2) { const a = t[0], b = t[t.length - 1]; if ((a === "'" && b === "'") || (a === '"' && b === '"')) return t.slice(1, -1); }
+  return t;
+}
+
+// Skip env-var assignments and known wrapper commands (with their
+// option arguments) so the underlying program reaches classification.
+function _peelWrappers(tokens) {
+  let i = 0;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) { i++; continue; }
+    if (_WRAPPER_NAMES.has(t)) {
+      i++;
+      while (i < tokens.length && (/^[-+]/.test(tokens[i]) || /^\d+[smhd]?$/.test(tokens[i]) || /^\d+m\d+s?$/.test(tokens[i]))) {
+        // Long option `--key value` — consume the value too when not `=`-joined and the value is non-flag / non-assignment.
+        if (/^--[A-Za-z0-9][\w-]*$/.test(tokens[i]) && i + 1 < tokens.length && !/^[-+]/.test(tokens[i + 1]) && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i + 1])) { i += 2; continue; }
+        i++;
+      }
+      continue;
+    }
+    break;
+  }
+  return tokens.slice(i);
+}
+
+// Extract `-c <payload>` (and `--command <payload>`) for shell invocations.
+// Walks options including combined short flags like `-lc`, `-ic`, `-ec`.
+function _extractShellCInner(s) {
+  const out = [];
+  const tokens = _tokenize(s);
+  const segs = _splitSegments(tokens);
+  for (const seg of segs) {
+    const peeled = _peelWrappers(seg);
+    if (!peeled.length) continue;
+    if (!_SHELL_NAMES.has(peeled[0])) {
+      // Extended: leaf commands that embed an inner command/payload.
+      // The caller re-scans each entry via isBlockedCommand, so we just
+      // surface the payload as a synthetic command string.
+      const leaf = peeled[0];
+      if (leaf === 'xargs' || leaf === 'parallel') {
+        let j = 1;
+        while (j < peeled.length && /^[-+]/.test(peeled[j])) {
+          if (/^--[A-Za-z0-9][\w-]*$/.test(peeled[j]) && j + 1 < peeled.length && !/^[-+]/.test(peeled[j + 1])) { j += 2; continue; }
+          j++;
+        }
+        if (j < peeled.length) out.push(peeled.slice(j).map(_stripQuotes).join(' '));
+      } else if (leaf === 'find') {
+        for (let j = 1; j < peeled.length; j++) {
+          if (peeled[j] === '-exec' || peeled[j] === '-execdir') {
+            const cmd = [];
+            let k = j + 1;
+            while (k < peeled.length && peeled[k] !== ';' && peeled[k] !== '\\;' && peeled[k] !== '+') { cmd.push(_stripQuotes(peeled[k])); k++; }
+            if (cmd.length) out.push(cmd.join(' '));
+            j = k;
+          }
+        }
+      } else if (leaf === 'awk') {
+        for (let j = 1; j < peeled.length; j++) {
+          const t = peeled[j];
+          if (t === '-f' || t === '-v' || t === '-F') { j++; continue; }
+          if (t.startsWith('-')) continue;
+          const body = _stripQuotes(t);
+          const m = body.match(/system\s*\(\s*(['"])([\s\S]*?)\1\s*\)/);
+          if (m) out.push(m[2]);
+          break;
+        }
+      } else if (leaf === 'perl' || leaf === 'node' || leaf === 'python' || leaf === 'python3') {
+        const flag = (leaf === 'python' || leaf === 'python3') ? '-c' : '-e';
+        for (let j = 1; j < peeled.length; j++) {
+          const t = peeled[j];
+          if (t === flag || (leaf === 'perl' && t === '-E')) { const arg = peeled[j + 1]; if (arg) out.push(_stripQuotes(arg)); break; }
+          if (t.startsWith('-')) continue;
+          break;
+        }
+      }
+      continue;
+    }
+    for (let i = 1; i < peeled.length; i++) {
+      const t = peeled[i];
+      if (t === '-c' || t === '--command' || /^-[a-zA-Z]+c$/.test(t)) {
+        const arg = peeled[i + 1];
+        if (arg) out.push(_stripQuotes(arg));
+        break;
+      }
+      if (t === '--rcfile' || t === '--init-file' || t === '-O' || t === '+O') { i++; continue; }
+      if (t.startsWith('-') || t.startsWith('+')) continue;
+      break;
+    }
+  }
+  return out;
+}
+
+// rm: detect -r/-R/--recursive AND -f/--force across split or combined
+// short-flag tokens.
+function _classifyRm(args) {
+  let r = false, f = false;
+  for (const t of args) {
+    if (t === '--') break;
+    if (t === '--recursive' || t === '-r' || t === '-R') { r = true; continue; }
+    if (t === '--force' || t === '-f') { f = true; continue; }
+    if (/^-[a-zA-Z]+$/.test(t)) { if (/[rR]/.test(t)) r = true; if (/f/.test(t)) f = true; continue; }
+    if (t.startsWith('-')) continue;
+    break;
+  }
+  if (r && f) return 'may recursively force-remove files';
+  if (r) return 'may recursively remove files';
+  if (f) return 'may force-remove files';
+  return null;
+}
+
+// PowerShell Remove-Item (and aliases): -Recurse/-Force, including :$true forms.
+// Parity with shell-policy.mjs _removeItemRecursiveForceUnsafe switch matching.
+const _PS_REMOVE_CMDS = new Set(['remove-item', 'ri', 'del', 'erase', 'rd', 'rmdir']);
+
+function _classifyRemoveItem(args) {
+  let r = false, f = false;
+  for (const t of args) {
+    if (t === '--') break;
+    const low = String(t).toLowerCase();
+    if (low.startsWith('-')) {
+      if (/^-r(ec(urse)?)?$/.test(low) || /^-r(ec(urse)?)?:\$true$/i.test(low)) { r = true; continue; }
+      if (/^-fo(rce)?$/.test(low) || /^-fo(rce)?:\$true$/i.test(low)) { f = true; continue; }
+      if (low === '-recurse' || low === '-recursive') { r = true; continue; }
+      if (low === '-force') { f = true; continue; }
+      continue;
+    }
+    break;
+  }
+  if (r && f) return 'may recursively force-remove files';
+  if (r) return 'may recursively remove files';
+  if (f) return 'may force-remove files';
+  return null;
+}
+
+// git: skip global options (-C path, -c key=val, --git-dir=..., --no-pager
+// etc.) before reading the subcommand.
+function _classifyGit(args) {
+  let i = 0;
+  while (i < args.length) {
+    const t = args[i];
+    if (t === '-C' || t === '-c') { i += 2; continue; }
+    if (/^--(git-dir|work-tree|namespace)(=|$)/.test(t)) { i += t.includes('=') ? 1 : 2; continue; }
+    if (t === '--no-pager' || t === '--paginate' || t === '--bare' || t === '--exec-path' || /^--literal-pathspecs|--glob-pathspecs|--noglob-pathspecs|--icase-pathspecs$/.test(t)) { i++; continue; }
+    if (/^--exec-path=|^--list-cmds=/.test(t)) { i++; continue; }
+    break;
+  }
+  const sub = args[i]; if (!sub) return null;
+  const rest = args.slice(i + 1);
+  if (sub === 'reset' && rest.includes('--hard')) return 'may discard uncommitted changes';
+  if (sub === 'push' && rest.some(t => t === '--force' || t === '-f' || t === '--force-with-lease' || t.startsWith('--force-with-lease=') || /^\+[\w/.-]+/.test(t))) return 'may overwrite remote history';
+  if (sub === 'clean') {
+    const dry = rest.some(t => t === '-n' || t === '--dry-run' || /^-[a-zA-Z]*n[a-zA-Z]*$/.test(t));
+    const force = rest.some(t => t === '-f' || t === '--force' || /^-[a-zA-Z]*f[a-zA-Z]*$/.test(t));
+    if (!dry && force) return 'may permanently delete untracked files';
+  }
+  if ((sub === 'checkout' || sub === 'restore') && rest.includes('.')) return 'may discard all working tree changes';
+  if (sub === 'stash' && (rest[0] === 'drop' || rest[0] === 'clear')) return 'may permanently remove stashed changes';
+  if (sub === 'branch' && (rest.includes('-D') || (rest.includes('--delete') && rest.includes('--force')))) return 'may force-delete a branch';
+  if ((sub === 'commit' || sub === 'push' || sub === 'merge') && rest.includes('--no-verify')) return 'may skip safety hooks';
+  if (sub === 'commit' && rest.includes('--amend')) return 'may rewrite the last commit';
+  return null;
+}
+
+const _KUBECTL_VAL = new Set(['--context','--cluster','--namespace','-n','--user','--kubeconfig','--token','--server','--as','--as-group','--certificate-authority','--client-certificate','--client-key','--request-timeout','--cache-dir','--v','-v','--profile','--profile-output']);
+
+function _classifyKubectl(args) {
+  let i = 0;
+  while (i < args.length) {
+    const t = args[i];
+    if (_KUBECTL_VAL.has(t)) { i += 2; continue; }
+    if (t.startsWith('--') && t.includes('=')) { i++; continue; }
+    if (t.startsWith('-')) { i++; continue; }
+    break;
+  }
+  return args[i] === 'delete' ? 'may delete Kubernetes resources' : null;
+}
+
+function _classifyTerraform(args) {
+  let i = 0;
+  while (i < args.length) {
+    const t = args[i];
+    if (/^-chdir=/.test(t) || t === '-help' || t === '-version' || t === '-h') { i++; continue; }
+    break;
+  }
+  return args[i] === 'destroy' ? 'may destroy Terraform infrastructure' : null;
+}
+
+function _classifyDd(args) {
+  for (const t of args) {
+    if (/^if=\/dev\//.test(t)) return 'may read from a raw device';
+    if (/^of=\/dev\//.test(t)) return 'may write to a raw device';
+  }
+  return null;
+}
+
+// DB destructive pattern baseline — security policy, not a heuristic
+// classifier. DROP/TRUNCATE/DELETE without WHERE are unambiguously
+// data-destructive regardless of context; this list is a floor, not a
+// complete SQL auditor.
+const _DB_PATTERNS = [
+  [/\b(DROP|TRUNCATE)\s+(TABLE|DATABASE|SCHEMA)\b/i, 'may drop or truncate database objects'],
+  [/\bDELETE\s+FROM\s+\w+[ \t]*(;|"|'|\n|$)/i, 'may delete all rows from a database table'],
+];
+
+function _classifySegment(tokens) {
+  const peeled = _peelWrappers(tokens);
+  if (!peeled.length) return null;
+  const cmd = peeled[0], rest = peeled.slice(1);
+  const cmdLow = cmd.toLowerCase();
+  if (cmd === 'rm') return _classifyRm(rest);
+  if (_PS_REMOVE_CMDS.has(cmdLow)) {
+    const w = _classifyRemoveItem(rest);
+    if (w) return w;
+  }
+  if (cmd === 'git') return _classifyGit(rest);
+  if (cmd === 'kubectl') return _classifyKubectl(rest);
+  if (cmd === 'terraform') return _classifyTerraform(rest);
+  if (cmd === 'dd') return _classifyDd(rest);
+  if (cmd === 'rmdir' || cmd === 'rd') {
+    const hasS = rest.some(t => /^\/s$/i.test(t));
+    const hasDriveRoot = rest.some(t => /^[A-Za-z]:\\?$/.test(t));
+    if (hasS && hasDriveRoot) return 'may recursively remove a drive root';
+  }
+  return null;
+}
+
+export function getDestructiveCommandWarning(command) {
+  const raw = String(command || '');
+  // Per-statement DB scan (split on `;`, `&&`, `||`, `|`, `\n`) so a
+  // destructive statement past a separator still surfaces.
+  const cleaned = _stripQuotedSpans(raw);
+  for (const stmt of cleaned.split(/[;&|\n]+/)) {
+    for (const [re, warning] of _DB_PATTERNS) if (re.test(stmt)) return warning;
+  }
+  // Tokenized walk per pipeline segment.
+  const segs = _splitSegments(_tokenize(raw));
+  for (const seg of segs) {
+    const peeled = _peelWrappers(seg);
+    if (!peeled.length) continue;
+    if (_SHELL_NAMES.has(peeled[0])) {
+      for (const inner of _extractShellCInner(seg.join(' '))) {
+        const w = getDestructiveCommandWarning(inner);
+        if (w) return w;
+      }
+      for (const body of _extractHeredocBodies(raw)) {
+        const w = getDestructiveCommandWarning(body);
+        if (w) return w;
+      }
+      continue;
+    }
+    const w = _classifySegment(seg);
+    if (w) return w;
+  }
+  for (const inner of _extractShellCInner(raw)) {
+    const w = getDestructiveCommandWarning(inner);
+    if (w) return w;
+  }
+  for (const inner of extractPowerShellCommandInner(raw)) {
+    const w = getDestructiveCommandWarning(inner);
+    if (w) return w;
+  }
+  return null;
+}

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

@@ -0,0 +1,154 @@
+// graph-binary-fetcher.mjs — fetches the prebuilt mixdog-graph native binary
+// from the GitHub release manifest. The code graph has NO JS parse fallback,
+// so the binary is required; ensureGraphBinary downloads + sha256-verifies it
+// on first use and caches it under <dataDir>/graph-bin/. Mirrors the runtime
+// fetcher pattern (memory/lib/runtime-fetcher.mjs) but for a single binary —
+// no tar extraction.
+//
+// Public API:
+//   ensureGraphBinary(dataDir) -> absolute path to the verified binary.
+//     Throws if no asset matches the platform, or download/verify fails.
+//   findCachedGraphBinary(dataDir) -> path | null (sync, no network).
+
+import { createHash } from 'node:crypto';
+import {
+  chmodSync, createWriteStream, existsSync, mkdirSync,
+  readFileSync, readdirSync, renameSync, rmSync,
+} from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pipeline } from 'node:stream/promises';
+
+// Bundled fallback manifest shipped with Mixdog. CI rewrites this on each
+// release with the per-platform asset URLs + sha256.
+const BUNDLED_MANIFEST_PATH = fileURLToPath(new URL('./graph-manifest.json', import.meta.url));
+
+// GitHub raw fallback — only consulted when neither cached nor bundled exists.
+const MANIFEST_URL = 'https://raw.githubusercontent.com/tribgames/mixdog/main/src/runtime/agent/orchestrator/tools/graph-manifest.json';
+
+function binSuffix() {
+  return process.platform === 'win32' ? '.exe' : '';
+}
+
+function platformKey() {
+  const os = process.platform === 'win32' ? 'win32' : process.platform;
+  return `${os}-${process.arch}`;
+}
+
+function graphBinDir(dataDir) {
+  return join(dataDir, 'graph-bin');
+}
+
+async function loadManifest(dataDir) {
+  const cached = join(graphBinDir(dataDir), 'manifest.json');
+  if (existsSync(cached)) {
+    try { return JSON.parse(readFileSync(cached, 'utf8')); } catch { /* fall through */ }
+  }
+  if (existsSync(BUNDLED_MANIFEST_PATH)) {
+    return JSON.parse(readFileSync(BUNDLED_MANIFEST_PATH, 'utf8'));
+  }
+  const res = await fetch(MANIFEST_URL, { signal: AbortSignal.timeout(30_000) });
+  if (!res.ok) throw new Error(`[graph-fetcher] manifest fetch failed: ${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+async function sha256File(filePath) {
+  return createHash('sha256').update(await readFile(filePath)).digest('hex');
+}
+
+async function downloadWithRetry(url, destPath) {
+  // 4 attempts total (1 + 3 retries); backoff 1s/3s/9s. 4xx is terminal.
+  const delays = [1000, 3000, 9000];
+  let lastErr;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(180_000) });
+      if (res.status >= 400 && res.status < 500) {
+        throw new Error(`[graph-fetcher] asset HTTP ${res.status} (terminal) — ${url}`);
+      }
+      if (!res.ok) throw new Error(`[graph-fetcher] asset HTTP ${res.status} — ${url}`);
+      await pipeline(res.body, createWriteStream(destPath));
+      return;
+    } catch (err) {
+      lastErr = err;
+      if (String(err?.message || '').includes('(terminal)')) throw err;
+      if (attempt < 3) {
+        process.stderr.write(`[graph-fetcher] download attempt ${attempt + 1} failed (${err?.message}), retrying in ${delays[attempt]}ms…\n`);
+        await new Promise((r) => setTimeout(r, delays[attempt]));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+// Remove stale binaries + tmp files, keeping the active one.
+function gcGraphBin(dir, keepFile) {
+  try {
+    for (const name of readdirSync(dir)) {
+      if (name === 'manifest.json' || name === keepFile) continue;
+      if (name.startsWith('mixdog-graph')) {
+        try { rmSync(join(dir, name), { force: true }); } catch { /* best-effort */ }
+      }
+    }
+  } catch { /* dir may not exist yet */ }
+}
+
+// Sync, network-free lookup of an already-cached binary. Used by the sync
+// _graphBinaryPath() resolver before falling back to an async fetch.
+export function findCachedGraphBinary(dataDir) {
+  try {
+    const dir = graphBinDir(dataDir);
+    const hit = readdirSync(dir).find(
+      (n) => n.startsWith('mixdog-graph') && !n.endsWith('.json') && !n.includes('.tmp-'),
+    );
+    return hit ? join(dir, hit) : null;
+  } catch {
+    return null;
+  }
+}
+
+let _inflight = null;
+
+export function ensureGraphBinary(dataDir) {
+  // Single-flight: concurrent callers (prewarm + cache-miss) share one download.
+  if (_inflight) return _inflight;
+  _inflight = (async () => {
+    const manifest = await loadManifest(dataDir);
+    const pkey = platformKey();
+    const asset = manifest.assets?.[pkey];
+    if (!asset || !asset.url || !asset.sha256) {
+      // Unsupported platform/arch (e.g. win32-arm64): the manifest has no
+      // downloadable asset for this {os}-{arch}. The code graph has NO JS
+      // parsing fallback, so this is terminal — surface a single clear,
+      // actionable message instead of a cryptic crash downstream.
+      const supported = Object.keys(manifest.assets || {}).join(', ') || '(none)';
+      throw new Error(
+        `[graph-fetcher] no prebuilt mixdog-graph binary for platform ${pkey} `
+        + `(unsupported platform/arch — there is no JS parsing fallback). `
+        + `Supported platforms: ${supported}. `
+        + `Build it locally: cargo build --release in native/mixdog-graph.`,
+      );
+    }
+    const version = String(manifest.version || '0');
+    const dir = graphBinDir(dataDir);
+    mkdirSync(dir, { recursive: true });
+    const fileName = `mixdog-graph-${version}${binSuffix()}`;
+    const destPath = join(dir, fileName);
+    if (existsSync(destPath)) {
+      try { if (await sha256File(destPath) === asset.sha256) return destPath; } catch { /* re-download */ }
+    }
+    const tmpPath = `${destPath}.tmp-${process.pid}-${Date.now()}`;
+    await downloadWithRetry(asset.url, tmpPath);
+    const actual = await sha256File(tmpPath);
+    if (actual !== asset.sha256) {
+      try { rmSync(tmpPath, { force: true }); } catch { /* best-effort */ }
+      throw new Error(`[graph-fetcher] sha256 mismatch for ${pkey}: expected ${asset.sha256}, got ${actual}`);
+    }
+    renameSync(tmpPath, destPath);
+    if (process.platform !== 'win32') { try { chmodSync(destPath, 0o755); } catch { /* best-effort */ } }
+    gcGraphBin(dir, fileName);
+    return destPath;
+  })().finally(() => { _inflight = null; });
+  return _inflight;
+}

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

@@ -0,0 +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.)",
+  "assets": {
+    "darwin-arm64": {
+      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-darwin-arm64",
+      "sha256": "34653a7cdf457295c4835fa9819627e9690c323b6012e6f571259478406bbe04"
+    },
+    "darwin-x64": {
+      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-darwin-x64",
+      "sha256": "1c0648ed8a1b9fd2d8bc44d85b91262cb11e0773d2280d6ec351ee1ff1c579f0"
+    },
+    "linux-arm64": {
+      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-linux-arm64",
+      "sha256": "71c9d69125b97e93466e5a5613c00db2d797c1f25cc4237e776225574c5f6970"
+    },
+    "linux-x64": {
+      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-linux-x64",
+      "sha256": "4800a7ac77b777ddb5862f252cdc00b55230455921e0c58416d7a77b120604a7"
+    },
+    "win32-x64": {
+      "url": "https://github.com/tribgames/mixdog/releases/download/v0.7.18/mixdog-graph-win32-x64.exe",
+      "sha256": "1d0d62f5b78965c7d5b05ebc7cf7bdef1a3e14cc2600aa205ca762e56c446934"
+    }
+  }
+}

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

@@ -0,0 +1,143 @@
+// patch-binary-fetcher.mjs — fetches the prebuilt mixdog-patch native binary
+// from the GitHub release manifest. apply_patch is native-only, so callers
+// surface fetch failures as clean tool errors rather than silently switching
+// engines. Caches under <dataDir>/patch-bin/. Mirrors graph-binary-fetcher.mjs.
+//
+// Public API:
+//   ensurePatchBinary(dataDir) -> absolute path to the verified binary.
+//     Throws on no-asset / download / verify failure.
+//   findCachedPatchBinary(dataDir) -> path | null (sync, no network).
+
+import { createHash } from 'node:crypto';
+import {
+  chmodSync, createWriteStream, existsSync, mkdirSync,
+  readFileSync, readdirSync, renameSync, rmSync,
+} from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pipeline } from 'node:stream/promises';
+
+const BUNDLED_MANIFEST_PATH = fileURLToPath(new URL('./patch-manifest.json', import.meta.url));
+const MANIFEST_URL = 'https://raw.githubusercontent.com/tribgames/mixdog/main/src/runtime/agent/orchestrator/tools/patch-manifest.json';
+
+function binSuffix() {
+  return process.platform === 'win32' ? '.exe' : '';
+}
+
+function platformKey() {
+  const os = process.platform === 'win32' ? 'win32' : process.platform;
+  return `${os}-${process.arch}`;
+}
+
+function patchBinDir(dataDir) {
+  return join(dataDir, 'patch-bin');
+}
+
+async function loadManifest(dataDir) {
+  const cached = join(patchBinDir(dataDir), 'manifest.json');
+  if (existsSync(cached)) {
+    try { return JSON.parse(readFileSync(cached, 'utf8')); } catch { /* fall through */ }
+  }
+  if (existsSync(BUNDLED_MANIFEST_PATH)) {
+    return JSON.parse(readFileSync(BUNDLED_MANIFEST_PATH, 'utf8'));
+  }
+  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();
+}
+
+async function sha256File(filePath) {
+  return createHash('sha256').update(await readFile(filePath)).digest('hex');
+}
+
+async function downloadWithRetry(url, destPath) {
+  const delays = [1000, 3000, 9000];
+  let lastErr;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(180_000) });
+      if (res.status >= 400 && res.status < 500) {
+        throw new Error(`[patch-fetcher] asset HTTP ${res.status} (terminal) — ${url}`);
+      }
+      if (!res.ok) throw new Error(`[patch-fetcher] asset HTTP ${res.status} — ${url}`);
+      await pipeline(res.body, createWriteStream(destPath));
+      return;
+    } catch (err) {
+      lastErr = err;
+      if (String(err?.message || '').includes('(terminal)')) throw err;
+      if (attempt < 3) {
+        process.stderr.write(`[patch-fetcher] download attempt ${attempt + 1} failed (${err?.message}), retrying in ${delays[attempt]}ms…\n`);
+        await new Promise((r) => setTimeout(r, delays[attempt]));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+function gcPatchBin(dir, keepFile) {
+  try {
+    for (const name of readdirSync(dir)) {
+      if (name === 'manifest.json' || name === keepFile) continue;
+      if (name.startsWith('mixdog-patch')) {
+        try { rmSync(join(dir, name), { force: true }); } catch { /* best-effort */ }
+      }
+    }
+  } catch { /* dir may not exist yet */ }
+}
+
+export function findCachedPatchBinary(dataDir) {
+  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;
+  } catch {
+    return null;
+  }
+}
+
+let _inflight = null;
+
+export function ensurePatchBinary(dataDir) {
+  if (_inflight) return _inflight;
+  _inflight = (async () => {
+    const manifest = await loadManifest(dataDir);
+    const pkey = platformKey();
+    const asset = manifest.assets?.[pkey];
+    if (!asset || !asset.url || !asset.sha256) {
+      // 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,
+      // actionable message instead of a cryptic crash downstream.
+      const supported = Object.keys(manifest.assets || {}).join(', ') || '(none)';
+      throw new Error(
+        `[patch-fetcher] no prebuilt mixdog-patch binary for platform ${pkey} `
+        + `(unsupported platform/arch — apply_patch is native-only, no JS apply fallback). `
+        + `Supported platforms: ${supported}. `
+        + `Build it locally: cargo build --release in native/mixdog-patch.`,
+      );
+    }
+    const version = String(manifest.version || '0');
+    const dir = patchBinDir(dataDir);
+    mkdirSync(dir, { recursive: true });
+    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 */ }
+    }
+    const tmpPath = `${destPath}.tmp-${process.pid}-${Date.now()}`;
+    await downloadWithRetry(asset.url, tmpPath);
+    const actual = await sha256File(tmpPath);
+    if (actual !== asset.sha256) {
+      try { rmSync(tmpPath, { force: true }); } catch { /* best-effort */ }
+      throw new Error(`[patch-fetcher] sha256 mismatch for ${pkey}: expected ${asset.sha256}, got ${actual}`);
+    }
+    renameSync(tmpPath, destPath);
+    if (process.platform !== 'win32') { try { chmodSync(destPath, 0o755); } catch { /* best-effort */ } }
+    gcPatchBin(dir, fileName);
+    return destPath;
+  })().finally(() => { _inflight = null; });
+  return _inflight;
+}

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

@@ -0,0 +1,18 @@
+export const PATCH_TOOL_DEFS = [
+  {
+    name: 'apply_patch',
+    title: 'Mixdog Apply Patch',
+    annotations: { title: 'Mixdog Apply Patch', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false, compressible: false, compressibleLossless: true },
+    description: 'Apply file patches. Prefer V4A with one file block per target file and exact current context around each edit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        patch: { type: 'string', description: 'Patch text only. V4A preferred: `*** Begin Patch` envelope and `*** Update/Add/Delete File: <path>` blocks. Use one block per target file, combining all hunks for that file. Copy exact current context around edits.' },
+        format: { type: 'string', enum: ['unified', 'v4a'], description: 'Auto-detected. Prefer v4a; unified needs counted @@ headers.' },
+        base_path: { type: 'string', description: 'Repo root so a/... paths resolve.' },
+        dry_run: { type: 'boolean', description: 'Default false. true = validate only, no write.' },
+      },
+      required: ['patch'],
+    },
+  },
+];