@octocodeai/freellama-mcp-server 0.6.2 → 0.9.0

package/dist/research/coder-agent.js

@@ -0,0 +1,4668 @@
+// src/research/coder-agent.ts
+import { createHash as createHash3 } from "node:crypto";
+import { existsSync as existsSync8, mkdirSync as mkdirSync6, readFileSync as readFileSync9, realpathSync as realpathSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import path12 from "node:path";
+
+// src/research/canonical-json.ts
+function canonicalJson(value, options = {}) {
+  const { sortKeys = true, ensureAscii = true, separators: [item, colon] = [", ", ": "], floatKeys } = options;
+  const quote = (text) => {
+    const json = JSON.stringify(text);
+    return ensureAscii ? json.replace(/[\u007f-\uffff]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`) : json;
+  };
+  const render = (node, float) => {
+    if (node === null) return "null";
+    if (typeof node === "string") return quote(node);
+    if (typeof node === "boolean") return String(node);
+    if (typeof node === "number") return numberText(node, float);
+    if (Array.isArray(node)) return `[${node.map((entry) => render(entry, false)).join(item)}]`;
+    if (typeof node === "object") {
+      const record = node;
+      const keys = Object.keys(record).filter((key) => record[key] !== void 0);
+      if (sortKeys) keys.sort();
+      return `{${keys.map((key) => `${quote(key)}${colon}${render(record[key], floatKeys?.has(key) ?? false)}`).join(item)}}`;
+    }
+    throw new TypeError(`cannot serialize a ${typeof node} as JSON`);
+  };
+  return render(value, false);
+}
+function numberText(value, float) {
+  if (!Number.isFinite(value)) throw new RangeError(`cannot serialize ${value} as JSON`);
+  if (Number.isInteger(value) && !float) return Math.abs(value) < 1e21 ? String(value) : BigInt(value).toString();
+  const [mantissa, power] = value.toExponential().split("e");
+  const exponent = Number(power);
+  if (value !== 0 && (exponent < -4 || exponent >= 16)) {
+    return `${mantissa}e${exponent < 0 ? "-" : "+"}${String(Math.abs(exponent)).padStart(2, "0")}`;
+  }
+  const text = String(value);
+  return Number.isInteger(value) ? `${text}.0` : text;
+}
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// src/research/errors.ts
+var ValidationError = class extends Error {
+  name = "ValidationError";
+};
+function isSystemError(error) {
+  return error instanceof Error && typeof error.errno === "number";
+}
+var ToolTimeoutError = class extends Error {
+  name = "ToolTimeoutError";
+};
+var ToolExitError = class extends Error {
+  constructor(exitCode, output, status = "error") {
+    super(`${status === "empty" ? "nothing found" : "command failed"} (exit code ${exitCode})` + (output ? `
+${output}` : ""));
+    this.exitCode = exitCode;
+    this.output = output;
+    this.status = status;
+  }
+  exitCode;
+  output;
+  status;
+  name = "ToolExitError";
+};
+function isToolError(error) {
+  return error instanceof ValidationError || error instanceof ToolTimeoutError || error instanceof ToolExitError || error instanceof SyntaxError || isSystemError(error);
+}
+
+// src/research/actions.ts
+function objectAt(text, start) {
+  let depth = 0;
+  let inString = false;
+  for (let index = start; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      if (char === "\\") index += 1;
+      else if (char === '"') inString = false;
+    } else if (char === '"') {
+      inString = true;
+    } else if (char === "{" || char === "[") {
+      depth += 1;
+    } else if (char === "}" || char === "]") {
+      depth -= 1;
+      if (depth === 0) return JSON.parse(text.slice(start, index + 1));
+    }
+  }
+  throw new SyntaxError("unterminated JSON object");
+}
+function parseJsonAction(content) {
+  let text = content.trim();
+  if (text.startsWith("```")) text = text.split(/\r\n|\r|\n/).slice(1, -1).join("\n").trim();
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    const start = text.indexOf("{");
+    if (start < 0) throw new ValidationError("model did not return a JSON action");
+    try {
+      value = objectAt(text, start);
+    } catch (inner) {
+      if (!(inner instanceof SyntaxError)) throw inner;
+      throw new ValidationError("model did not return a valid JSON action");
+    }
+  }
+  if (!isRecord(value) || typeof value.action !== "string") throw new ValidationError("model action must be a JSON object with an action");
+  return value;
+}
+function callSignature(payload) {
+  return canonicalJson(payload, { ensureAscii: false });
+}
+var REPEAT_NOTICE = "(identical call already made this run \u2014 its result is above and was not re-executed. Use a different call, or finish now with the evidence already collected.)";
+var PARSE_REPAIR_NOTICE = "Your last reply was not a valid JSON action, so it was discarded. Reply with EXACTLY one JSON object and nothing else \u2014 no prose before or after, no markdown fence. Use the action shapes given in your instructions. If you already have enough evidence, send the finish action now.";
+
+// src/research/adapter.ts
+function isPositiveInt(value) {
+  return (typeof value === "boolean" || typeof value === "number" && Number.isInteger(value)) && Number(value) >= 1;
+}
+
+// src/research/agent-loop.ts
+import { readFileSync as readFileSync5 } from "node:fs";
+import { performance as performance2 } from "node:perf_hooks";
+import { setTimeout as sleep } from "node:timers/promises";
+
+// src/research/context-manager.ts
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+// src/research/context-policy.ts
+var CHARS_PER_TOKEN = 4;
+var SAFETY_MARGIN_TOKENS = 256;
+var IMAGE_TOKEN_ESTIMATE = 1024;
+var DEFAULT_KEEP_RECENT = 2;
+var COMPACT_PREVIEW_CHARS = 180;
+var COMPACT_RETAIN_RATIO = 0.8;
+var CLIP_HEAD_RATIO = 2 / 3;
+var OBSERVATION_PAGE_CHARS = 3e3;
+var COMPACTION_TARGET_RATIO = 0.9;
+var MAX_PARSE_REPAIRS = 2;
+var INTEGER = /^[+-]?[0-9]+$/;
+var DECIMAL = /^[+-]?(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$/;
+function envInt(env, name, defaultValue, minimum = 0) {
+  const raw = env[name];
+  if (raw === void 0 || raw === "") return defaultValue;
+  if (!INTEGER.test(raw.trim())) throw new ValidationError(`${name} must be an integer, got ${JSON.stringify(raw)}`);
+  const value = Number(raw.trim());
+  if (value < minimum) throw new ValidationError(`${name} must be >= ${minimum}, got ${value}`);
+  return value;
+}
+function envFloat(env, name, defaultValue, minimum = 0) {
+  const raw = env[name];
+  if (raw === void 0 || raw === "") return defaultValue;
+  const value = Number(raw.trim());
+  if (!DECIMAL.test(raw.trim())) throw new ValidationError(`${name} must be a number, got ${JSON.stringify(raw)}`);
+  if (!Number.isFinite(value) || value < minimum) {
+    throw new ValidationError(`${name} must be finite and >= ${minimum}, got ${JSON.stringify(raw)}`);
+  }
+  return value;
+}
+function envBool(env, name, defaultValue) {
+  const raw = env[name];
+  if (raw === void 0 || raw === "") return defaultValue;
+  const normalized = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  throw new ValidationError(`${name} must be true/false, got ${JSON.stringify(raw)}`);
+}
+function contextBudget(numCtx, numPredict, safetyMarginTokens = SAFETY_MARGIN_TOKENS) {
+  return Math.max(numCtx - numPredict - safetyMarginTokens, 0);
+}
+var ContextPolicy = class _ContextPolicy {
+  fields;
+  /**
+   * Fields configured from the environment. They are floats, so canonical JSON (calibration keys)
+   * renders them as floats: `FREELLAMA_AGENT_CHARS_PER_TOKEN=8` gives `8.0`, the default gives `4`.
+   */
+  floatKeys;
+  constructor(fields = {}, floatKeys = []) {
+    this.fields = {
+      chars_per_token: fields.chars_per_token ?? CHARS_PER_TOKEN,
+      safety_margin_tokens: fields.safety_margin_tokens ?? SAFETY_MARGIN_TOKENS,
+      image_token_estimate: fields.image_token_estimate ?? IMAGE_TOKEN_ESTIMATE,
+      keep_recent: fields.keep_recent ?? DEFAULT_KEEP_RECENT,
+      compact_preview_chars: fields.compact_preview_chars ?? COMPACT_PREVIEW_CHARS,
+      compact_retain_ratio: fields.compact_retain_ratio ?? COMPACT_RETAIN_RATIO,
+      clip_head_ratio: fields.clip_head_ratio ?? CLIP_HEAD_RATIO,
+      observation_page_chars: fields.observation_page_chars ?? OBSERVATION_PAGE_CHARS,
+      pinned_overflow: fields.pinned_overflow ?? "error"
+    };
+    this.floatKeys = new Set(floatKeys);
+    const f = this.fields;
+    if (!Number.isFinite(f.chars_per_token) || f.chars_per_token <= 0) throw new ValidationError("chars_per_token must be finite and > 0");
+    if (f.safety_margin_tokens < 0 || f.image_token_estimate < 0 || f.keep_recent < 0) {
+      throw new ValidationError("context token estimates and keep_recent must be >= 0");
+    }
+    if (f.compact_preview_chars <= 0 || f.observation_page_chars <= 0) throw new ValidationError("preview and page sizes must be > 0");
+    if (!(f.compact_retain_ratio > 0 && f.compact_retain_ratio < 1)) throw new ValidationError("compact_retain_ratio must be between 0 and 1");
+    if (!(f.clip_head_ratio > 0 && f.clip_head_ratio < 1)) throw new ValidationError("clip_head_ratio must be between 0 and 1");
+    if (f.pinned_overflow !== "error" && f.pinned_overflow !== "clip") throw new ValidationError("pinned_overflow must be 'error' or 'clip'");
+  }
+  get chars_per_token() {
+    return this.fields.chars_per_token;
+  }
+  get safety_margin_tokens() {
+    return this.fields.safety_margin_tokens;
+  }
+  get image_token_estimate() {
+    return this.fields.image_token_estimate;
+  }
+  get keep_recent() {
+    return this.fields.keep_recent;
+  }
+  get compact_preview_chars() {
+    return this.fields.compact_preview_chars;
+  }
+  get compact_retain_ratio() {
+    return this.fields.compact_retain_ratio;
+  }
+  get clip_head_ratio() {
+    return this.fields.clip_head_ratio;
+  }
+  get observation_page_chars() {
+    return this.fields.observation_page_chars;
+  }
+  get pinned_overflow() {
+    return this.fields.pinned_overflow;
+  }
+  static fromEnv(env = process.env) {
+    const floats = [
+      ["chars_per_token", "FREELLAMA_AGENT_CHARS_PER_TOKEN"],
+      ["compact_retain_ratio", "FREELLAMA_AGENT_COMPACT_RETAIN_RATIO"],
+      ["clip_head_ratio", "FREELLAMA_AGENT_CLIP_HEAD_RATIO"]
+    ];
+    return new _ContextPolicy({
+      chars_per_token: envFloat(env, "FREELLAMA_AGENT_CHARS_PER_TOKEN", CHARS_PER_TOKEN, 1e-6),
+      safety_margin_tokens: envInt(env, "FREELLAMA_AGENT_SAFETY_MARGIN_TOKENS", SAFETY_MARGIN_TOKENS),
+      image_token_estimate: envInt(env, "FREELLAMA_AGENT_IMAGE_TOKEN_ESTIMATE", IMAGE_TOKEN_ESTIMATE),
+      keep_recent: envInt(env, "FREELLAMA_AGENT_KEEP_RECENT", DEFAULT_KEEP_RECENT),
+      compact_preview_chars: envInt(env, "FREELLAMA_AGENT_COMPACT_PREVIEW_CHARS", COMPACT_PREVIEW_CHARS, 1),
+      compact_retain_ratio: envFloat(env, "FREELLAMA_AGENT_COMPACT_RETAIN_RATIO", COMPACT_RETAIN_RATIO, 1e-6),
+      clip_head_ratio: envFloat(env, "FREELLAMA_AGENT_CLIP_HEAD_RATIO", CLIP_HEAD_RATIO, 1e-6),
+      observation_page_chars: envInt(env, "FREELLAMA_AGENT_OBSERVATION_PAGE_CHARS", OBSERVATION_PAGE_CHARS, 1),
+      pinned_overflow: (env.FREELLAMA_AGENT_PINNED_OVERFLOW ?? "error").trim().toLowerCase()
+    }, floats.filter(([, name]) => env[name] !== void 0 && env[name] !== "").map(([key]) => key));
+  }
+  metadata() {
+    return { ...this.fields };
+  }
+};
+var AgentRuntimeConfig = class _AgentRuntimeConfig {
+  constructor(fields) {
+    this.fields = fields;
+  }
+  fields;
+  get max_turns() {
+    return this.fields.max_turns;
+  }
+  get num_ctx() {
+    return this.fields.num_ctx;
+  }
+  get num_predict() {
+    return this.fields.num_predict;
+  }
+  get temperature() {
+    return this.fields.temperature;
+  }
+  get seed() {
+    return this.fields.seed;
+  }
+  get request_timeout_seconds() {
+    return this.fields.request_timeout_seconds;
+  }
+  get retry_attempts() {
+    return this.fields.retry_attempts;
+  }
+  get retry_backoff_seconds() {
+    return this.fields.retry_backoff_seconds;
+  }
+  get tool_timeout_seconds() {
+    return this.fields.tool_timeout_seconds;
+  }
+  get keep_alive() {
+    return this.fields.keep_alive;
+  }
+  get think() {
+    return this.fields.think;
+  }
+  get max_parse_repairs() {
+    return this.fields.max_parse_repairs;
+  }
+  get parse_repair_echo_chars() {
+    return this.fields.parse_repair_echo_chars;
+  }
+  get context() {
+    return this.fields.context;
+  }
+  static fromEnv(options) {
+    const env = options.env ?? process.env;
+    const context = ContextPolicy.fromEnv(env);
+    const config = new _AgentRuntimeConfig({
+      max_turns: envInt(env, "FREELLAMA_AGENT_MAX_TURNS", 10, 1),
+      num_ctx: envInt(env, "FREELLAMA_AGENT_NUM_CTX", 8192, 1),
+      num_predict: envInt(env, "FREELLAMA_AGENT_NUM_PREDICT", 512, 1),
+      temperature: envFloat(env, "FREELLAMA_AGENT_TEMPERATURE", 0),
+      seed: envInt(env, "FREELLAMA_AGENT_SEED", 42),
+      request_timeout_seconds: envFloat(env, "FREELLAMA_AGENT_REQUEST_TIMEOUT_SECONDS", 600, 1e-3),
+      retry_attempts: envInt(env, "FREELLAMA_AGENT_RETRY_ATTEMPTS", 2, 1),
+      retry_backoff_seconds: envFloat(env, "FREELLAMA_AGENT_RETRY_BACKOFF_SECONDS", 5),
+      tool_timeout_seconds: envFloat(env, "FREELLAMA_AGENT_TOOL_TIMEOUT_SECONDS", options.defaultToolTimeoutSeconds, 1e-3),
+      keep_alive: (env.FREELLAMA_AGENT_KEEP_ALIVE ?? "5m").trim(),
+      think: envBool(env, "FREELLAMA_AGENT_THINK", false),
+      max_parse_repairs: envInt(env, "FREELLAMA_AGENT_MAX_PARSE_REPAIRS", MAX_PARSE_REPAIRS, 0),
+      parse_repair_echo_chars: envInt(env, "FREELLAMA_AGENT_PARSE_REPAIR_ECHO_CHARS", 500, 1),
+      context
+    });
+    if (contextBudget(config.num_ctx, config.num_predict, context.safety_margin_tokens) <= 0) {
+      throw new ValidationError("FREELLAMA_AGENT_NUM_CTX must exceed FREELLAMA_AGENT_NUM_PREDICT plus FREELLAMA_AGENT_SAFETY_MARGIN_TOKENS");
+    }
+    if (!config.keep_alive) throw new ValidationError("FREELLAMA_AGENT_KEEP_ALIVE must not be empty");
+    return config;
+  }
+  metadata() {
+    const { context: _context, ...rest } = this.fields;
+    return { ...rest };
+  }
+};
+
+// src/research/text.ts
+var SPACE_CLASS = "\\p{White_Space}\\x1c-\\x1f";
+var SPACE = new RegExp(`^[${SPACE_CLASS}]$`, "u");
+var EDGE_SPACE = new RegExp(`^[${SPACE_CLASS}]+|[${SPACE_CLASS}]+$`, "gu");
+var isSpace = (char) => char !== void 0 && SPACE.test(char);
+var trimSpace = (text) => text.replace(EDGE_SPACE, "");
+var ASTRAL = /[\uD800-\uDBFF][\uDC00-\uDFFF]/;
+function cpLength(text) {
+  if (!ASTRAL.test(text)) return text.length;
+  let count = 0;
+  for (const _ of text) count += 1;
+  return count;
+}
+function cpAdvance(text, start, count) {
+  let index = start;
+  for (let step = 0; step < count && index < text.length; step += 1) {
+    const code = text.charCodeAt(index);
+    const pair = code >= 55296 && code <= 56319 && index + 1 < text.length && text.charCodeAt(index + 1) >= 56320 && text.charCodeAt(index + 1) <= 57343;
+    index += pair ? 2 : 1;
+  }
+  return index;
+}
+function cpSlice(text, start, end) {
+  if (!ASTRAL.test(text)) return text.slice(start, end);
+  const from = cpAdvance(text, 0, start);
+  if (end === void 0) return text.slice(from);
+  if (end <= start) return "";
+  return text.slice(from, cpAdvance(text, from, end - start));
+}
+function cpTail(text, count) {
+  const length = cpLength(text);
+  return count >= length ? text : cpSlice(text, length - count);
+}
+var UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+function decodeUtf8(bytes, source) {
+  try {
+    return UTF8.decode(bytes);
+  } catch {
+    throw new ValidationError(`${source} is not valid UTF-8`);
+  }
+}
+function normalizeNewlines(text) {
+  return text.replace(/\r\n?/g, "\n");
+}
+
+// src/research/fit.ts
+var COMPACT_MARKER = "[earlier observation compacted to save context";
+var estimateText = (value) => canonicalJson(value, { sortKeys: false, ensureAscii: false });
+function estimateTokens(text, charsPerToken = CHARS_PER_TOKEN) {
+  return Math.floor(cpLength(text) / charsPerToken) + 1;
+}
+var UNMEASURED_BYTES_PER_TOKEN_MILLI = 3e3;
+function platformBytesPerTokenMilli(learnedMilli) {
+  if (learnedMilli === null || learnedMilli === void 0) return UNMEASURED_BYTES_PER_TOKEN_MILLI;
+  return Math.min(Math.max(Math.floor(learnedMilli / 10) * 9, 1e3), 8e3);
+}
+function platformTextTokens(text, learnedMilli) {
+  return Math.ceil(Buffer.byteLength(text, "utf8") * 1e3 / platformBytesPerTokenMilli(learnedMilli));
+}
+function messagesTokens(messages, policy = new ContextPolicy(), learnedMilli = null) {
+  let total = 0;
+  for (const message of messages) {
+    const { images = [], ...text } = message;
+    if (Array.isArray(images)) total += images.length * policy.image_token_estimate;
+    if (learnedMilli !== null) {
+      total += platformTextTokens(JSON.stringify(text), learnedMilli) + 1;
+      continue;
+    }
+    const { content = "", ...metadata } = text;
+    total += estimateTokens(typeof content === "string" ? content : estimateText(content), policy.chars_per_token);
+    total += estimateTokens(estimateText(metadata), policy.chars_per_token);
+  }
+  return total;
+}
+var ContextBudgeter = class {
+  policy;
+  platformRatio;
+  scale;
+  calibration_samples;
+  constructor(policy = new ContextPolicy(), options = {}) {
+    this.policy = policy;
+    this.platformRatio = options.platformRatio ?? null;
+    this.scale = this.platformRatio ? 1 : Math.max(options.initialScale ?? 1, 1);
+    this.calibration_samples = this.platformRatio ? 0 : Math.max(Math.trunc(options.calibrationSamples ?? 0), 0);
+  }
+  estimate = (messages) => this.platformRatio ? messagesTokens(messages, this.policy, this.platformRatio.bytes_per_token_milli) : Math.ceil(messagesTokens(messages, this.policy) * this.scale);
+  /** Calibrate the fallback estimate; returns whether the multiplier rose (and should persist). */
+  observe(messages, promptEvalCount) {
+    if (this.platformRatio) return false;
+    if (typeof promptEvalCount !== "number" || !Number.isFinite(promptEvalCount)) return false;
+    const actual = Math.trunc(promptEvalCount);
+    if (actual <= 0) return false;
+    const baseline = Math.max(messagesTokens(messages, this.policy), 1);
+    const previous = this.scale;
+    this.scale = Math.max(this.scale, actual / baseline);
+    this.calibration_samples += 1;
+    return this.scale > previous;
+  }
+  metadata() {
+    const ratio = this.platformRatio;
+    return {
+      token_counting: ratio ? "platform_learned_ratio" : "local_chars_per_token",
+      estimate_scale: Math.round(this.scale * 1e6) / 1e6,
+      calibration_samples: this.calibration_samples,
+      bytes_per_token_milli: ratio?.bytes_per_token_milli ?? null,
+      bytes_per_token_milli_with_margin: ratio ? platformBytesPerTokenMilli(ratio.bytes_per_token_milli) : null,
+      bytes_per_token_samples: ratio?.bytes_per_token_samples ?? null
+    };
+  }
+};
+function clip(text, limit, headRatio = CLIP_HEAD_RATIO) {
+  if (!(headRatio > 0 && headRatio < 1)) throw new ValidationError("head_ratio must be between 0 and 1");
+  const length = cpLength(text);
+  if (limit <= 0 || length <= limit) return text;
+  const marker = (dropped2) => `
+\u2026 [${dropped2} characters elided] \u2026
+`;
+  const usable = Math.max(limit - cpLength(marker(length)), 0);
+  if (usable === 0) return cpSlice(text, 0, limit);
+  const headChars = Math.trunc(usable * headRatio);
+  const tailChars = usable - headChars;
+  const dropped = length - headChars - tailChars;
+  const tail = tailChars ? cpTail(text, tailChars) : "";
+  return cpSlice(text, 0, headChars) + marker(dropped) + tail;
+}
+var STEP_HEADER = /^Observation \(step ([0-9]+)\):\n/;
+var LOOP_REMINDER = /\n\n(?:Commands|Tool calls) remaining: [0-9]+\. Finish now if the task is answerable; do not repeat prior (?:commands|calls)\.(?=\n?$)/g;
+var PAGE_FOOTER = /\n\n\[page ([0-9]+) of ([0-9]+) — [0-9]+ characters total, nothing discarded\. /;
+var decimal = (digits) => BigInt(digits).toString();
+function compact(content, policy) {
+  if (content.startsWith(COMPACT_MARKER)) return content;
+  const stepMatch = STEP_HEADER.exec(content);
+  let recovery = "";
+  let body = content;
+  if (stepMatch) {
+    const step = decimal(stepMatch[1]);
+    body = content.slice(stepMatch[0].length);
+    const newline = body.indexOf("\n");
+    const ledgerLine = newline < 0 ? body : body.slice(0, newline);
+    const ledger = ledgerLine.startsWith("[evidence ledger: ") && ledgerLine.endsWith("]") ? ledgerLine : "";
+    if (ledger && newline >= 0) body = body.slice(newline + 1);
+    body = body.replace(LOOP_REMINDER, "");
+    const footer = PAGE_FOOTER.exec(body);
+    const page = footer ? decimal(footer[1]) : "1";
+    const total = footer ? decimal(footer[2]) : "1";
+    if (footer) body = body.slice(0, footer.index);
+    recovery = `; step ${step}, page ${page} of ${total}; retrieve stored output: {"action":"page","step":${step},"page":${page}}`;
+    if (ledger) recovery += `; ${ledger}`;
+  }
+  const preview = clip(body, policy.compact_preview_chars, policy.clip_head_ratio);
+  return `${COMPACT_MARKER}${recovery}] ${preview}`;
+}
+var textContent = (message) => typeof message?.content === "string" ? message.content : null;
+var contentLength = (message) => cpLength(textContent(message) ?? "");
+function widestIndex(indexes2, messages) {
+  let best;
+  let bestLength = -1;
+  for (const index of indexes2) {
+    const length = contentLength(messages[index]);
+    if (length > bestLength) {
+      best = index;
+      bestLength = length;
+    }
+  }
+  return best;
+}
+function textCandidates(messages, from, to, minimum) {
+  const result = [];
+  for (let index = from; index < to; index += 1) {
+    if (textContent(messages[index]) !== null && contentLength(messages[index]) > minimum) result.push(index);
+  }
+  return result;
+}
+function fitToContext(messages, options) {
+  const policy = options.policy ?? new ContextPolicy();
+  const keepRecent = options.keepRecent ?? policy.keep_recent;
+  const budget = contextBudget(options.numCtx, options.numPredict, policy.safety_margin_tokens);
+  const count = options.tokenCounter ?? ((value) => messagesTokens(value, policy));
+  if (count(messages) <= budget) return [messages, false];
+  const pinned = Math.min(2, messages.length);
+  const trimmed = messages.map((message) => ({ ...message }));
+  const observations = [];
+  for (let index = pinned; index < trimmed.length; index += 1) {
+    const role = trimmed[index].role;
+    if ((role === "user" || role === "tool") && textContent(trimmed[index]) !== null) observations.push(index);
+  }
+  const protectedIndexes = new Set(keepRecent ? observations.slice(-keepRecent) : []);
+  let compacted = false;
+  const target = Math.floor(budget * COMPACTION_TARGET_RATIO);
+  for (const index of observations) {
+    if (count(trimmed) <= target) break;
+    if (protectedIndexes.has(index)) continue;
+    const content = textContent(trimmed[index]);
+    const replacement = compact(content, policy);
+    if (cpLength(replacement) < cpLength(content)) {
+      trimmed[index].content = replacement;
+      compacted = true;
+    }
+  }
+  const shrinkWidest = (candidates) => {
+    const widest = widestIndex(candidates, trimmed);
+    if (widest === void 0) return false;
+    const content = textContent(trimmed[widest]) ?? "";
+    const keep = Math.max(Math.trunc(cpLength(content) * policy.compact_retain_ratio), policy.compact_preview_chars);
+    if (keep >= cpLength(content)) return false;
+    trimmed[widest].content = clip(content, keep, policy.clip_head_ratio);
+    compacted = true;
+    return true;
+  };
+  for (let guard = 0; count(trimmed) > budget && guard < 200; guard += 1) {
+    if (!shrinkWidest(observations)) break;
+  }
+  for (const message of trimmed.slice(pinned, Math.max(trimmed.length - 2, pinned))) {
+    const thinking = message.thinking;
+    if (count(trimmed) <= budget) break;
+    if (typeof thinking === "string" && cpLength(thinking) > policy.compact_preview_chars) {
+      message.thinking = compact(thinking, policy);
+      compacted = true;
+    }
+  }
+  for (let guard = 0; count(trimmed) > budget && guard < 200; guard += 1) {
+    const candidates = textCandidates(trimmed, pinned, trimmed.length, policy.compact_preview_chars);
+    if (candidates.length === 0 || !shrinkWidest(candidates)) break;
+  }
+  for (let guard = 0; policy.pinned_overflow === "clip" && count(trimmed) > budget && guard < 200; guard += 1) {
+    const candidates = textCandidates(trimmed, 0, pinned, policy.compact_preview_chars);
+    if (candidates.length === 0 || !shrinkWidest(candidates)) break;
+  }
+  if (count(trimmed) > budget) {
+    throw new ValidationError(
+      `pinned system/question content and minimum history exceed context budget: ${count(trimmed)} > ${budget} estimated tokens. Increase FREELLAMA_AGENT_NUM_CTX, reduce the task/instructions, or explicitly set FREELLAMA_AGENT_PINNED_OVERFLOW=clip.`
+    );
+  }
+  return [trimmed, compacted];
+}
+
+// src/research/context-manager.ts
+function timeNs() {
+  const subMillis = process.hrtime.bigint() % 1000000n;
+  return (BigInt(Date.now()) * 1000000n + subMillis).toString();
+}
+var AgentContextManager = class {
+  runtime;
+  model;
+  calibrationDir;
+  calibrationIdentity;
+  budgeter;
+  calibrationSource;
+  compactions = 0;
+  constructor(runtime, options = {}) {
+    this.runtime = runtime;
+    this.model = options.model ?? "";
+    const platformRatio = options.platformRatio ?? null;
+    this.calibrationDir = platformRatio ? null : options.calibrationDir ?? null;
+    this.calibrationIdentity = options.calibrationIdentity ?? "";
+    const loaded = this.loadCalibration();
+    this.budgeter = new ContextBudgeter(runtime.context, {
+      initialScale: loaded?.scale ?? 1,
+      calibrationSamples: loaded?.samples ?? 0,
+      platformRatio
+    });
+    this.calibrationSource = platformRatio ? "not_applied" : loaded ? "persistent_model_cache" : "current_process";
+  }
+  modelKey() {
+    return createHash("sha256").update(this.calibrationContractJson(), "utf8").digest("hex").slice(0, 24);
+  }
+  calibrationContract() {
+    return {
+      schema_version: 2,
+      model: this.model,
+      identity: this.calibrationIdentity,
+      estimator_version: 1,
+      chars_per_token: this.runtime.context.chars_per_token,
+      image_token_estimate: this.runtime.context.image_token_estimate
+    };
+  }
+  /** The canonical JSON the model key hashes. */
+  calibrationContractJson() {
+    return canonicalJson(this.calibrationContract(), { floatKeys: this.runtime.context.floatKeys });
+  }
+  /** One persisted calibration record: the contract plus the float `scale` and integer `samples`. */
+  calibrationRecordJson(scale, samples) {
+    const floatKeys = /* @__PURE__ */ new Set([...this.runtime.context.floatKeys, "scale"]);
+    return `${canonicalJson({ ...this.calibrationContract(), scale, samples }, { floatKeys })}
+`;
+  }
+  /** Record files `<key>-*.json`; the key is hexadecimal, so only the literal affixes matter. */
+  records(directory, key) {
+    const prefix = `${key}-`;
+    return readdirSync(directory).filter((name) => name.startsWith(prefix) && name.endsWith(".json") && name.length >= prefix.length + 5);
+  }
+  loadCalibration() {
+    if (!this.model || this.calibrationDir === null || !existsSync(this.calibrationDir)) return null;
+    let bestScale = 1;
+    let samples = 0;
+    const contract = this.calibrationContract();
+    for (const name of this.records(this.calibrationDir, this.modelKey())) {
+      let record;
+      try {
+        record = JSON.parse(readFileSync(path.join(this.calibrationDir, name), "utf8"));
+      } catch {
+        continue;
+      }
+      if (!isRecord(record)) continue;
+      if (Object.entries(contract).some(([key, value]) => record[key] !== value)) continue;
+      const scale = record.scale ?? 1;
+      const recordSamples = record.samples ?? 0;
+      if (typeof scale !== "number" || typeof recordSamples !== "number") continue;
+      if (!Number.isFinite(scale) || scale < 1 || !(Math.trunc(recordSamples) > 0)) continue;
+      bestScale = Math.max(bestScale, scale);
+      samples = Math.max(samples, Math.trunc(recordSamples));
+    }
+    return samples ? { scale: bestScale, samples } : null;
+  }
+  persistCalibration() {
+    if (!this.model || this.calibrationDir === null) return;
+    mkdirSync(this.calibrationDir, { recursive: true });
+    const key = this.modelKey();
+    const stem = `${key}-${timeNs()}-${process.pid}`;
+    const temporary = path.join(this.calibrationDir, `${stem}.tmp`);
+    writeFileSync(temporary, this.calibrationRecordJson(this.budgeter.scale, this.budgeter.calibration_samples), "utf8");
+    renameSync(temporary, path.join(this.calibrationDir, `${stem}.json`));
+    const records = this.records(this.calibrationDir, key).sort();
+    for (const stale of records.slice(0, Math.max(records.length - 32, 0))) {
+      try {
+        unlinkSync(path.join(this.calibrationDir, stale));
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+  }
+  fit(messages) {
+    const [fitted, compacted] = fitToContext(messages, {
+      numCtx: this.runtime.num_ctx,
+      numPredict: this.runtime.num_predict,
+      policy: this.runtime.context,
+      tokenCounter: this.budgeter.estimate
+    });
+    this.compactions += compacted ? 1 : 0;
+    return fitted;
+  }
+  observe(messages, promptEvalCount) {
+    if (this.budgeter.observe(messages, promptEvalCount)) this.persistCalibration();
+  }
+  metadata() {
+    return {
+      ...this.runtime.context.metadata(),
+      ...this.budgeter.metadata(),
+      calibration_source: this.calibrationSource,
+      calibration_scope: this.calibrationIdentity ? "provided_identity_and_estimator" : "model_tag_and_estimator",
+      compaction_target_ratio: COMPACTION_TARGET_RATIO,
+      estimated_input_budget: contextBudget(this.runtime.num_ctx, this.runtime.num_predict, this.runtime.context.safety_margin_tokens),
+      compactions: this.compactions
+    };
+  }
+};
+function writeFailureResult(resultPath, answer) {
+  mkdirSync(path.dirname(resultPath), { recursive: true });
+  writeFileSync(resultPath, `${JSON.stringify({ final_answer: answer, tool_calls: [], usage: {} }, null, 2)}
+`, "utf8");
+}
+
+// src/research/observations.ts
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync as existsSync2, mkdirSync as mkdirSync2, mkdtempSync, openSync, readFileSync as readFileSync2, readSync, renameSync as renameSync2, rmSync, unlinkSync as unlinkSync2, writeSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path2 from "node:path";
+function pageFooter(step, page, total, totalChars) {
+  if (total <= 1) return "";
+  const head = `
+
+[page ${page} of ${total} \u2014 ${totalChars} characters total, nothing discarded. `;
+  if (page >= total) return `${head}End of stored output.]`;
+  return `${head}For the next page send exactly: {"action":"page","step":${step},"page":${page + 1}} \u2014 that re-reads stored output and does NOT re-run the command.]`;
+}
+function encodeStrict(text) {
+  if (/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(text)) {
+    throw new ValidationError("observation contains a lone surrogate and cannot be encoded as UTF-8");
+  }
+  return Buffer.from(text, "utf8");
+}
+function writeAll(fd, data) {
+  let offset = 0;
+  while (offset < data.length) offset += writeSync(fd, data, offset, data.length - offset);
+}
+function readAt(file, position, length) {
+  const fd = openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    let read = 0;
+    while (read < length) {
+      const count = readSync(fd, buffer, read, length - read, position + read);
+      if (count === 0) break;
+      read += count;
+    }
+    return buffer.subarray(0, read);
+  } finally {
+    closeSync(fd);
+  }
+}
+var utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+var ObservationStore = class {
+  directory;
+  pageSize;
+  byStep = /* @__PURE__ */ new Map();
+  constructor(pageSize = OBSERVATION_PAGE_CHARS) {
+    if (pageSize <= 0) throw new ValidationError("observation page size must be > 0");
+    this.directory = mkdtempSync(path2.join(path2.resolve(tmpdir()), "freellama-observations-"));
+    this.pageSize = pageSize;
+  }
+  close() {
+    this.byStep.clear();
+    rmSync(this.directory, { recursive: true, force: true });
+  }
+  put(step, text, metadata = {}) {
+    if (step < 1) throw new ValidationError("observation step must be positive");
+    const file = path2.join(this.directory, `${step}.utf8`);
+    const indexPath = path2.join(this.directory, `${step}.index`);
+    let start = 0;
+    let offset = 0;
+    let pages = 0;
+    let characters = 0;
+    const output = openSync(file, "w");
+    const index = openSync(indexPath, "w");
+    try {
+      while (start < text.length) {
+        let end = cpAdvance(text, start, this.pageSize);
+        if (end < text.length) {
+          const newline = text.lastIndexOf("\n", end - 1);
+          if (newline >= start) end = newline + 1;
+        }
+        const slice = text.slice(start, end);
+        characters += cpLength(slice);
+        const encoded = encodeStrict(slice);
+        writeAll(output, encoded);
+        const nextOffset = offset + encoded.length;
+        const record = Buffer.alloc(16);
+        record.writeBigUInt64BE(BigInt(offset), 0);
+        record.writeBigUInt64BE(BigInt(nextOffset), 8);
+        writeAll(index, record);
+        offset = nextOffset;
+        pages += 1;
+        start = end;
+      }
+      if (!pages) {
+        writeAll(index, Buffer.alloc(16));
+        pages = 1;
+      }
+    } finally {
+      closeSync(output);
+      closeSync(index);
+    }
+    const bounded = {};
+    for (const [key, value] of Object.entries(metadata)) {
+      if (key === "action" || key === "status" || key === "source") bounded[key] = clip(String(value), 240);
+    }
+    this.byStep.set(step, { path: file, indexPath, characters, pages, metadata: bounded });
+  }
+  /** Explicit full materialization for consumers that need it; adapters use view/writeResult. */
+  get(step) {
+    const record = this.byStep.get(step);
+    return record ? utf8.decode(readFileSync2(record.path)) : null;
+  }
+  pageCount(step) {
+    const record = this.byStep.get(step);
+    if (!record) throw new Error(`no stored observation for step ${step}`);
+    return record.pages;
+  }
+  /** Return `[body, footer]` for one page of a stored observation. */
+  view(step, page = 1) {
+    const record = this.byStep.get(step);
+    if (!record) {
+      const known = [...this.byStep.keys()].sort((a, b) => a - b).join(", ") || "none yet";
+      return [`no stored output for step ${step} (known steps: ${known})`, ""];
+    }
+    const chosen = Math.max(1, Math.min(page, record.pages));
+    const entry = readAt(record.indexPath, (chosen - 1) * 16, 16);
+    const start = Number(entry.readBigUInt64BE(0));
+    const end = Number(entry.readBigUInt64BE(8));
+    const chunk = utf8.decode(readAt(record.path, start, end - start));
+    return [chunk, pageFooter(step, chosen, record.pages, record.characters)];
+  }
+  message(step, page = 1) {
+    const [body, footer] = this.view(step, page);
+    const record = this.byStep.get(step);
+    if (!record) return `Observation (step ${step}):
+${body}`;
+    const chosen = Math.max(1, Math.min(page, record.pages));
+    const ledger = { ...record.metadata, step, page: chosen, total_pages: record.pages, trust: "untrusted_tool_output" };
+    return `Observation (step ${step}):
+[evidence ledger: ${JSON.stringify(ledger)}]
+${body}${footer}`;
+  }
+  /** Decode a stored UTF-8 file in 64 KiB reads, never splitting a code point across chunks. */
+  streamStored(file, consume) {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    const fd = openSync(file, "r");
+    try {
+      const buffer = Buffer.alloc(65536);
+      for (; ; ) {
+        const count = readSync(fd, buffer, 0, buffer.length, null);
+        if (count === 0) break;
+        const chunk = decoder.decode(buffer.subarray(0, count), { stream: true });
+        if (chunk) consume(chunk);
+      }
+      const rest = decoder.decode();
+      if (rest) consume(rest);
+    } finally {
+      closeSync(fd);
+    }
+  }
+  /** Atomically write the public JSON result, restoring full call results from disk. */
+  writeResult(resultPath, result) {
+    const directory = path2.dirname(resultPath);
+    mkdirSync2(directory, { recursive: true });
+    const temporary = path2.join(directory, `.${path2.basename(resultPath)}.${randomBytes(6).toString("hex")}.tmp`);
+    let fd = null;
+    try {
+      fd = openSync(temporary, "wx", 384);
+      const out = fd;
+      const emit = (text) => writeAll(out, Buffer.from(text, "utf8"));
+      emit("{");
+      Object.entries(result).forEach(([key, value], fieldIndex) => {
+        if (fieldIndex) emit(",");
+        emit(`${JSON.stringify(key)}:`);
+        if (key !== "tool_calls") {
+          emit(JSON.stringify(value) ?? "null");
+          return;
+        }
+        emit("[");
+        value.forEach((call, callIndex) => {
+          const step = callIndex + 1;
+          if (step > 1) emit(",");
+          const metadata = {};
+          for (const [name, item] of Object.entries(call)) if (name !== "result") metadata[name] = item;
+          const encoded = JSON.stringify(metadata);
+          emit(encoded.slice(0, -1) + (Object.keys(metadata).length ? "," : "") + '"result":"');
+          const record = this.byStep.get(step);
+          if (!record) throw new Error(`no stored observation for step ${step}`);
+          this.streamStored(record.path, (chunk) => emit(JSON.stringify(chunk).slice(1, -1)));
+          emit('"}');
+        });
+        emit("]");
+      });
+      emit("}\n");
+      closeSync(fd);
+      fd = null;
+      renameSync2(temporary, resultPath);
+    } finally {
+      if (fd !== null) closeSync(fd);
+      if (existsSync2(temporary)) unlinkSync2(temporary);
+    }
+  }
+};
+
+// src/research/progress-events.ts
+var PROGRESS_ENV = "FREELLAMA_AGENT_PROGRESS";
+var PROGRESS_PREFIX = "@freellama-progress ";
+function progressEmitter(env, write = (line2) => {
+  process.stderr.write(line2);
+}) {
+  if (env[PROGRESS_ENV] !== "stderr") return void 0;
+  return (event) => {
+    try {
+      write(`${PROGRESS_PREFIX}${JSON.stringify(event)}
+`);
+    } catch {
+    }
+  };
+}
+
+// src/research/transport.ts
+import { createHash as createHash2 } from "node:crypto";
+import { readFileSync as readFileSync4 } from "node:fs";
+import { homedir } from "node:os";
+import path3 from "node:path";
+
+// src/research/transport-http.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+var RECEIPT_BODY_LIMIT = 64 * 1024;
+var HTTPError = class extends Error {
+  constructor(code, reason, body = Buffer.alloc(0)) {
+    super(`HTTP Error ${code}: ${reason}`);
+    this.code = code;
+    this.reason = reason;
+    this.body = body;
+  }
+  code;
+  reason;
+  body;
+  name = "HTTPError";
+};
+var URLError = class extends Error {
+  constructor(reason) {
+    super(`request not sent: ${reason.message}`);
+    this.reason = reason;
+  }
+  reason;
+  name = "URLError";
+};
+var RequestTimeoutError = class extends Error {
+  name = "RequestTimeoutError";
+  constructor(message = "timed out") {
+    super(message);
+  }
+};
+function requestHeaders(env = process.env) {
+  const headers = { "content-type": "application/json" };
+  const tokenFile = trimSpace(env.FREELLAMA_AUTH_TOKEN_FILE ?? "");
+  if (!tokenFile) return headers;
+  const token = trimSpace(decodeUtf8(readFileSync3(tokenFile), "FREELLAMA_AUTH_TOKEN_FILE"));
+  if (cpLength(token) < 32 || [...token].some((character) => isSpace(character))) {
+    throw new ValidationError("FREELLAMA_AUTH_TOKEN_FILE must contain one token of at least 32 bytes");
+  }
+  headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+function httpRequest(url, options) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      reject(new ValidationError(`unknown url type: ${JSON.stringify(url)}`));
+      return;
+    }
+    const client = parsed.protocol === "https:" ? https : parsed.protocol === "http:" ? http : null;
+    if (client === null) {
+      reject(new URLError(new Error(`unknown url type: ${parsed.protocol.replace(/:$/, "")}`)));
+      return;
+    }
+    const headers = { ...options.headers, connection: "close" };
+    if (options.body) headers["content-length"] = String(options.body.length);
+    let sent = false;
+    let settled = false;
+    const { signal } = options;
+    const onAbort = () => fail(signal?.reason instanceof Error ? signal.reason : new Error("request aborted"));
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      request.destroy();
+      reject(error);
+    };
+    if (signal?.aborted) {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("request aborted"));
+      return;
+    }
+    const request = client.request(parsed, { method: options.method, headers });
+    signal?.addEventListener("abort", onAbort, { once: true });
+    request.setTimeout(Math.max(options.timeoutSeconds * 1e3, 1), () => {
+      fail(sent ? new RequestTimeoutError() : new URLError(new RequestTimeoutError()));
+    });
+    request.on("finish", () => {
+      sent = true;
+    });
+    request.on("error", (error) => fail(sent ? error : new URLError(error)));
+    request.on("response", (response) => {
+      const chunks = [];
+      let size = 0;
+      const status = response.statusCode ?? 0;
+      const ok = status >= 200 && status < 300;
+      const limit = ok ? options.limit : RECEIPT_BODY_LIMIT + 1;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        signal?.removeEventListener("abort", onAbort);
+        const body = Buffer.concat(chunks);
+        request.destroy();
+        if (ok) resolve(body);
+        else reject(new HTTPError(status, response.statusMessage ?? "", body));
+      };
+      response.on("data", (chunk) => {
+        if (limit !== void 0 && size >= limit) return;
+        const piece = limit !== void 0 ? chunk.subarray(0, limit - size) : chunk;
+        chunks.push(piece);
+        size += piece.length;
+        if (limit !== void 0 && size >= limit) finish();
+      });
+      response.on("error", (error) => fail(error));
+      response.on("end", finish);
+    });
+    request.end(options.body);
+  });
+}
+function parseJsonBody(body, source) {
+  return JSON.parse(decodeUtf8(body, source));
+}
+async function requestJson(url, payload, timeoutSeconds) {
+  const body = Buffer.from(JSON.stringify(payload), "utf8");
+  const response = await httpRequest(url, { method: "POST", headers: requestHeaders(), body, timeoutSeconds });
+  return parseJsonBody(response, "chat response");
+}
+
+// src/research/transport.ts
+var MANAGED_SUFFIX = "/_freellama/v1/tasks";
+var IDENTITY_LIMIT = 1024 * 1024;
+var trimSlashes = (text) => text.replace(/\/+$/, "");
+async function readCatalogJson(url, request = httpRequest) {
+  const payload = await request(url, { method: "GET", headers: requestHeaders(), timeoutSeconds: 5, limit: IDENTITY_LIMIT + 1 });
+  if (payload.length > IDENTITY_LIMIT) throw new ValidationError("model identity catalog exceeds size limit");
+  return parseJsonBody(payload, "model identity catalog");
+}
+function catalogEntry(payload, model) {
+  const entries = isRecord(payload) ? payload.models ?? [] : [];
+  if (!Array.isArray(entries)) return null;
+  const names = /* @__PURE__ */ new Set([model]);
+  const lastSegment = model.slice(model.lastIndexOf("/") + 1);
+  if (!lastSegment.includes(":")) names.add(model + ":latest");
+  for (const item of entries) {
+    if (!isRecord(item)) continue;
+    const name = Object.hasOwn(item, "name") ? item.name : item.model;
+    if (typeof name === "object" && name !== null) return "ambiguous";
+    if (typeof name === "string" && names.has(name)) return item;
+  }
+  return null;
+}
+var DIGEST = /^(?:sha256:)?[0-9a-fA-F]{64}$/;
+var sha256 = (data) => createHash2("sha256").update(data, "utf8").digest("hex");
+async function resolveModelIdentity(endpointInput, model, systemPrompt, options = {}) {
+  const endpoint = trimSlashes(endpointInput);
+  const url = endpoint.endsWith(MANAGED_SUFFIX) ? endpoint.slice(0, -MANAGED_SUFFIX.length) + "/_freellama/v1/models" : endpoint + "/api/tags";
+  const unknown = { identity: "", verified: false, scope: "current_process_only" };
+  try {
+    const entry = catalogEntry(await (options.readJson ?? readCatalogJson)(url), model);
+    if (entry === "ambiguous") return unknown;
+    const digestValue = entry?.digest;
+    if (typeof digestValue !== "string" || !DIGEST.test(digestValue)) return unknown;
+    const digest = (digestValue.startsWith("sha256:") ? digestValue.slice("sha256:".length) : digestValue).toLowerCase();
+    const contract = { endpoint, model, digest, system_hash: sha256(systemPrompt) };
+    return {
+      identity: sha256(canonicalJson(contract)),
+      verified: true,
+      scope: "manifest_digest_and_system_prompt",
+      digest
+    };
+  } catch (error) {
+    if (isTransportError(error) || isSystemError(error) || error instanceof ValidationError || error instanceof SyntaxError || error instanceof TypeError) {
+      return unknown;
+    }
+    throw error;
+  }
+}
+async function resolvePlatformTokenRatio(serveEndpoint, model, options = {}) {
+  try {
+    const url = `${trimSlashes(serveEndpoint)}/_freellama/v1/models`;
+    const entry = catalogEntry(await (options.readJson ?? readCatalogJson)(url), model);
+    if (entry === null || entry === "ambiguous") return null;
+    const milli = entry.bytes_per_token_milli;
+    if (typeof milli !== "number" || !Number.isSafeInteger(milli) || milli <= 0) return null;
+    const samples = entry.bytes_per_token_samples;
+    return {
+      bytes_per_token_milli: milli,
+      bytes_per_token_samples: typeof samples === "number" && Number.isSafeInteger(samples) && samples > 0 ? samples : 1
+    };
+  } catch {
+    return null;
+  }
+}
+function isTransportError(error) {
+  return error instanceof HTTPError || error instanceof URLError || error instanceof RequestTimeoutError;
+}
+function retryableChatError(error) {
+  if (error instanceof HTTPError) {
+    if (error.code !== 503 || error.body.length > RECEIPT_BODY_LIMIT) return false;
+    try {
+      const body = parseJsonBody(error.body, "retry receipt");
+      if (!isRecord(body) || body.retry_safe === false || body.execution_outcome !== void 0 && body.execution_outcome !== "not_started") return false;
+      return body.retry_safe === true && body.execution_outcome === "not_started" || ["admission_timeout", "resource_admission_unavailable", "upstream_circuit_open", "model_lifecycle_busy"].includes(String(body.code));
+    } catch {
+      return false;
+    }
+  }
+  return error instanceof URLError && error.reason.code === "ECONNREFUSED";
+}
+var RECEIPT_FIELDS = /* @__PURE__ */ new Set([
+  "error",
+  "code",
+  "reason",
+  "retry_after_seconds",
+  "resource_admission",
+  "lifecycle",
+  "placement",
+  "execution",
+  "admission",
+  "route",
+  "decision",
+  "quality",
+  "feedback",
+  "execution_outcome",
+  "retry_safe",
+  "result_recoverable",
+  "job_id",
+  "last_observed_status"
+]);
+var PAYLOAD_FIELDS = /* @__PURE__ */ new Set([
+  "prompt",
+  "system",
+  "system_prompt",
+  "messages",
+  "content",
+  "input",
+  "images",
+  "tools",
+  "request",
+  "request_options",
+  "headers",
+  "authorization",
+  "token",
+  "api_key",
+  "auth_token"
+]);
+function receiptValue(value) {
+  if (isRecord(value)) {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (!PAYLOAD_FIELDS.has(key.toLowerCase())) result[key] = receiptValue(item);
+    }
+    return result;
+  }
+  if (Array.isArray(value)) return value.map(receiptValue);
+  return value;
+}
+function errorDiagnostic(error) {
+  if (error instanceof Error) return `${error.name}: ${error.message}`;
+  return String(error);
+}
+function chatErrorDetails(error) {
+  let diagnostic = errorDiagnostic(error);
+  if (!(error instanceof HTTPError)) return [diagnostic, null];
+  const details = { status: error.code };
+  try {
+    const body = error.body.subarray(0, RECEIPT_BODY_LIMIT + 1);
+    if (body.length > RECEIPT_BODY_LIMIT) return [diagnostic, details];
+    const payload = parseJsonBody(body, "refusal body");
+    if (!isRecord(payload) || typeof payload.error !== "string") return [diagnostic, details];
+    const receipt = {};
+    for (const [key, value] of Object.entries(payload)) {
+      if (RECEIPT_FIELDS.has(key)) receipt[key] = receiptValue(value);
+    }
+    details.receipt = receipt;
+    diagnostic = `HTTP ${error.code}: ${receipt.error}`;
+  } catch (failure) {
+    if (!(failure instanceof SyntaxError || failure instanceof ValidationError || failure instanceof RangeError)) throw failure;
+  }
+  return [diagnostic, details];
+}
+var PromptCacheUsage = class {
+  calls = 0;
+  reportedCalls = 0;
+  reportedTokens = 0;
+  reportedPromptTokens = 0;
+  observe(response) {
+    this.calls += 1;
+    const cached = response.prompt_eval_cached_count;
+    const prompt = response.prompt_eval_count;
+    if (Number.isInteger(cached) && Number.isInteger(prompt) && cached >= 0 && cached <= prompt) {
+      this.reportedCalls += 1;
+      this.reportedTokens += cached;
+      this.reportedPromptTokens += prompt;
+    }
+  }
+  get tokens() {
+    return this.calls > 0 && this.calls === this.reportedCalls ? this.reportedTokens : null;
+  }
+  metadata() {
+    const tokens = this.tokens;
+    return {
+      status: tokens !== null ? "reported" : this.reportedCalls ? "partially_reported" : "not_reported",
+      calls: this.calls,
+      reported_calls: this.reportedCalls,
+      reported_tokens: this.reportedCalls ? this.reportedTokens : null,
+      hit_ratio: tokens !== null && this.reportedPromptTokens ? this.reportedTokens / this.reportedPromptTokens : null
+    };
+  }
+};
+var resolvedShift;
+function contextShift(env = process.env, reset = false) {
+  if (resolvedShift !== void 0 && !reset) return resolvedShift;
+  const read = (value2) => value2 === "ollama_default" || value2 === "off" ? value2 : void 0;
+  let value = read(env.FREELLAMA_CONTEXT_SHIFT?.trim());
+  if (!value) {
+    const file = env.FREELLAMA_RUNTIME_CONFIG || path3.join(env.FREELLAMA_HOME || path3.join(homedir(), ".octocode", "freellama"), "runtime.toml");
+    try {
+      const topLevel = readFileSync4(file, "utf8").split(/^\s*\[/m)[0] ?? "";
+      value = read(/^\s*context_shift\s*=\s*"([^"]*)"/m.exec(topLevel)?.[1]);
+    } catch {
+    }
+  }
+  resolvedShift = value ?? "off";
+  return resolvedShift;
+}
+function chatRequest(endpointInput, model, messages, options, think, keepAlive, executionPreference = "auto", minPlacementEvidence = "configured") {
+  const endpoint = trimSlashes(endpointInput);
+  if (endpoint.endsWith(MANAGED_SUFFIX)) {
+    const managedOptions = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (key !== "num_ctx") managedOptions[key] = value;
+    }
+    if (!Object.hasOwn(options, "num_ctx")) throw new ValidationError("managed chat request requires num_ctx");
+    return [endpoint, {
+      task: "coding",
+      objective: "fastest",
+      model,
+      context_tokens: options.num_ctx,
+      execution_preference: executionPreference,
+      min_placement_evidence: minPlacementEvidence,
+      messages,
+      keep_alive: keepAlive,
+      request_options: { format: "json", think, options: managedOptions }
+    }];
+  }
+  return [`${endpoint}/api/chat`, {
+    model,
+    messages,
+    stream: false,
+    truncate: false,
+    ...contextShift() === "ollama_default" ? {} : { shift: false },
+    format: "json",
+    think,
+    keep_alive: keepAlive,
+    options
+  }];
+}
+function unwrapChatResponse(payload, executionReceipts) {
+  if (!isRecord(payload)) throw new TypeError("chat response must be a JSON object");
+  const { response } = payload;
+  if (!isRecord(response)) return payload;
+  const route = payload.route ?? {};
+  if (!isRecord(route)) throw new TypeError("managed chat response route must be a JSON object");
+  executionReceipts.push({
+    model: route.selected_model ?? null,
+    execution: payload.execution ?? null,
+    admission: payload.admission ?? null,
+    feedback: payload.feedback ?? null
+  });
+  return response;
+}
+
+// src/research/transport-jobs.ts
+import { STATUS_CODES } from "node:http";
+
+// src/job-progress.ts
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "expired"]);
+var SUBMIT_FALLBACK_CODES = /* @__PURE__ */ new Set(["task_job_input_too_large", "task_jobs_full", "task_jobs_input_budget"]);
+var RETENTION_FAILURE_CODES = /* @__PURE__ */ new Set(["task_job_result_too_large", "task_job_error_too_large"]);
+var FIRST_POLL_MS = 250;
+var HEARTBEAT_MS = 1e4;
+var MAX_POLL_MS = 2e3;
+var MAX_POLL_FAILURES = 5;
+var CANCEL_ATTEMPTS = 3;
+var CANCEL_BACKOFF_MS = 250;
+var CANCEL_REPORT_MS = 5e3;
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+var number = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+var gigabytes = (bytes) => `${(bytes / 1e9).toFixed(1)} GB`;
+var seconds = (ms) => ms < 1e4 ? `${(ms / 1e3).toFixed(1)} s` : `${Math.round(ms / 1e3)} s`;
+function modelNames(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (typeof item === "string") return [item];
+    const named = object(item)?.model ?? object(item)?.name;
+    return typeof named === "string" ? [named] : [];
+  });
+}
+function evictedSuffix(detail) {
+  const evicted = modelNames(detail?.evicted ?? detail?.evicted_idle_models);
+  return evicted.length > 0 ? `, evicted ${evicted.join(", ")}` : "";
+}
+function holdersSuffix(detail) {
+  const holders = Array.isArray(detail?.memory_holders) ? detail.memory_holders : [];
+  const named = holders.map((holder) => holder).filter((holder) => typeof holder.name === "string" && typeof holder.resident_bytes === "number").slice(0, 3).map((holder) => {
+    const count = typeof holder.processes === "number" && holder.processes > 1 ? ` \xD7${holder.processes}` : "";
+    return `${holder.name}${count} ${gigabytes(holder.resident_bytes)}`;
+  });
+  return named.length > 0 ? `; largest memory users: ${named.join(", ")}` : "";
+}
+function jobProgressMessage(job) {
+  const status = typeof job.status === "string" ? job.status : "queued";
+  const reason = typeof job.reason === "string" ? job.reason : "";
+  const detail = object(job.detail);
+  const model = typeof job.selected_model === "string" && job.selected_model ? job.selected_model : void 0;
+  switch (status) {
+    case "queued":
+      return "queued";
+    case "waiting_for_admission":
+      return reason === "resources_reserved_waiting_for_backend_capacity" ? "memory reserved; waiting for backend capacity" : "waiting for backend capacity";
+    case "waiting_for_resources": {
+      const need = number(detail?.required_available_bytes);
+      const available = number(detail?.effective_available_bytes);
+      if (need === void 0 && available === void 0) {
+        return (reason === "checking_host_resources" ? "checking host memory" : "waiting for memory") + evictedSuffix(detail);
+      }
+      const sizes = [need !== void 0 ? `need ${gigabytes(need)}` : void 0, available !== void 0 ? `${gigabytes(available)} available` : void 0].filter(Boolean).join(", ");
+      const pressure = Array.isArray(detail?.pressure_reasons) ? detail.pressure_reasons.map((item) => typeof item === "string" ? item : JSON.stringify(item)) : [];
+      return `waiting for memory: ${sizes}${pressure.length > 0 ? ` (host: ${pressure.join(", ")})` : ""}${holdersSuffix(detail)}${evictedSuffix(detail)}`;
+    }
+    case "waiting_for_runner":
+      return "waiting for runner";
+    case "loading": {
+      const expected = number(detail?.expected_load_ms);
+      return `loading ${model ?? "model"}${expected !== void 0 ? ` (~${seconds(expected)})` : ""}${evictedSuffix(detail)}`;
+    }
+    case "running":
+      return model ? `running ${model}` : "running";
+    default:
+      return status.replace(/_/g, " ");
+  }
+}
+function errorBody(error) {
+  try {
+    return object(JSON.parse(error instanceof Error ? error.message : String(error)));
+  } catch {
+    return void 0;
+  }
+}
+function describeNapiError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const missing = /does not exist or has expired|\bHTTP 404\b|^\s*(?:404\b|Not Found\s*$)/i.test(message);
+  return { body: errorBody(error), ...missing ? { status: 404 } : {} };
+}
+function unconfirmedSubmission(error, body) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (body && (typeof body.code === "string" || "execution_outcome" in body || "retry_safe" in body)) {
+    return error instanceof Error ? error : new Error(message);
+  }
+  return new Error(JSON.stringify({
+    ...body,
+    error: typeof body?.error === "string" ? body.error : message,
+    execution_outcome: "unknown",
+    retry_safe: false
+  }));
+}
+function submissionRefused({ body }) {
+  const code = body?.code;
+  return typeof code === "string" && SUBMIT_FALLBACK_CODES.has(code);
+}
+var defaultWait = (ms, signal) => new Promise((resolve) => {
+  if (signal?.aborted) return resolve();
+  const done = () => {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", done);
+    resolve();
+  };
+  const timer = setTimeout(done, ms);
+  signal?.addEventListener("abort", done, { once: true });
+});
+async function runWithJobProgress(calls, report, options = {}) {
+  const { signal, wait = defaultWait, describe = describeNapiError, onJob } = options;
+  const aborted = (id2, cancellation2) => options.aborted?.(id2, cancellation2) ?? new Error(id2 ? cancellation2 === "unknown" ? `run_task was cancelled by the client; cancellation acknowledgement is unknown for deferred job ${id2}, which may still be running. Upstream stop is not confirmed.` : `run_task was cancelled by the client; cancellation was requested for deferred job ${id2}${cancellation2 === "acknowledged" ? " and acknowledged by serve" : ""}. Upstream stop is not confirmed.` : "run_task was cancelled by the client before a job handle was received; execution outcome is unknown. The task was not replayed.");
+  if (signal?.aborted) throw options.aborted?.() ?? new Error("run_task was cancelled by the client before submission; no task was submitted.");
+  let raw;
+  try {
+    raw = await calls.submit();
+  } catch (error) {
+    if (signal?.aborted) throw aborted();
+    const described = describe(error);
+    if (submissionRefused(described)) return calls.sync(described.body);
+    throw options.unconfirmed?.(error, described.body) ?? unconfirmedSubmission(error, described.body);
+  }
+  let submitted;
+  try {
+    submitted = object(JSON.parse(raw));
+  } catch {
+    return raw;
+  }
+  let job = object(submitted?.job);
+  const id = typeof job?.id === "string" ? job.id : void 0;
+  if (submitted?.deferred !== true || !job || !id) return raw;
+  onJob?.(id, true);
+  let open = true;
+  const settled = () => {
+    if (open) onJob?.(id, false);
+    open = false;
+  };
+  let cancellation;
+  const requestCancellation = async () => {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        const reply = object(JSON.parse(await calls.cancel(id)));
+        const status = object(reply?.job)?.status ?? reply?.status;
+        if (!TERMINAL.has(String(status))) return "requested";
+        settled();
+        return "acknowledged";
+      } catch (error) {
+        if (describe(error).status === 404) {
+          settled();
+          return "unknown";
+        }
+        if (attempt >= CANCEL_ATTEMPTS) return "unknown";
+        await wait(CANCEL_BACKOFF_MS * 2 ** (attempt - 1));
+      }
+    }
+  };
+  const cancel = () => {
+    cancellation ??= requestCancellation();
+  };
+  const cancellationState = async () => {
+    if (!cancellation) return void 0;
+    let timer;
+    const capped = new Promise((resolve) => {
+      timer = setTimeout(() => resolve("unknown"), CANCEL_REPORT_MS);
+    });
+    try {
+      return await Promise.race([cancellation, capped]);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  signal?.addEventListener("abort", cancel, { once: true });
+  try {
+    let lastMessage = "";
+    let lastPhase = "";
+    let lastReportAt = Date.now();
+    let phaseStartedAt = lastReportAt;
+    let delay = FIRST_POLL_MS;
+    let failures = 0;
+    for (; ; ) {
+      if (signal?.aborted) {
+        cancel();
+        throw aborted(id, await cancellationState());
+      }
+      const now = Date.now();
+      const phase = `${String(job.status)}|${String(job.reason)}`;
+      if (phase !== lastPhase) {
+        lastPhase = phase;
+        phaseStartedAt = now;
+        delay = FIRST_POLL_MS;
+      }
+      const message = jobProgressMessage(job);
+      if (message !== lastMessage) {
+        report(message);
+        lastMessage = message;
+        lastReportAt = now;
+      } else if (now - lastReportAt >= HEARTBEAT_MS && !TERMINAL.has(String(job.status))) {
+        report(`${message} (${seconds(now - phaseStartedAt)})`);
+        lastReportAt = now;
+      }
+      if (TERMINAL.has(String(job.status))) break;
+      await wait(delay, signal);
+      if (signal?.aborted) {
+        cancel();
+        throw aborted(id, await cancellationState());
+      }
+      delay = Math.min(MAX_POLL_MS, Math.round(delay * 1.5));
+      try {
+        const polled = object(object(JSON.parse(await calls.get(id)))?.job);
+        if (polled) job = polled;
+        failures = 0;
+      } catch (error) {
+        if (describe(error).status === 404) {
+          settled();
+          const failure2 = {
+            code: "task_job_unavailable",
+            error: `Deferred job ${id} is no longer available; its execution outcome is unknown. The task was not run again. Its result cannot be recovered from the missing job record; verify the original execution before submitting new work.`,
+            job_id: id,
+            last_observed_status: job.status,
+            execution_outcome: "unknown",
+            result_recoverable: false,
+            retry_safe: false
+          };
+          throw options.failure?.(failure2, 404) ?? new Error(JSON.stringify(failure2));
+        }
+        failures += 1;
+        if (failures >= MAX_POLL_FAILURES) {
+          cancel();
+          throw error;
+        }
+      }
+    }
+    settled();
+    if (job.status === "completed") return JSON.stringify(job.result ?? {});
+    const failure = { ...object(job.error) ?? { error: `deferred job ${id} ended ${String(job.status)}` } };
+    if (typeof failure.code === "string" && RETENTION_FAILURE_CODES.has(failure.code)) {
+      const lost = failure.code === "task_job_result_too_large" ? "result" : "error";
+      failure.error = `${String(failure.error)} Deferred job ${id} was not run again. Its original ${lost} was not retained and cannot be recovered from this job; resubmission would execute new work.`;
+      failure.job_id = id;
+      failure.result_recoverable = false;
+      failure.retry_safe = false;
+    }
+    const status = typeof failure.status === "number" ? failure.status : void 0;
+    delete failure.id;
+    delete failure.ok;
+    if (status !== void 0) delete failure.status;
+    throw options.failure?.(failure, status) ?? new Error(JSON.stringify(failure));
+  } finally {
+    signal?.removeEventListener("abort", cancel);
+  }
+}
+
+// src/research/transport-jobs.ts
+var TASKS_SUFFIX = "/_freellama/v1/tasks";
+function describeHttpError(error) {
+  if (!(error instanceof HTTPError)) return {};
+  try {
+    const body = parseJsonBody(error.body.subarray(0, RECEIPT_BODY_LIMIT), "error body");
+    return { status: error.code, ...isRecord(body) ? { body } : {} };
+  } catch {
+    return { status: error.code };
+  }
+}
+function syncError(body, status) {
+  const code = status ?? 500;
+  return new HTTPError(code, STATUS_CODES[code] ?? "", Buffer.from(JSON.stringify(body), "utf8"));
+}
+async function requestJsonAsJob(url, payload, timeoutSeconds, options) {
+  const request = options.request ?? httpRequest;
+  const headers = requestHeaders();
+  const call = async (method, target, body, signal) => {
+    const sent = body === void 0 ? void 0 : Buffer.from(JSON.stringify(body), "utf8");
+    const response = await request(target, { method, headers, body: sent, timeoutSeconds, signal });
+    return decodeUtf8(response, "managed task response");
+  };
+  const sync = () => call("POST", url, payload);
+  if (!url.endsWith(TASKS_SUFFIX)) return parseJsonBody(Buffer.from(await sync(), "utf8"), "chat response");
+  const jobs = `${url.slice(0, -TASKS_SUFFIX.length)}/_freellama/v1/jobs`;
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(), Math.max(timeoutSeconds * 1e3, 1));
+  try {
+    const raw = await runWithJobProgress({
+      submit: () => call("POST", url, { ...payload, defer: true }),
+      get: (id) => call("GET", `${jobs}/${encodeURIComponent(id)}`, void 0, deadline.signal),
+      cancel: (id) => call("POST", `${jobs}/${encodeURIComponent(id)}/cancel`, null),
+      sync: async () => {
+        throw syncError({
+          code: "cancellable_task_unavailable",
+          error: "Serve refused job submission before execution; cancellable research requires available job capacity and a supported request size.",
+          execution_outcome: "not_started",
+          retry_safe: true
+        }, 409);
+      }
+    }, options.report, {
+      signal: deadline.signal,
+      wait: options.wait,
+      describe: describeHttpError,
+      failure: syncError,
+      aborted: () => new RequestTimeoutError(),
+      // Keep transport types, but do not let an arbitrary 503 erase an uncertain submission.
+      unconfirmed: (error, body) => error instanceof HTTPError && !retryableChatError(error) ? syncError({
+        ...body,
+        error: typeof body?.error === "string" ? body.error : error.message,
+        execution_outcome: body?.execution_outcome ?? "unknown",
+        retry_safe: false
+      }, error.code) : error,
+      onJob: options.onJob
+    });
+    return parseJsonBody(Buffer.from(raw, "utf8"), "chat response");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/research/workspace-path.ts
+import { lstatSync, readlinkSync, statSync } from "node:fs";
+import path4 from "node:path";
+var SymlinkLoopError = class extends ValidationError {
+  name = "SymlinkLoopError";
+};
+var hasNul = (text) => text.includes("\0");
+function cleanPath(text) {
+  const parts = text.split("/").filter((part) => part !== "" && part !== ".");
+  if (text.startsWith("/")) return `/${parts.join("/")}`;
+  return parts.join("/") || ".";
+}
+function joinPath(base, child) {
+  return cleanPath(child.startsWith("/") ? child : `${base}/${child}`);
+}
+function escapesRoot(resolved, root) {
+  const a = cleanPath(resolved);
+  const b = cleanPath(root);
+  return a !== b && !a.startsWith(b === "/" ? "/" : `${b}/`);
+}
+var IGNORED = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR", "EBADF", "ELOOP"]);
+function probe(read, fallback) {
+  try {
+    return read();
+  } catch (error) {
+    if (IGNORED.has(error.code ?? "")) return fallback;
+    throw error;
+  }
+}
+function exists(target) {
+  return !hasNul(target) && probe(() => (statSync(target), true), false);
+}
+function isSymlink(target) {
+  return !hasNul(target) && probe(() => lstatSync(target).isSymbolicLink(), false);
+}
+function lexists(target) {
+  if (hasNul(target)) return false;
+  try {
+    lstatSync(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isDir(target) {
+  if (hasNul(target)) return false;
+  try {
+    return statSync(target).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function readlink(target) {
+  if (hasNul(target)) throw new ValidationError("embedded null byte");
+  try {
+    return readlinkSync(target);
+  } catch {
+    return null;
+  }
+}
+function resolvePath(target, cwd = process.cwd()) {
+  const seen = /* @__PURE__ */ new Map();
+  const walk = (start, rest) => {
+    let current = rest.startsWith("/") ? "" : start;
+    for (const name of rest.split("/")) {
+      if (!name || name === ".") continue;
+      if (name === "..") {
+        current = current.slice(0, Math.max(current.lastIndexOf("/"), 0));
+        continue;
+      }
+      const next = `${current}/${name}`;
+      if (seen.has(next)) {
+        const cached = seen.get(next);
+        if (cached === null || cached === void 0) throw new SymlinkLoopError(`symlink loop at ${JSON.stringify(next)}`);
+        current = cached;
+        continue;
+      }
+      const link = readlink(next);
+      if (link === null) {
+        current = next;
+      } else {
+        seen.set(next, null);
+        current = walk(current, link);
+        seen.set(next, current);
+      }
+    }
+    return current;
+  };
+  const text = cleanPath(target);
+  return path4.posix.normalize(walk(text.startsWith("/") ? "" : cwd, text) || "/");
+}
+
+// src/research/grounding.ts
+import { existsSync as existsSync3 } from "node:fs";
+import path5 from "node:path";
+var PATH_TOKEN = /(?<![\w@/.-])(?:\.\/)?[\w@-][\w@.-]*(?:\/[\w@.-]+)+\.[A-Za-z][A-Za-z0-9]{0,5}(?=$|[\s:`'"),.;\]])/g;
+function clean(token) {
+  return token.replace(/^\.\//, "").replace(/[.,;]+$/, "");
+}
+function pathsIn(text) {
+  return [...new Set([...text.matchAll(PATH_TOKEN)].map((match) => clean(match[0])))];
+}
+function missingPaths(answer, workspace) {
+  return pathsIn(answer).filter((candidate) => !existsSync3(path5.join(workspace, candidate)));
+}
+function evidencePaths(observations, workspace, limit = 10) {
+  const found = [];
+  for (const text of observations) {
+    for (const candidate of pathsIn(text)) {
+      if (!found.includes(candidate) && existsSync3(path5.join(workspace, candidate))) found.push(candidate);
+      if (found.length >= limit) return found;
+    }
+  }
+  return found;
+}
+function groundingRepairNotice(missing, evidence) {
+  return `These paths in your answer do not exist in the workspace: ${missing.join(", ")}. ` + (evidence.length > 0 ? `Paths your own commands returned: ${evidence.join(", ")}. ` : "") + "Return a finish action again that cites only paths that exist; if the evidence does not establish the answer, say so.";
+}
+function groundingNote(missing) {
+  return `
+[freellama: cited path(s) not found in the workspace: ${missing.join(", ")}; treat this answer as unverified]`;
+}
+function toolErrorHint(message) {
+  if (/rg: unrecognized flag --(?:exclude-dir|include)/.test(message)) {
+    return "\nHint: rg excludes directories with --glob '!node_modules' and filters types with -t ts; or use grep -rn PATTERN . --exclude-dir=node_modules.";
+  }
+  return "";
+}
+function sourceRepairNotice(evidence) {
+  return `Your answer names no source file. Keep the answer and end it with "Source: path:line" copied from your results, for example one of: ${evidence.slice(0, 6).join(", ")}.`;
+}
+
+// src/research/agent-loop.ts
+var isValidationError = (error) => error instanceof ValidationError;
+function requireEnv(env, name) {
+  const value = env[name];
+  if (value === void 0) throw new Error(`${name} is not set`);
+  return value;
+}
+var readText = (file) => normalizeNewlines(decodeUtf8(readFileSync5(file), file));
+var pathOf = (value) => value === "" ? "." : value;
+var numberOr = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : typeof value === "boolean" ? Number(value) : fallback;
+var echo = (action) => canonicalJson(action, { sortKeys: false, ensureAscii: false });
+async function runAdapter(spec, hooks = {}) {
+  const env = hooks.env ?? process.env;
+  let resultPath = null;
+  try {
+    const model = env.FREELLAMA_TARGET_MODEL || requireEnv(env, "FREELLAMA_BENCH_MODEL");
+    const workspace = resolvePath(pathOf(requireEnv(env, "FREELLAMA_BENCH_WORKSPACE")));
+    const prompt = readText(pathOf(requireEnv(env, "FREELLAMA_BENCH_PROMPT")));
+    resultPath = pathOf(requireEnv(env, "FREELLAMA_AGENT_RESULT"));
+    return await runLoop(spec, hooks, env, { model, workspace, prompt, resultPath });
+  } catch (error) {
+    const answer = `unexpected adapter error: ${errorDiagnostic(error)}`;
+    process.stderr.write(`${error instanceof Error ? error.stack ?? answer : answer}
+`);
+    if (resultPath !== null) {
+      try {
+        writeFailureResult(resultPath, answer);
+      } catch {
+      }
+    }
+    return 1;
+  }
+}
+async function runLoop(spec, hooks, env, inputs) {
+  const { model, workspace, prompt, resultPath } = inputs;
+  const print = hooks.print ?? ((line2) => process.stdout.write(`${line2}
+`));
+  const progress = hooks.progress ?? progressEmitter(env);
+  const endpoint = (env.FREELLAMA_OLLAMA_ENDPOINT ?? "http://127.0.0.1:11434").replace(/\/+$/, "");
+  const managedEndpoint = (env.FREELLAMA_AGENT_MANAGED_ENDPOINT ?? "").replace(/\/+$/, "");
+  let phaseAt = { maxTurns: 0 };
+  const sendJson = hooks.requestJson ?? (managedEndpoint ? (url, payload, timeoutSeconds) => requestJsonAsJob(url, payload, timeoutSeconds, {
+    report: (message) => progress?.({ event: "job_phase", ...phaseAt, message }),
+    onJob: (id, open) => progress?.({ event: open ? "job_open" : "job_closed", id }),
+    request: hooks.httpRequest
+  }) : requestJson);
+  const executionPreference = env.FREELLAMA_AGENT_EXECUTION_PREFERENCE ?? "auto";
+  const minPlacementEvidence = env.FREELLAMA_AGENT_MIN_PLACEMENT_EVIDENCE ?? "configured";
+  let runtime;
+  try {
+    runtime = AgentRuntimeConfig.fromEnv({ defaultToolTimeoutSeconds: spec.defaultToolTimeoutSeconds, env });
+  } catch (error) {
+    if (!isValidationError(error)) throw error;
+    const answer2 = `invalid research adapter configuration: ${error.message}`;
+    writeFailureResult(resultPath, answer2);
+    print(answer2);
+    return 1;
+  }
+  let messages = [
+    { role: "system", content: spec.systemPrompt(workspace) },
+    { role: "user", content: withBriefing(prompt, spec, workspace) }
+  ];
+  const calls = [];
+  const usage = { input_tokens: 0, output_tokens: 0, cache_read_tokens: null, cache_write_tokens: null };
+  const cacheUsage = new PromptCacheUsage();
+  const metrics = { load_ms: 0, prompt_eval_ms: 0, eval_ms: 0 };
+  const executionReceipts = [];
+  let answer = "";
+  let failure = null;
+  let transportError = null;
+  const readCatalog = (url) => readCatalogJson(url, hooks.httpRequest);
+  const platformRatio = managedEndpoint ? await (hooks.resolvePlatformTokenRatio ?? resolvePlatformTokenRatio)(managedEndpoint, model, { readJson: readCatalog }) : null;
+  const calibrationDir = trimSpace(env.FREELLAMA_AGENT_TOKEN_CALIBRATION_DIR ?? "");
+  const calibrationModelIdentity = calibrationDir ? await (hooks.resolveModelIdentity ?? resolveModelIdentity)(
+    managedEndpoint || endpoint,
+    model,
+    messages[0].content,
+    { readJson: readCatalog }
+  ) : { verified: false, scope: "persistence_disabled", identity: "" };
+  const contextManager = new AgentContextManager(runtime, {
+    model,
+    calibrationIdentity: calibrationModelIdentity.identity,
+    calibrationDir: calibrationDir && calibrationModelIdentity.verified ? calibrationDir : null,
+    platformRatio
+  });
+  try {
+    messages = contextManager.fit(messages);
+  } catch (error) {
+    if (!isValidationError(error)) throw error;
+    answer = `research task does not fit the configured context safely: ${error.message}`;
+    writeFailureResult(resultPath, answer);
+    print(answer);
+    return 1;
+  }
+  const chatOptions = {
+    temperature: runtime.temperature,
+    seed: runtime.seed,
+    num_ctx: runtime.num_ctx,
+    num_predict: runtime.num_predict
+  };
+  const callModel = async () => {
+    let lastError = null;
+    let response = null;
+    for (let attempt = 0; attempt < runtime.retry_attempts; attempt += 1) {
+      try {
+        const transportEndpoint = managedEndpoint ? `${managedEndpoint}/_freellama/v1/tasks` : endpoint;
+        const [url, payload] = chatRequest(
+          transportEndpoint,
+          model,
+          messages,
+          chatOptions,
+          runtime.think,
+          runtime.keep_alive,
+          executionPreference,
+          minPlacementEvidence
+        );
+        const recorded = executionReceipts.length;
+        response = unwrapChatResponse(await sendJson(url, payload, runtime.request_timeout_seconds), executionReceipts);
+        if (managedEndpoint && executionReceipts.length === recorded) {
+          executionReceipts.push({ model: null, execution: null, reason: "managed_execution_receipt_missing" });
+        }
+        break;
+      } catch (error) {
+        if (!isTransportError(error) || !retryableChatError(error)) throw error;
+        lastError = error;
+        if (attempt + 1 < runtime.retry_attempts) {
+          progress?.({ event: "retry", attempt: attempt + 2, attempts: runtime.retry_attempts });
+          await sleep(runtime.retry_backoff_seconds * 1e3);
+        }
+      }
+    }
+    if (response === null) throw lastError;
+    usage.input_tokens = usage.input_tokens + Math.trunc(numberOr(response.prompt_eval_count, 0));
+    cacheUsage.observe(response);
+    usage.cache_read_tokens = cacheUsage.tokens;
+    usage.output_tokens = usage.output_tokens + Math.trunc(numberOr(response.eval_count, 0));
+    metrics.load_ms += numberOr(response.load_duration, 0) / 1e6;
+    metrics.prompt_eval_ms += numberOr(response.prompt_eval_duration, 0) / 1e6;
+    metrics.eval_ms += numberOr(response.eval_duration, 0) / 1e6;
+    contextManager.observe(messages, response.prompt_eval_count);
+    return response;
+  };
+  const refit = () => {
+    try {
+      messages = contextManager.fit(messages);
+      return true;
+    } catch (error) {
+      if (!isValidationError(error)) throw error;
+      failure = `research context cannot be fitted safely: ${error.message}`;
+      return false;
+    }
+  };
+  const content = (response) => {
+    const message = response.message ?? {};
+    if (!isRecord(message)) throw new TypeError("chat response message must be a JSON object");
+    const text = message.content ?? "";
+    return typeof text === "string" ? text : JSON.stringify(text);
+  };
+  const seenCalls = /* @__PURE__ */ new Map();
+  const pageSize = runtime.context.observation_page_chars;
+  const observations = hooks.observationStore ? hooks.observationStore(pageSize) : new ObservationStore(pageSize);
+  let session;
+  try {
+    try {
+      session = spec.open ? await spec.open(workspace) : void 0;
+    } catch (error) {
+      if (!isValidationError(error)) throw error;
+      answer = `research adapter could not start: ${error.message}`;
+      writeFailureResult(resultPath, answer);
+      print(answer);
+      return 1;
+    }
+    const root = session?.workspace ?? workspace;
+    let parseFailures = 0;
+    let exhausted = true;
+    let repeats = 0;
+    let groundingRepaired = false;
+    let sourceRepaired = false;
+    const seenOutputs = [];
+    for (let turn = 0; turn < runtime.max_turns; turn += 1) {
+      const at = { turn: turn + 1, maxTurns: runtime.max_turns };
+      phaseAt = at;
+      progress?.({ event: "model", ...at });
+      let response;
+      try {
+        response = await callModel();
+      } catch (error) {
+        if (!isTransportError(error)) throw error;
+        let diagnostic;
+        [diagnostic, transportError] = chatErrorDetails(error);
+        failure = `agent response failed: ${diagnostic}`;
+        exhausted = false;
+        break;
+      }
+      const raw = content(response);
+      let action;
+      try {
+        action = spec.parseAction(raw);
+      } catch (error) {
+        if (!isValidationError(error)) throw error;
+        parseFailures += 1;
+        if (parseFailures > runtime.max_parse_repairs) {
+          failure = `agent gave ${parseFailures} unparseable replies: ${errorDiagnostic(error)}`;
+          exhausted = false;
+          break;
+        }
+        progress?.({ event: "repair", ...at });
+        messages.push({ role: "assistant", content: cpSlice(raw, 0, runtime.parse_repair_echo_chars) });
+        messages.push({ role: "user", content: PARSE_REPAIR_NOTICE });
+        if (!refit()) {
+          exhausted = false;
+          break;
+        }
+        continue;
+      }
+      parseFailures = 0;
+      if (action.action === "page") {
+        const wantStep = Math.trunc(numberOr(action.step, 0));
+        const wantPage = Math.trunc(numberOr(action.page, 1));
+        progress?.({ event: "action", ...at, action });
+        messages.push({ role: "assistant", content: echo(action) });
+        messages.push({ role: "user", content: observations.message(wantStep, wantPage) });
+        if (!refit()) {
+          exhausted = false;
+          break;
+        }
+        continue;
+      }
+      if (action.action === "finish") {
+        const proposed = trimSpace(String(action.answer ?? ""));
+        const missing = missingPaths(proposed, root);
+        if (missing.length > 0 && !groundingRepaired) {
+          groundingRepaired = true;
+          progress?.({ event: "repair", ...at });
+          messages.push({ role: "assistant", content: echo(action) });
+          messages.push({ role: "user", content: groundingRepairNotice(missing, evidencePaths(seenOutputs, root)) });
+          if (!refit()) {
+            answer = proposed + groundingNote(missing);
+            exhausted = false;
+            break;
+          }
+          continue;
+        }
+        const evidence = spec.requireSource !== false && missing.length === 0 && !sourceRepaired && pathsIn(proposed).length === 0 ? evidencePaths(seenOutputs, root) : [];
+        if (evidence.length > 0) {
+          sourceRepaired = true;
+          progress?.({ event: "repair", ...at });
+          messages.push({ role: "assistant", content: echo(action) });
+          messages.push({ role: "user", content: sourceRepairNotice(evidence) });
+          if (!refit()) {
+            answer = proposed;
+            exhausted = false;
+            break;
+          }
+          continue;
+        }
+        progress?.({ event: "finish", ...at });
+        answer = missing.length > 0 ? proposed + groundingNote(missing) : proposed;
+        exhausted = false;
+        break;
+      }
+      const started = performance2.now();
+      const call = session.toolCall(action, root, runtime);
+      const signature = callSignature(call.signature);
+      let observation;
+      let status;
+      let exitCode;
+      if (seenCalls.has(signature)) {
+        progress?.({ event: "action", ...at, action, repeat: true });
+        observation = REPEAT_NOTICE;
+        status = "repeat";
+        repeats += 1;
+      } else {
+        progress?.({ event: "action", ...at, action });
+        try {
+          observation = hooks.runTool ? await hooks.runTool(call.record.arguments) : await call.run();
+          status = "ok";
+        } catch (error) {
+          if (!isToolError(error)) throw error;
+          status = error instanceof ToolExitError ? error.status : "error";
+          exitCode = error instanceof ToolExitError ? error.exitCode : void 0;
+          observation = `${status === "empty" ? "tool search" : "tool error"}: ${error.message}${toolErrorHint(error.message)}`;
+        }
+        seenCalls.set(signature, calls.length + 1);
+      }
+      calls.push({
+        ...call.record,
+        status,
+        ...exitCode === void 0 ? {} : { exit_code: exitCode },
+        duration_ms: Math.round((performance2.now() - started) * 1e3) / 1e3
+      });
+      messages.push({ role: "assistant", content: echo(action) });
+      const remaining = runtime.max_turns - calls.length;
+      const step = calls.length;
+      observations.put(step, observation, call.ledger(status));
+      seenOutputs.push(observation);
+      messages.push({ role: "user", content: observations.message(step) + spec.remaining(remaining) });
+      if (!refit()) {
+        exhausted = false;
+        break;
+      }
+      if (repeats >= 2) break;
+    }
+    if (exhausted) {
+      progress?.({ event: "finalize", maxTurns: runtime.max_turns });
+      phaseAt = { maxTurns: runtime.max_turns };
+      messages.push({ role: "user", content: spec.exhausted });
+      if (refit()) {
+        try {
+          const response = await callModel();
+          const finalAction = spec.parseAction(content(response));
+          if (finalAction.action !== "finish") throw new ValidationError("forced final response was not finish");
+          answer = trimSpace(String(finalAction.answer ?? ""));
+          const missing = missingPaths(answer, root);
+          if (missing.length > 0) answer += groundingNote(missing);
+        } catch (error) {
+          if (!isTransportError(error) && !isValidationError(error)) throw error;
+          let diagnostic;
+          [diagnostic, transportError] = chatErrorDetails(error);
+          failure = `agent exceeded ${runtime.max_turns} turns and finalization failed: ${diagnostic}`;
+        }
+      }
+    }
+    if (!answer) answer = failure ?? "agent stopped without a final answer";
+    const report = spec.report ? await spec.report(session) : {};
+    const result = {
+      ...report,
+      final_answer: answer,
+      tool_calls: calls,
+      usage,
+      provider_metrics: {
+        load_ms: metrics.load_ms,
+        prompt_eval_ms: metrics.prompt_eval_ms,
+        eval_ms: metrics.eval_ms
+      },
+      model_metadata: {
+        ...spec.adapterMetadata(session),
+        temperature: chatOptions.temperature,
+        seed: chatOptions.seed,
+        num_ctx: chatOptions.num_ctx,
+        num_predict: chatOptions.num_predict,
+        max_turns: runtime.max_turns,
+        runtime_config: runtime.metadata(),
+        context_management: contextManager.metadata(),
+        context_compactions: contextManager.compactions,
+        transport: managedEndpoint ? "managed" : "direct_ollama",
+        execution_preference: executionPreference,
+        min_placement_evidence: minPlacementEvidence,
+        execution_receipts: executionReceipts,
+        ...transportError ? { transport_error: transportError } : {},
+        cache_token_metrics: cacheUsage.metadata(),
+        calibration_model_identity: calibrationModelIdentity
+      }
+    };
+    observations.writeResult(resultPath, result);
+    print(answer);
+    return failure ? 1 : 0;
+  } finally {
+    session?.close?.();
+    observations.close();
+  }
+}
+function withBriefing(prompt, spec, workspace) {
+  try {
+    const briefing2 = spec.briefing?.(workspace);
+    return briefing2 ? `${prompt}
+
+${briefing2}` : prompt;
+  } catch {
+    return prompt;
+  }
+}
+
+// src/research/coder-actions.ts
+import { spawn as spawn2, spawnSync as spawnSync2 } from "node:child_process";
+import { existsSync as existsSync6, lstatSync as lstatSync2, mkdirSync as mkdirSync4, readFileSync as readFileSync7, realpathSync as realpathSync3, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import path8 from "node:path";
+
+// src/research/sandbox.ts
+import { accessSync, constants as fsConstants, existsSync as existsSync4, mkdirSync as mkdirSync3, mkdtempSync as mkdtempSync2, realpathSync, rmSync as rmSync2, symlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import path6 from "node:path";
+
+// src/research/proc.ts
+import { spawn, spawnSync } from "node:child_process";
+import { constants } from "node:os";
+function decodeText(bytes, source = "command output") {
+  return normalizeNewlines(decodeUtf8(bytes, source));
+}
+function runProcess(argv, options) {
+  const timeoutMs = Math.max(options.timeoutSeconds * 1e3, 0);
+  return new Promise((resolve, reject) => {
+    const child = spawn(argv[0], argv.slice(1), {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdout = [];
+    const stderr = [];
+    let settled = false;
+    const finish = (action) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      action();
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      const fail = () => finish(() => reject(new ToolTimeoutError(
+        `command ${JSON.stringify(argv.at(-1))} timed out after ${options.timeoutSeconds} seconds`
+      )));
+      if (child.exitCode !== null || child.signalCode !== null) fail();
+      else child.once("exit", fail);
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.once("error", (error) => finish(() => reject(error)));
+    child.once("close", (code, signal) => finish(() => {
+      try {
+        resolve({
+          stdout: decodeText(Buffer.concat(stdout)),
+          stderr: decodeText(Buffer.concat(stderr)),
+          returncode: code ?? -(signal ? constants.signals[signal] ?? 1 : 1)
+        });
+      } catch (error) {
+        reject(error);
+      }
+    }));
+  });
+}
+function probe2(argv, env) {
+  const result = spawnSync(argv[0], argv.slice(1), { env, stdio: ["ignore", "pipe", "pipe"], timeout: 1e4, killSignal: "SIGKILL" });
+  return !result.error && result.status === 0;
+}
+
+// src/research/glob.ts
+import { readdirSync as readdirSync2 } from "node:fs";
+var GlobPatternError = class extends ValidationError {
+  name = "GlobPatternError";
+};
+var hasGlobMagic = (text) => /[*?[]/.test(text);
+var isHidden = (name) => name.startsWith(".");
+function globPaths(pattern) {
+  const split = pattern.lastIndexOf("/") + 1;
+  const basename = pattern.slice(split);
+  let dirname = pattern.slice(0, split);
+  if (/[^/]/.test(dirname)) dirname = dirname.replace(/\/+$/, "");
+  if (!hasGlobMagic(pattern)) return (basename ? lexists(pattern) : isDir(dirname)) ? [pattern] : [];
+  if (!dirname) return matchNames("", basename);
+  const directories = dirname !== pattern && hasGlobMagic(dirname) ? globDirectories(dirname) : [dirname];
+  const results = [];
+  for (const directory of directories) {
+    const names = hasGlobMagic(basename) ? matchNames(directory, basename) : (basename ? lexists(join(directory, basename)) : isDir(directory)) ? [basename] : [];
+    for (const name of names) results.push(join(directory, name));
+  }
+  return results;
+}
+function globDirectories(pattern) {
+  return globPaths(pattern).filter((match) => isDir(match));
+}
+function join(directory, name) {
+  if (name.startsWith("/")) return name;
+  return !directory || directory.endsWith("/") ? directory + name : `${directory}/${name}`;
+}
+function matchNames(directory, pattern) {
+  const where = directory || ".";
+  if (where.includes("\0")) throw new ValidationError("embedded null byte");
+  let names;
+  try {
+    names = readdirSync2(where);
+  } catch {
+    names = [];
+  }
+  if (!isHidden(pattern)) names = names.filter((name) => !isHidden(name));
+  const matches = compileGlob(pattern);
+  return names.filter(matches);
+}
+function compileGlob(pattern) {
+  const chars = Array.from(pattern);
+  const items = [];
+  for (let index = 0; index < chars.length; ) {
+    const char = chars[index++];
+    if (char === "*") {
+      if (items.at(-1)?.kind !== "star") items.push({ kind: "star" });
+    } else if (char === "?") {
+      items.push({ kind: "any" });
+    } else if (char === "[") {
+      const parsed = parseClass(chars, index, pattern);
+      if (parsed) {
+        items.push(parsed.item);
+        index = parsed.end;
+      } else {
+        items.push({ kind: "char", char: char.codePointAt(0) });
+      }
+    } else {
+      items.push({ kind: "char", char: char.codePointAt(0) });
+    }
+  }
+  return (name) => matchItems(items, Array.from(name, (char) => char.codePointAt(0)));
+}
+function parseClass(chars, start, pattern) {
+  let close = start;
+  if (chars[close] === "!") close += 1;
+  if (chars[close] === "]") close += 1;
+  while (close < chars.length && chars[close] !== "]") close += 1;
+  if (close >= chars.length) return null;
+  const body = chars.slice(start, close);
+  const negate = body[0] === "!";
+  const first = negate ? 1 : 0;
+  const tokens = body.map((char) => ({ char, operator: char === "-" }));
+  if (body.join("").includes("--")) {
+    for (const token of tokens) token.operator = false;
+    for (let hyphen = body.indexOf("-", first + 1); hyphen >= 0; hyphen = body.indexOf("-", hyphen + 3)) {
+      tokens[hyphen].operator = true;
+    }
+  }
+  const ranges = [];
+  const point = (char) => char.codePointAt(0);
+  for (let index = first; index < tokens.length; ) {
+    const low = tokens[index++].char;
+    if (!tokens[index]?.operator || index + 1 >= tokens.length) {
+      ranges.push([point(low), point(low)]);
+      continue;
+    }
+    const high = tokens[index + 1].char;
+    index += 2;
+    if (point(high) < point(low)) {
+      throw new GlobPatternError(`bad character range ${low}-${high} in glob pattern ${JSON.stringify(pattern)}`);
+    }
+    ranges.push([point(low), point(high)]);
+  }
+  return { item: { kind: "class", negate, ranges }, end: close + 1 };
+}
+function matchOne(item, char) {
+  if (item.kind === "any") return true;
+  if (item.kind === "char") return item.char === char;
+  if (item.kind === "class") return item.ranges.some(([low, high]) => char >= low && char <= high) !== item.negate;
+  return false;
+}
+function matchItems(items, name) {
+  let item = 0;
+  let char = 0;
+  let starItem = -1;
+  let starChar = 0;
+  while (char < name.length) {
+    if (item < items.length && items[item].kind !== "star" && matchOne(items[item], name[char])) {
+      item += 1;
+      char += 1;
+    } else if (item < items.length && items[item].kind === "star") {
+      starItem = item;
+      starChar = char;
+      item += 1;
+    } else if (starItem >= 0) {
+      item = starItem + 1;
+      starChar += 1;
+      char = starChar;
+    } else {
+      return false;
+    }
+  }
+  while (item < items.length && items[item].kind === "star") item += 1;
+  return item === items.length;
+}
+
+// src/research/sandbox-sed.ts
+var DIGIT = /^[\p{Nd}\u{b2}-\u{b3}\u{b9}\u{1369}-\u{1371}\u{19da}\u{2070}\u{2074}-\u{2079}\u{2080}-\u{2089}\u{2460}-\u{2468}\u{2474}-\u{247c}\u{2488}-\u{2490}\u{24ea}\u{24f5}-\u{24fd}\u{24ff}\u{2776}-\u{277e}\u{2780}-\u{2788}\u{278a}-\u{2792}\u{10a40}-\u{10a43}\u{10e60}-\u{10e68}\u{11052}-\u{1105a}\u{1f100}-\u{1f10a}]$/u;
+var isDigit = (char) => char !== void 0 && DIGIT.test(char);
+var within = (char, set) => set.includes(char ?? "");
+function checkSed(args) {
+  for (const program of sedPrograms(args)) checkSedProgram(program);
+}
+function checkSedProgram(text) {
+  const program = Array.from(text);
+  const length = program.length;
+  let index = 0;
+  const delimited = (start) => {
+    const delimiter = program[start];
+    let cursor = start + 1;
+    while (cursor < length) {
+      if (program[cursor] === "\\") cursor += 2;
+      else if (program[cursor] === delimiter) return cursor + 1;
+      else cursor += 1;
+    }
+    throw new ValidationError("command blocked: unterminated sed expression");
+  };
+  while (index < length) {
+    while (index < length && (isSpace(program[index]) || within(program[index], ";{}"))) index += 1;
+    if (index === length) return;
+    for (let address = 0; address < 2; address += 1) {
+      if (index < length && isDigit(program[index])) {
+        while (index < length && isDigit(program[index])) index += 1;
+      } else if (index < length && program[index] === "$") {
+        index += 1;
+      } else if (index < length && program[index] === "/") {
+        index = delimited(index);
+      } else if (index + 1 < length && program[index] === "\\") {
+        index = delimited(index + 1);
+      } else {
+        break;
+      }
+      while (index < length && isSpace(program[index])) index += 1;
+      if (address === 0 && index < length && program[index] === ",") {
+        index += 1;
+        continue;
+      }
+      break;
+    }
+    while (index < length && (isSpace(program[index]) || program[index] === "!")) index += 1;
+    if (index === length) throw new ValidationError("command blocked: sed command is missing");
+    const command = program[index];
+    index += 1;
+    if (command === "s" && index < length) {
+      index = delimited(index);
+      index = delimited(index - 1);
+      const flagsStart = index;
+      while (index < length && !within(program[index], ";}\n")) index += 1;
+      const flags = Array.from(trimSpace(program.slice(flagsStart, index).join("")));
+      if (flags.some((flag) => !within(flag, "gIp0123456789"))) {
+        throw new ValidationError("command blocked: sed substitution flags can read, write or execute");
+      }
+    } else if (!within(command, "pPdDqQnNhHgGx={}")) {
+      throw new ValidationError("command blocked: sed command can read, write or execute files");
+    }
+    if (!within(command, "{}") && index < length && !(isSpace(program[index]) || within(program[index], ";{}"))) {
+      throw new ValidationError("command blocked: unsupported sed command argument");
+    }
+  }
+}
+function sedPrograms(args) {
+  const programs = [];
+  let index = 0;
+  while (index < args.length) {
+    const arg = args[index];
+    if (arg === "--") {
+      programs.push(...args.slice(index + 1));
+      break;
+    }
+    if (arg === "--file" || arg.startsWith("--file=")) {
+      throw new ValidationError("command blocked: sed script files can read, write or execute");
+    }
+    if (arg === "--expression") {
+      index += 1;
+      if (index >= args.length) throw new ValidationError("command blocked: sed expression is missing");
+      programs.push(args[index]);
+    } else if (arg.startsWith("--expression=")) {
+      programs.push(arg.slice(arg.indexOf("=") + 1));
+    } else if (arg.startsWith("-") && !arg.startsWith("--")) {
+      const short = Array.from(arg).slice(1);
+      for (let offset = 0; offset < short.length; offset += 1) {
+        const option = short[offset];
+        if (option === "f") throw new ValidationError("command blocked: sed script files can read, write or execute");
+        if (option === "e") {
+          let program = short.slice(offset + 1).join("");
+          if (!program) {
+            index += 1;
+            if (index >= args.length) throw new ValidationError("command blocked: sed expression is missing");
+            program = args[index];
+          }
+          programs.push(program);
+          break;
+        }
+        if (!within(option, "nEr")) throw new ValidationError("command blocked: unsupported sed option");
+      }
+    } else if (!arg.startsWith("--")) {
+      if (programs.length === 0) programs.push(arg);
+    } else {
+      throw new ValidationError("command blocked: unsupported sed option");
+    }
+    index += 1;
+  }
+  return programs;
+}
+
+// src/research/shlex.ts
+var ASCII_WORDCHARS = "abcdfeghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_";
+var POSIX_WORDCHARS = "\xDF\xE0\xE1\xE2\xE3\xE4\xE5\xE6\xE7\xE8\xE9\xEA\xEB\xEC\xED\xEE\xEF\xF0\xF1\xF2\xF3\xF4\xF5\xF6\xF8\xF9\xFA\xFB\xFC\xFD\xFE\xFF\xC0\xC1\xC2\xC3\xC4\xC5\xC6\xC7\xC8\xC9\xCA\xCB\xCC\xCD\xCE\xCF\xD0\xD1\xD2\xD3\xD4\xD5\xD6\xD8\xD9\xDA\xDB\xDC\xDD\xDE";
+function within2(char, set) {
+  return set.includes(char);
+}
+function shlexTokens(text, options) {
+  return [...shlexIter(text, options)];
+}
+function* shlexIter(text, options) {
+  const posix = options.posix;
+  const punctuation = options.punctuationChars ?? "";
+  const whitespaceSplit = options.whitespaceSplit ?? false;
+  const commenters = options.commenters ?? "#";
+  let wordchars = ASCII_WORDCHARS + (posix ? POSIX_WORDCHARS : "");
+  if (punctuation) {
+    wordchars += "~-./*?=";
+    wordchars = [...wordchars].filter((char) => !punctuation.includes(char)).join("");
+  }
+  const whitespace = " 	\r\n";
+  const quotes = `'"`;
+  const escape = "\\";
+  const escapedquotes = '"';
+  const eof = posix ? null : "";
+  const chars = Array.from(text);
+  let cursor = 0;
+  const pushbackChars = [];
+  const pushback = [];
+  let state = " ";
+  let token = "";
+  const readChar = () => {
+    if (punctuation && pushbackChars.length > 0) return pushbackChars.pop();
+    if (cursor < chars.length) return chars[cursor++];
+    return "";
+  };
+  const skipLine = () => {
+    while (cursor < chars.length) {
+      const char = chars[cursor++];
+      if (char === "\n") break;
+    }
+  };
+  const readToken = () => {
+    let quoted = false;
+    let escapedstate = " ";
+    for (; ; ) {
+      const nextchar = readChar();
+      if (state === null) {
+        token = "";
+        break;
+      } else if (state === " ") {
+        if (!nextchar) {
+          state = null;
+          break;
+        } else if (within2(nextchar, whitespace)) {
+          if (token || posix && quoted) break;
+          continue;
+        } else if (within2(nextchar, commenters)) {
+          skipLine();
+        } else if (posix && within2(nextchar, escape)) {
+          escapedstate = "a";
+          state = nextchar;
+        } else if (within2(nextchar, wordchars)) {
+          token = nextchar;
+          state = "a";
+        } else if (within2(nextchar, punctuation)) {
+          token = nextchar;
+          state = "c";
+        } else if (within2(nextchar, quotes)) {
+          if (!posix) token = nextchar;
+          state = nextchar;
+        } else if (whitespaceSplit) {
+          token = nextchar;
+          state = "a";
+        } else {
+          token = nextchar;
+          if (token || posix && quoted) break;
+          continue;
+        }
+      } else if (within2(state, quotes)) {
+        quoted = true;
+        if (!nextchar) throw new ValidationError("No closing quotation");
+        if (nextchar === state) {
+          if (!posix) {
+            token += nextchar;
+            state = " ";
+            break;
+          }
+          state = "a";
+        } else if (posix && within2(nextchar, escape) && within2(state, escapedquotes)) {
+          escapedstate = state;
+          state = nextchar;
+        } else {
+          token += nextchar;
+        }
+      } else if (within2(state, escape)) {
+        if (!nextchar) throw new ValidationError("No escaped character");
+        if (within2(escapedstate, quotes) && nextchar !== state && nextchar !== escapedstate) {
+          token += state;
+        }
+        token += nextchar;
+        state = escapedstate;
+      } else if (state === "a" || state === "c") {
+        if (!nextchar) {
+          state = null;
+          break;
+        } else if (within2(nextchar, whitespace)) {
+          state = " ";
+          if (token || posix && quoted) break;
+          continue;
+        } else if (within2(nextchar, commenters)) {
+          skipLine();
+          if (posix) {
+            state = " ";
+            if (token || posix && quoted) break;
+            continue;
+          }
+        } else if (state === "c") {
+          if (within2(nextchar, punctuation)) {
+            token += nextchar;
+          } else {
+            if (!within2(nextchar, whitespace)) pushbackChars.push(nextchar);
+            state = " ";
+            break;
+          }
+        } else if (posix && within2(nextchar, quotes)) {
+          state = nextchar;
+        } else if (posix && within2(nextchar, escape)) {
+          escapedstate = "a";
+          state = nextchar;
+        } else if (within2(nextchar, wordchars) || within2(nextchar, quotes) || whitespaceSplit && !within2(nextchar, punctuation)) {
+          token += nextchar;
+        } else {
+          if (punctuation) pushbackChars.push(nextchar);
+          else pushback.unshift(nextchar);
+          state = " ";
+          if (token || posix && quoted) break;
+          continue;
+        }
+      }
+    }
+    const result = token;
+    token = "";
+    if (posix && !quoted && result === "") return null;
+    return result;
+  };
+  for (; ; ) {
+    const next = pushback.length > 0 ? pushback.shift() : readToken();
+    if (next === eof) return;
+    yield next;
+  }
+}
+
+// src/research/sandbox-validate.ts
+var READ_ONLY_TOOLS = [
+  "ls",
+  "find",
+  "grep",
+  "egrep",
+  "fgrep",
+  "rg",
+  "cat",
+  "head",
+  "tail",
+  "wc",
+  "sort",
+  "uniq",
+  "cut",
+  "tr",
+  "nl",
+  "file",
+  "stat",
+  "du",
+  "tree",
+  "basename",
+  "dirname",
+  "realpath",
+  "readlink",
+  "sed",
+  "jq",
+  "diff",
+  "cmp",
+  "column",
+  "xargs",
+  "git",
+  "tac",
+  "fold",
+  "paste",
+  "comm",
+  "od",
+  "strings",
+  "seq",
+  "expr"
+];
+var SAFE_BUILTINS = /* @__PURE__ */ new Set(["echo", "printf", "true", "false", "test", "[", "pwd"]);
+var READ_ONLY_GIT = /* @__PURE__ */ new Set([
+  "log",
+  "show",
+  "grep",
+  "ls-files",
+  "ls-tree",
+  "diff",
+  "blame",
+  "status",
+  "rev-parse",
+  "cat-file",
+  "shortlog",
+  "describe",
+  "rev-list",
+  "name-rev",
+  "annotate"
+]);
+var READ_ONLY_TOOL_SET = new Set(READ_ONLY_TOOLS);
+var FORBIDDEN_FLAGS = {
+  find: ["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"],
+  sort: ["-o", "--output", "--compress-program", "--files0-from"],
+  wc: ["--files0-from"],
+  grep: ["-f", "--file"],
+  egrep: ["-f", "--file"],
+  fgrep: ["-f", "--file"],
+  rg: ["--pre", "--pre-glob", "--search-zip", "-z", "-f", "--file"],
+  tree: ["-o"],
+  file: ["-C", "--compile", "-f", "--files-from"],
+  jq: ["-f", "--from-file", "-L", "--library-path"],
+  git: ["-C", "-c", "--config-env", "--exec-path", "--output", "-o", "--ext-diff", "--textconv", "--open-files-in-pager", "-O"],
+  diff: ["--to-file"]
+};
+var SED_IN_PLACE = /^(?:-[a-zA-Z]*i|--in-place)/;
+var S = SPACE_CLASS;
+var W = "\\p{L}\\p{N}_";
+var HIDDEN_EXPANSION = /\$\(|`|<\(|>\(|\$'|\$\{|\$[A-Za-z_0-9@*#?!$-]/;
+var ALLOWED_STDERR_REDIRECT = new RegExp(`(?<![${W}>&])2>[${S}]*/dev/null|(?<![${W}>&])2>&1`, "gu");
+var HOME_ESCAPE = new RegExp(`(?:^|[${S}="'])(?:~|\\$HOME(?![${W}])|\\$\\{HOME\\})`, "u");
+var ABS_PATH = new RegExp(`(?:^|[${S}="'(:,])(/[^${S}"';|&)]*)`, "gu");
+var DOTDOT_PATH = new RegExp(`(?:^|[${S}="'/])\\.\\.(?:/|[${S}"']|$)`, "u");
+var FS_ABS_PREFIX = /^\/(?:etc|usr|home|Users|var|tmp|private|opt|root|System|Library|bin|sbin|dev|proc|sys|Applications|Volumes|mnt|media|srv|run|nix|snap)(?:\/|$)/;
+function outsideSingleQuotes(command) {
+  const out = [];
+  let quoted = false;
+  let escaped = false;
+  for (const char of command) {
+    if (quoted) {
+      quoted = char !== "'";
+      out.push(" ");
+      continue;
+    }
+    if (escaped) {
+      escaped = false;
+      out.push(" ");
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      out.push(" ");
+      continue;
+    }
+    if (char === "'") {
+      quoted = true;
+      out.push(out.length > 0 && out[out.length - 1] === "$" ? "'" : " ");
+      continue;
+    }
+    out.push(char);
+  }
+  return out.join("");
+}
+function assertCommandConfined(root, commandText) {
+  if (HOME_ESCAPE.test(commandText)) {
+    throw new ValidationError("command blocked: home-directory path is outside the workspace");
+  }
+  if (DOTDOT_PATH.test(commandText)) {
+    throw new ValidationError("command blocked: '..' walks outside the workspace");
+  }
+  const resolvedRoot = resolvePath(root);
+  for (const match of commandText.matchAll(ABS_PATH)) {
+    const raw = match[1];
+    let candidates;
+    if (hasGlobMagic(raw)) {
+      const matches = globPaths(raw).map(cleanPath);
+      if (matches.length === 0 && !raw.startsWith(resolvedRoot)) {
+        throw new ValidationError(`command blocked: path pattern escapes workspace: ${raw}`);
+      }
+      candidates = matches;
+    } else {
+      const candidate = cleanPath(raw);
+      if (FS_ABS_PREFIX.exec(raw) === null && !exists(candidate)) continue;
+      candidates = [candidate];
+    }
+    for (const candidate of candidates) {
+      if (escapesRoot(resolvePath(candidate), resolvedRoot)) {
+        throw new ValidationError(`command blocked: path escapes workspace: ${raw}`);
+      }
+    }
+  }
+}
+var OPERATOR_CHARS = new Set(";&|()<>");
+var SEPARATORS = /* @__PURE__ */ new Set(["|", "||", "&&", ";"]);
+var LITERAL_OPEN = "\uE000";
+var LITERAL_CLOSE = "\uE001";
+function protectLiteralParens(commandText) {
+  let out = "";
+  let quote;
+  for (let index = 0; index < commandText.length; index++) {
+    const char = commandText[index];
+    if (quote === void 0 && char === "\\" && (commandText[index + 1] === "(" || commandText[index + 1] === ")")) {
+      out += commandText[index + 1] === "(" ? LITERAL_OPEN : LITERAL_CLOSE;
+      index += 1;
+      continue;
+    }
+    if (quote === void 0 && char === "\\") {
+      out += char + (commandText[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+    if (quote === void 0 && (char === "'" || char === '"')) quote = char;
+    else if (quote === char) quote = void 0;
+    else if (quote !== void 0 && (char === "(" || char === ")")) {
+      out += char === "(" ? LITERAL_OPEN : LITERAL_CLOSE;
+      continue;
+    }
+    out += char;
+  }
+  return out;
+}
+var restoreParens = (token) => token.replaceAll(LITERAL_OPEN, "(").replaceAll(LITERAL_CLOSE, ")");
+function segments(commandText) {
+  const tokens = [...shlexIter(protectLiteralParens(commandText), { posix: true, punctuationChars: ";&|()<>", whitespaceSplit: true, commenters: "" })];
+  const result = [[]];
+  for (const raw of tokens) {
+    if (raw.includes(LITERAL_OPEN) || raw.includes(LITERAL_CLOSE)) {
+      result[result.length - 1].push(restoreParens(raw));
+      continue;
+    }
+    const token = raw;
+    if (SEPARATORS.has(token)) {
+      result.push([]);
+    } else if (token && [...token].every((char) => OPERATOR_CHARS.has(char))) {
+      if (token === "<") {
+        result[result.length - 1].push(token);
+        continue;
+      }
+      throw new ValidationError(
+        `command blocked: shell operator '${token}' is not allowed (read-only research: no output redirection, background jobs or subshells)`
+      );
+    } else {
+      result[result.length - 1].push(token);
+    }
+  }
+  return result.filter((segment) => segment.length > 0);
+}
+var inShortCluster = (arg, letters) => arg.startsWith("-") && !arg.startsWith("--") && arg.slice(1).includes(letters);
+function checkTool(words) {
+  if (words.length === 0) return;
+  const name = words[0];
+  const args = words.slice(1);
+  if (name.includes("/")) throw new ValidationError(`command blocked: run tools by name, not path: ${name}`);
+  if (SAFE_BUILTINS.has(name)) return;
+  if (!READ_ONLY_TOOL_SET.has(name)) {
+    throw new ValidationError(
+      `command blocked: '${name}' is not a read-only research tool (allowed: ${READ_ONLY_TOOLS.join(", ")})`
+    );
+  }
+  for (const flag of FORBIDDEN_FLAGS[name] ?? []) {
+    if (args.some((arg) => arg === flag || arg.startsWith(`${flag}=`) || flag.length === 2 && flag.startsWith("-") && inShortCluster(arg, flag[1]))) {
+      throw new ValidationError(`command blocked: \`${name} ${flag}\` loads external arguments, writes or executes`);
+    }
+  }
+  if (name === "sed") {
+    for (const arg of args) {
+      if (SED_IN_PLACE.test(arg)) throw new ValidationError("command blocked: sed -i edits files");
+    }
+    checkSed(args);
+  }
+  if (name === "git") {
+    const allowed = [...READ_ONLY_GIT].sort().join(", ");
+    const subcommand = args.find((arg) => !arg.startsWith("-"));
+    if (subcommand === void 0) {
+      throw new ValidationError(`command blocked: \`git\` needs a read-only subcommand (allowed: ${allowed})`);
+    }
+    if (!READ_ONLY_GIT.has(subcommand)) {
+      throw new ValidationError(`command blocked: \`git ${subcommand}\` is not read-only (allowed: ${allowed})`);
+    }
+  }
+  if (name === "xargs") {
+    if (args.some((arg) => arg === "--arg-file" || arg.startsWith("--arg-file=") || arg.startsWith("-a") && !arg.startsWith("--"))) {
+      throw new ValidationError("command blocked: xargs argument files cannot be confined");
+    }
+    const target = xargsCommand(args);
+    if (!["echo", "printf", "true", "false"].includes(target[0])) {
+      throw new ValidationError(`command blocked: xargs can only feed echo/printf here (its file arguments cannot be confined). Search file contents directly instead: grep -rln --include='*.ts' "PATTERN" .  or  rg -l "PATTERN"`);
+    }
+    checkTool(target);
+  }
+}
+var XARGS_WITH_VALUE = /* @__PURE__ */ new Set(["-n", "-I", "-d", "-P", "-L", "-s", "-E", "-a", "--arg-file", "--delimiter", "--max-args", "--max-procs"]);
+function xargsCommand(args) {
+  let index = 0;
+  while (index < args.length && args[index].startsWith("-")) index += XARGS_WITH_VALUE.has(args[index]) ? 2 : 1;
+  const command = args.slice(index);
+  return command.length > 0 ? command : ["echo"];
+}
+var FOLLOW_FLAGS = { rg: "L", grep: "R", egrep: "R", fgrep: "R", find: "L", tree: "l", du: "L" };
+var SHELL_CONSTRUCTS = /* @__PURE__ */ new Set(["for", "while", "until", "if", "case", "function", "{", "eval", "exec", "source", "."]);
+function validateCommand(root, commandTextInput) {
+  if (!trimSpace(commandTextInput)) throw new ValidationError("empty shell command");
+  if (trimSpace(commandTextInput).includes("\n")) throw new ValidationError("command blocked: send one command line per turn");
+  const commandText = trimSpace(commandTextInput.replace(ALLOWED_STDERR_REDIRECT, " "));
+  if (HIDDEN_EXPANSION.test(outsideSingleQuotes(commandText))) {
+    throw new ValidationError(
+      "command blocked: command substitution, process substitution and $-expansion are not allowed; write paths and patterns literally"
+    );
+  }
+  for (const token of shlexIter(commandText, { posix: false, whitespaceSplit: true, commenters: "" })) {
+    if (token.startsWith("'") || token.startsWith('"') || token.startsWith("--exclude-dir=")) continue;
+    if (token.includes("{") || token.includes("}")) {
+      throw new ValidationError("command blocked: brace-expanded paths cannot be confined");
+    }
+  }
+  const resolvedRoot = () => resolvePath(root);
+  for (const segment of segments(commandText)) {
+    for (let word of segment.slice(1)) {
+      if (word.startsWith("--exclude-dir=")) continue;
+      if (word === "<") continue;
+      if (word.startsWith("-")) {
+        if (!word.includes("=")) continue;
+        word = word.slice(word.indexOf("=") + 1);
+      }
+      const candidate = joinPath(root, word);
+      const candidates = hasGlobMagic(word) ? globPaths(candidate).map(cleanPath) : [candidate];
+      for (const item of candidates) {
+        if ((exists(item) || isSymlink(item)) && escapesRoot(resolvePath(item), resolvedRoot())) {
+          throw new ValidationError("command blocked: relative path escapes workspace");
+        }
+      }
+    }
+    const tool = segment[0];
+    const followFlags = Object.hasOwn(FOLLOW_FLAGS, tool) ? FOLLOW_FLAGS[tool] : void 0;
+    if (followFlags && segment.slice(1).some((arg) => arg === "--follow" || arg === "--dereference" || arg === "--dereference-recursive" || inShortCluster(arg, followFlags))) {
+      throw new ValidationError("command blocked: recursive symlink following cannot be confined");
+    }
+    if (tool.includes("=") && !tool.startsWith("=")) {
+      throw new ValidationError("command blocked: variable assignment is not allowed");
+    }
+    if (SHELL_CONSTRUCTS.has(tool)) {
+      throw new ValidationError(`command blocked: shell construct '${tool}' is not allowed; use one pipeline`);
+    }
+    checkTool(segment.filter((word) => word !== "<"));
+  }
+  assertCommandConfined(root, commandText);
+  return commandText;
+}
+
+// src/research/sandbox.ts
+function macosProfile(workspace, scratch, readPaths = []) {
+  const quote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+  const extra = readPaths.map((dir) => ` (subpath ${quote(dir)})`).join("");
+  return `(version 1)
+(allow default)
+(deny network*)
+(deny file-write*)
+(allow file-write* (literal "/dev/null") (literal "/dev/tty") (literal "/dev/dtracehelper") (subpath ${quote(scratch)}))
+(deny file-read-data (subpath "/Users") (subpath "/Volumes") (subpath "/private/var/root"))
+(allow file-read-data (subpath ${quote(workspace)}) (subpath ${quote(scratch)})${extra})
+`;
+}
+function which(name, envPath = process.env.PATH) {
+  const searchPath = envPath ?? "/bin:/usr/bin";
+  if (!searchPath) return null;
+  const seen = /* @__PURE__ */ new Set();
+  for (const directory of searchPath.split(":")) {
+    if (seen.has(directory)) continue;
+    seen.add(directory);
+    const candidate = directory ? directory.endsWith("/") ? directory + name : `${directory}/${name}` : name;
+    try {
+      accessSync(candidate, fsConstants.X_OK);
+    } catch {
+      continue;
+    }
+    if (!isDir(candidate)) return candidate;
+  }
+  return null;
+}
+var KEPT_ENV = /* @__PURE__ */ new Set(["LANG", "LC_ALL", "LC_CTYPE", "TZ"]);
+var ReadOnlyShell = class {
+  workspace;
+  kind = "restricted-bash";
+  prefix = [];
+  env = {};
+  bash = "/bin/bash";
+  scratch = null;
+  /** Directories outside the workspace the shell may also read, such as a worktree's git directory. */
+  readPaths;
+  constructor(workspace, options = {}) {
+    this.workspace = workspace;
+    this.readPaths = options.readPaths ?? [];
+  }
+  enter() {
+    this.workspace = resolvePath(this.workspace);
+    const scratch = mkdtempSync2(path6.join(path6.resolve(tmpdir2()), "freellama-shell-"));
+    this.scratch = scratch;
+    const binDir = path6.join(scratch, "bin");
+    mkdirSync3(binDir);
+    for (const tool of READ_ONLY_TOOLS) {
+      const located = which(tool);
+      if (located) symlinkSync(realpathSync(located), path6.join(binDir, tool));
+    }
+    this.bash = which("bash") ?? "/bin/bash";
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (KEPT_ENV.has(key) && value !== void 0) env[key] = value;
+    }
+    Object.assign(env, {
+      PATH: binDir,
+      HOME: this.workspace,
+      TMPDIR: scratch,
+      TERM: "dumb",
+      PAGER: "cat",
+      GIT_PAGER: "cat",
+      GIT_CONFIG_NOSYSTEM: "1",
+      GIT_CONFIG_GLOBAL: "/dev/null",
+      GIT_OPTIONAL_LOCKS: "0",
+      // `git status` otherwise rewrites the index
+      GIT_TERMINAL_PROMPT: "0"
+    });
+    this.env = env;
+    this.prefix = this.osSandbox(scratch, binDir);
+    return this;
+  }
+  close() {
+    if (this.scratch !== null) {
+      rmSync2(this.scratch, { recursive: true, force: true });
+      this.scratch = null;
+    }
+  }
+  osSandbox(scratch, binDir) {
+    if ((process.env.FREELLAMA_AGENT_OS_SANDBOX ?? "auto") === "off") return [];
+    const sandboxExec = which("sandbox-exec");
+    if (sandboxExec) {
+      const profile = path6.join(scratch, "profile.sb");
+      writeFileSync2(profile, macosProfile(this.workspace, scratch, this.readPaths), "utf8");
+      const prefix = [sandboxExec, "-f", profile];
+      if (probe2([...prefix, this.bash, "-c", "true"], this.env)) {
+        this.kind = "sandbox-exec+restricted-bash";
+        return prefix;
+      }
+    }
+    const bwrap = which("bwrap");
+    if (bwrap) {
+      const prefix = [bwrap, "--unshare-all", "--die-with-parent", "--new-session", "--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp"];
+      for (const systemDir of ["/usr", "/bin", "/sbin", "/lib", "/lib32", "/lib64", "/etc/alternatives", "/etc/ld.so.cache", "/etc/localtime", "/nix/store"]) {
+        prefix.push("--ro-bind-try", systemDir, systemDir);
+      }
+      prefix.push(
+        "--ro-bind",
+        this.workspace,
+        this.workspace,
+        ...this.readPaths.flatMap((dir) => ["--ro-bind", dir, dir]),
+        "--ro-bind",
+        binDir,
+        binDir,
+        "--bind",
+        scratch,
+        scratch,
+        "--chdir",
+        this.workspace,
+        "--"
+      );
+      if (probe2([...prefix, this.bash, "-c", "true"], this.env)) {
+        this.kind = "bwrap+restricted-bash";
+        return prefix;
+      }
+    }
+    return [];
+  }
+  /**
+   * Run one read-only tool with an argument vector, no shell: the structured `search` action uses
+   * it so a pattern such as `${x}` or `(` is data, never shell syntax. Same OS sandbox, PATH and
+   * scrubbed environment as `run`; exit 1 of a search means no matches.
+   */
+  /** Whether `tool` was found on the caller's PATH when the shell was entered. */
+  hasTool(tool) {
+    return this.scratch !== null && existsSync4(path6.join(this.scratch, "bin", tool));
+  }
+  async runTool(argv, timeoutSeconds) {
+    const [tool, ...args] = argv;
+    if (!tool || !READ_ONLY_TOOLS.includes(tool) || this.scratch === null) {
+      throw new ValidationError(`tool ${tool ?? "(none)"} is not available to structured actions`);
+    }
+    const result = await runProcess(
+      [...this.prefix, path6.join(this.scratch, "bin", tool), ...args],
+      { cwd: this.workspace, env: this.env, timeoutSeconds }
+    );
+    if (result.returncode === 1 && !trimSpace(result.stderr)) return "(no matches)";
+    if (result.returncode !== 0) throw new ToolExitError(result.returncode, result.stdout + result.stderr);
+    return trimSpace(result.stdout) ? result.stdout : "(no matches)";
+  }
+  async run(commandText, timeoutSeconds) {
+    const command = validateCommand(this.workspace, commandText);
+    const tokens = shlexTokens(command, { posix: true, punctuationChars: ";&|()<>", whitespaceSplit: true, commenters: "" });
+    if (tokens.some((token) => token === ";" || token === "&&" || token === "||")) {
+      throw new ValidationError("command blocked: send one pipeline per turn so each execution outcome can be recorded");
+    }
+    const result = await runProcess(
+      [...this.prefix, this.bash, "--restricted", "--noprofile", "--norc", "-o", "pipefail", "-c", command],
+      { cwd: this.workspace, env: this.env, timeoutSeconds }
+    );
+    let output = result.stdout + result.stderr;
+    if (result.returncode !== 0) {
+      const parts = segments(command);
+      const words = parts.length === 1 ? parts[0] : [];
+      const isSearch = ["rg", "grep", "egrep", "fgrep"].includes(words[0] ?? "") || words[0] === "git" && words[1] === "grep";
+      const isDiff = words[0] === "diff" || words[0] === "git" && words[1] === "diff";
+      if (result.returncode === 1 && isSearch && !trimSpace(result.stderr)) {
+        throw new ToolExitError(result.returncode, output, "empty");
+      }
+      if (!(result.returncode === 1 && isDiff && !trimSpace(result.stderr))) {
+        throw new ToolExitError(result.returncode, output);
+      }
+    }
+    if (!trimSpace(output)) output = `(no output, exit code ${result.returncode})`;
+    return output;
+  }
+};
+
+// src/research/structured-actions.ts
+import { existsSync as existsSync5, readdirSync as readdirSync3, readFileSync as readFileSync6, realpathSync as realpathSync2, statSync as statSync2 } from "node:fs";
+import path7 from "node:path";
+var SKIPPED_DIRS = ["node_modules", "target", "dist", "build", ".git", ".venv", "venv", "vendor", "__pycache__", ".octocode", "site-packages", "coverage"];
+var READ_DEFAULT_LINES = 120;
+var READ_MAX_LINES = 400;
+var LIST_MAX_ENTRIES = 300;
+var SEARCH_MAX_PER_FILE = 20;
+function confined(workspace, rel) {
+  const raw = (rel ?? ".").trim() || ".";
+  if (path7.isAbsolute(raw) && !raw.startsWith(workspace)) throw new ValidationError(`path is outside the workspace: ${raw}`);
+  const absolute = path7.resolve(workspace, raw);
+  const real = existsSync5(absolute) ? realpathSync2(absolute) : absolute;
+  if (escapesRoot(real, workspace)) throw new ValidationError(`path is outside the workspace: ${raw}`);
+  return path7.relative(workspace, real) || ".";
+}
+function validateSearch(value) {
+  if (typeof value.pattern !== "string" || !value.pattern.trim()) throw new ValidationError("search action requires a non-empty string pattern");
+  if (value.pattern.length > 300) throw new ValidationError("search pattern is longer than 300 characters");
+  for (const key of ["path", "glob"]) {
+    if (value[key] !== void 0 && typeof value[key] !== "string") throw new ValidationError(`search ${key} must be a string`);
+  }
+  for (const key of ["regex", "ignoreCase"]) {
+    if (value[key] !== void 0 && typeof value[key] !== "boolean") throw new ValidationError(`search ${key} must be true or false`);
+  }
+}
+function validateRead(value) {
+  if (typeof value.path !== "string" || !value.path.trim()) throw new ValidationError("read action requires a file path");
+  for (const key of ["start", "end"]) {
+    const n = value[key];
+    if (n !== void 0 && (typeof n !== "number" || !Number.isInteger(n) || n < 1)) throw new ValidationError(`read ${key} must be a positive integer line number`);
+  }
+}
+function searchArgv(workspace, action, ripgrep) {
+  const target = confined(workspace, action.path);
+  if (ripgrep) {
+    return [
+      "rg",
+      "-n",
+      "--no-heading",
+      "--color",
+      "never",
+      "--max-columns",
+      "300",
+      "--max-count",
+      String(SEARCH_MAX_PER_FILE),
+      ...action.regex ? [] : ["-F"],
+      ...action.ignoreCase ? ["-i"] : [],
+      ...action.glob ? ["-g", action.glob] : [],
+      ...SKIPPED_DIRS.flatMap((dir) => ["-g", `!${dir}/`]),
+      "-e",
+      action.pattern,
+      "--",
+      target
+    ];
+  }
+  return [
+    "grep",
+    "-rnI",
+    ...action.regex ? ["-E"] : ["-F"],
+    ...action.ignoreCase ? ["-i"] : [],
+    ...action.glob ? [`--include=${action.glob}`] : [],
+    ...SKIPPED_DIRS.map((dir) => `--exclude-dir=${dir}`),
+    "-e",
+    action.pattern,
+    "--",
+    target
+  ];
+}
+function readLines(workspace, action) {
+  const resolved = resolveNamedPath(workspace, action.path, "file");
+  if (resolved.path === void 0) throw new ValidationError(`no such file: ${resolved.note}; search or list to find the right path`);
+  const rel = resolved.path;
+  const absolute = path7.join(workspace, rel);
+  if (!statSync2(absolute).isFile()) throw new ValidationError(`${rel} is a directory; use list`);
+  const bytes = readFileSync6(absolute);
+  if (bytes.includes(0)) throw new ValidationError(`${rel} is binary`);
+  const text = bytes.toString("utf8");
+  const lines = (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n");
+  const start = Math.min(action.start ?? 1, Math.max(lines.length, 1));
+  const end = Math.min(action.end ?? start + READ_DEFAULT_LINES - 1, start + READ_MAX_LINES - 1, lines.length);
+  const width = String(end).length;
+  const body = lines.slice(start - 1, end).map((line2, index) => `${String(start + index).padStart(width)}  ${line2}`).join("\n");
+  const more = end < lines.length ? `
+(${rel} has ${lines.length} lines; read start=${end + 1} for more)` : "";
+  return `${resolved.note ? `${resolved.note}
+` : ""}${rel}:${start}-${end}
+${body}${more}`;
+}
+function listEntries(workspace, rel) {
+  const resolved = resolveNamedPath(workspace, rel, "dir");
+  if (resolved.path === void 0) throw new ValidationError(`not a directory: ${resolved.note}`);
+  const base = resolved.path;
+  const root = path7.join(workspace, base);
+  if (!statSync2(root).isDirectory()) throw new ValidationError(`not a directory: ${base}; read it instead`);
+  const out = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = readdirSync3(dir, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (out.length >= LIST_MAX_ENTRIES) return;
+      if (entry.name.startsWith(".") || SKIPPED_DIRS.includes(entry.name)) continue;
+      const shown = path7.relative(workspace, path7.join(dir, entry.name));
+      out.push(entry.isDirectory() ? `${shown}/` : shown);
+      if (entry.isDirectory() && depth < 1) walk(path7.join(dir, entry.name), depth + 1);
+    }
+  };
+  walk(root, 0);
+  const listing = out.length === 0 ? `(${base} is empty)` : out.join("\n") + (out.length >= LIST_MAX_ENTRIES ? "\n(listing truncated; list a subdirectory)" : "");
+  return resolved.note ? `${resolved.note}
+${listing}` : listing;
+}
+var INDEX_MAX_ENTRIES = 5e4;
+var indexes = /* @__PURE__ */ new Map();
+function workspaceIndex(workspace) {
+  const cached = indexes.get(workspace);
+  if (cached) return cached;
+  const files = [];
+  const dirs = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync3(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (files.length + dirs.length >= INDEX_MAX_ENTRIES) return;
+      if (entry.name.startsWith(".") || SKIPPED_DIRS.includes(entry.name)) continue;
+      const absolute = path7.join(dir, entry.name);
+      const rel = path7.relative(workspace, absolute);
+      if (entry.isDirectory()) {
+        dirs.push(rel);
+        walk(absolute);
+      } else if (entry.isFile()) {
+        files.push(rel);
+      }
+    }
+  };
+  walk(workspace);
+  const index = { files, dirs };
+  indexes.set(workspace, index);
+  return index;
+}
+function forgetWorkspaceIndex(workspace) {
+  indexes.delete(workspace);
+}
+function pathCandidates(workspace, rel, kind = "any") {
+  const wanted = rel.replace(/^\.\//, "").replace(/\/+$/, "");
+  if (!wanted || wanted === ".") return [];
+  const { files, dirs } = workspaceIndex(workspace);
+  const pool = kind === "file" ? files : kind === "dir" ? dirs : [...files, ...dirs];
+  const suffix = `/${wanted}`;
+  return pool.filter((candidate) => candidate === wanted || candidate.endsWith(suffix)).sort((a, b) => a.length - b.length);
+}
+function resolveNamedPath(workspace, rel, kind) {
+  const named = confined(workspace, rel);
+  if (named === "." || existsSync5(path7.join(workspace, named))) return { path: named };
+  const candidates = pathCandidates(workspace, named, kind);
+  if (candidates.length === 1) return { path: candidates[0], note: `(${named} does not exist; using ${candidates[0]})` };
+  if (candidates.length > 1) {
+    return { path: void 0, note: `${named} does not exist; matching paths: ${candidates.slice(0, 8).join(", ")}${candidates.length > 8 ? ", \u2026" : ""}` };
+  }
+  return { path: void 0, note: `${named} does not exist and no path ends with it` };
+}
+function looksLikeRegex(pattern) {
+  return /\||\.\*|\\[bswdBSWD]|\[[^\]]+\]|^\^|\$$|\(\?|\.\+/.test(pattern);
+}
+
+// src/research/coder-actions.ts
+var WRITE_MAX_BYTES = 256 * 1024;
+var MAX_ALLOWED_COMMANDS = 10;
+var DEFAULT_RUN_TIMEOUT_SECONDS = 300;
+var MAX_RUN_TIMEOUT_SECONDS = 1800;
+var OBSERVATION_LINES = { head: 10, tail: 40, lineChars: 240 };
+var RESULT_LINES = { head: 20, tail: 80, lineChars: 300 };
+var CAPTURE_HEAD_BYTES = 256 * 1024;
+var CAPTURE_TAIL_BYTES = 1024 * 1024;
+var EDIT_PREVIEW_LINES = 12;
+function confinedWritePath(root, rel) {
+  if (typeof rel !== "string" || !rel.trim()) throw new ValidationError("a file path is required");
+  const raw = rel.trim();
+  if (raw.includes("\0")) throw new ValidationError("path contains a NUL byte");
+  const lexical = path8.resolve(root, raw);
+  const relative = path8.relative(root, lexical);
+  if (!relative || relative.startsWith("..") || path8.isAbsolute(relative)) {
+    throw new ValidationError(`path is outside the copy: ${raw}`);
+  }
+  if (relative.split(path8.sep).includes(".git")) throw new ValidationError(`${relative} is inside .git, which is not editable`);
+  const physical = resolvePath(lexical);
+  if (escapesRoot(physical, root)) throw new ValidationError(`path leaves the copy through a symlink: ${raw}`);
+  return { rel: relative, absolute: physical };
+}
+function occurrences(text, needle) {
+  const found = [];
+  for (let at = text.indexOf(needle); at >= 0; at = text.indexOf(needle, at + needle.length)) found.push(at);
+  return found;
+}
+var lineAt = (text, offset) => text.slice(0, offset).split("\n").length;
+function looseMatchLine(text, search) {
+  const wanted = search.split("\n").map((part) => part.trim());
+  while (wanted.length > 0 && wanted[wanted.length - 1] === "") wanted.pop();
+  if (wanted.length === 0) return void 0;
+  const lines = text.split("\n").map((part) => part.trim());
+  const hits = [];
+  for (let index = 0; index + wanted.length <= lines.length && hits.length < 2; index += 1) {
+    if (wanted.every((part, offset) => lines[index + offset] === part)) hits.push(index + 1);
+  }
+  return hits.length === 1 ? hits[0] : void 0;
+}
+function numbered(text, from, to) {
+  const lines = text.split("\n");
+  const end = Math.min(to, from + EDIT_PREVIEW_LINES - 1, lines.length);
+  const width = String(end).length;
+  return lines.slice(from - 1, end).map((part, index) => `${String(from + index).padStart(width)}  ${part}`).join("\n") + (end < to ? `
+(${to - end} more changed lines)` : "");
+}
+function applyEdit(root, action) {
+  const resolved = resolveNamedPath(root, action.path, "file");
+  if (resolved.path === void 0) throw new ValidationError(`no such file: ${resolved.note}; use write to create a file`);
+  const { rel, absolute } = confinedWritePath(root, resolved.path);
+  if (!statSync3(absolute).isFile()) throw new ValidationError(`${rel} is not a file`);
+  const bytes = readFileSync7(absolute);
+  if (bytes.includes(0)) throw new ValidationError(`${rel} is binary and cannot be edited`);
+  const text = bytes.toString("utf8");
+  const crlf = text.includes("\r\n") && !action.search.includes("\r");
+  const search = crlf ? action.search.replaceAll("\n", "\r\n") : action.search;
+  const replace = crlf ? action.replace.replaceAll("\n", "\r\n") : action.replace;
+  const found = occurrences(text, search);
+  if (found.length === 0) {
+    const loose = looseMatchLine(text.replaceAll("\r\n", "\n"), action.search);
+    throw new ValidationError(
+      `search text not found in ${rel} (0 matches). ` + (loose ? `It matches line ${loose} if indentation is ignored: read those lines and copy them exactly. ` : "Read the lines again and copy them exactly, indentation included. ") + "Nothing was changed."
+    );
+  }
+  if (found.length > 1) {
+    const lines = found.slice(0, 6).map((offset) => lineAt(text, offset)).join(", ");
+    throw new ValidationError(`search text matches ${found.length} times in ${rel} (lines ${lines}${found.length > 6 ? ", \u2026" : ""}); include more surrounding lines so it matches exactly once. Nothing was changed.`);
+  }
+  const at = found[0];
+  const updated = text.slice(0, at) + replace + text.slice(at + search.length);
+  writeFileSync3(absolute, updated);
+  const first = lineAt(updated, at);
+  const removed = search.split("\n").length;
+  const added = replace === "" ? 0 : replace.split("\n").length;
+  const shown = updated.replaceAll("\r\n", "\n");
+  return `${resolved.note ? `${resolved.note}
+` : ""}edited ${rel}: ${removed} line(s) at line ${first} replaced by ${added} line(s)` + (added > 0 ? `
+${numbered(shown, first, first + added - 1)}` : "");
+}
+function writeWholeFile(root, action) {
+  const { rel, absolute } = confinedWritePath(root, action.path);
+  const size = Buffer.byteLength(action.content, "utf8");
+  if (size > WRITE_MAX_BYTES) throw new ValidationError(`content is ${size} bytes; write accepts at most ${WRITE_MAX_BYTES} (use edit for large files)`);
+  const existed = existsSync6(absolute);
+  if (existed && !statSync3(absolute).isFile()) throw new ValidationError(`${rel} is a directory`);
+  mkdirSync4(path8.dirname(absolute), { recursive: true });
+  writeFileSync3(absolute, action.content);
+  const lines = action.content === "" ? 0 : action.content.split("\n").length - (action.content.endsWith("\n") ? 1 : 0);
+  return `${existed ? "replaced" : "created"} ${rel} (${lines} lines, ${size} bytes)`;
+}
+function allowedCommand(requested, allowed) {
+  if (typeof requested !== "string" || !requested.trim()) throw new ValidationError("run requires a command");
+  if (allowed.length === 0) throw new ValidationError("no commands are allowed in this task, so nothing can be run; finish and say the change is untested");
+  const match = allowed.find((command) => command === requested.trim());
+  if (match === void 0) {
+    throw new ValidationError(`command not allowed: ${JSON.stringify(requested)}. Run exactly one of: ${allowed.map((command) => JSON.stringify(command)).join(", ")}`);
+  }
+  return match;
+}
+function normalizeAllowedCommands(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value) || value.some((command) => typeof command !== "string")) throw new ValidationError("commands must be an array of strings");
+  const commands = [...new Set(value.map((command) => command.trim()))];
+  if (commands.some((command) => !command || /[\n\r\0]/.test(command))) throw new ValidationError("each command must be one non-empty line");
+  if (commands.length > MAX_ALLOWED_COMMANDS) throw new ValidationError(`at most ${MAX_ALLOWED_COMMANDS} commands may be allowed`);
+  return commands;
+}
+var ANSI = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
+var lenient = new TextDecoder("utf-8", { fatal: false });
+function headTail(text, options, gap) {
+  const lines = text.endsWith("\n") ? text.slice(0, -1).split("\n") : text.split("\n");
+  const clip2 = (part) => part.length > options.lineChars ? `${part.slice(0, options.lineChars)}\u2026` : part;
+  const marker = (count) => `\u2026 ${count} lines omitted \u2026`;
+  if (lines.length <= options.head + options.tail) {
+    if (!gap) return lines.map(clip2).join("\n");
+    return [...lines.slice(0, gap.line).map(clip2), marker(gap.lines), ...lines.slice(gap.line).map(clip2)].join("\n");
+  }
+  const cutEnd = lines.length - options.tail;
+  const insideCut = gap !== void 0 && gap.line >= options.head && gap.line <= cutEnd;
+  const omitted = cutEnd - options.head + (insideCut ? gap.lines : 0);
+  const kept = [...lines.slice(0, options.head).map(clip2), marker(omitted), ...lines.slice(cutEnd).map(clip2)];
+  if (gap && !insideCut) {
+    const at = gap.line < options.head ? gap.line : gap.line - cutEnd + options.head + 1;
+    kept.splice(at, 0, marker(gap.lines));
+  }
+  return kept.join("\n");
+}
+var OutputCapture = class {
+  head = [];
+  headBytes = 0;
+  tail = [];
+  tailBytes = 0;
+  droppedLines = 0;
+  droppedBytes = 0;
+  push(chunk) {
+    if (this.headBytes < CAPTURE_HEAD_BYTES) {
+      const taken = chunk.subarray(0, CAPTURE_HEAD_BYTES - this.headBytes);
+      this.head.push(taken);
+      this.headBytes += taken.length;
+      chunk = chunk.subarray(taken.length);
+    }
+    if (chunk.length === 0) return;
+    this.tail.push(chunk);
+    this.tailBytes += chunk.length;
+    while (this.tailBytes - this.tail[0].length >= CAPTURE_TAIL_BYTES) {
+      const dropped = this.tail.shift();
+      this.tailBytes -= dropped.length;
+      this.droppedBytes += dropped.length;
+      for (let at = dropped.indexOf(10); at >= 0; at = dropped.indexOf(10, at + 1)) this.droppedLines += 1;
+    }
+  }
+  /** The decoded text, and where bytes were dropped (a line index into it) when they were. */
+  text() {
+    const clean2 = (bytes) => lenient.decode(bytes).replace(ANSI, "").replace(/\r\n?/g, "\n");
+    const head = clean2(Buffer.concat(this.head));
+    const tail = clean2(Buffer.concat(this.tail));
+    if (this.droppedBytes === 0) return { text: head + tail };
+    const headLines = head.split("\n").length;
+    return { text: `${head}
+${tail}`, gap: { line: headLines, lines: this.droppedLines } };
+  }
+};
+function descendants(pid) {
+  const listing = spawnSync2("ps", ["-A", "-o", "pid=,ppid="], { encoding: "utf8" });
+  if (listing.status !== 0) return [];
+  const children = /* @__PURE__ */ new Map();
+  for (const row of listing.stdout.split("\n")) {
+    const [child, parent] = row.trim().split(/\s+/).map(Number);
+    if (!child || parent === void 0 || Number.isNaN(parent)) continue;
+    children.set(parent, [...children.get(parent) ?? [], child]);
+  }
+  const out = [];
+  const queue = [pid];
+  while (queue.length > 0) {
+    for (const child of children.get(queue.shift()) ?? []) {
+      out.push(child);
+      queue.push(child);
+    }
+  }
+  return out;
+}
+function killTree(pid) {
+  for (const target of [pid, ...descendants(pid)]) {
+    try {
+      process.kill(target, "SIGKILL");
+    } catch {
+    }
+  }
+}
+var SECRET_HOME_PATHS = [".ssh", ".aws", ".gnupg", ".config/gh", ".netrc", ".git-credentials", ".docker", ".kube", ".octocode", "Library/Keychains"];
+function secretPaths(env) {
+  const candidates = [
+    ...env.HOME ? SECRET_HOME_PATHS.map((rel) => path8.join(env.HOME, rel)) : [],
+    ...env.FREELLAMA_HOME ? [env.FREELLAMA_HOME] : []
+  ];
+  const found = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    try {
+      found.add(realpathSync3(candidate));
+    } catch {
+    }
+  }
+  return [...found];
+}
+function macosRunProfile(writable, hidden) {
+  const quote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+  const unreadable = hidden.map((target) => ` (${lstatSync2(target).isDirectory() ? "subpath" : "literal"} ${quote(target)})`).join("");
+  return `(version 1)
+(allow default)
+(deny network*)
+(deny file-write*)
+(allow file-write* (literal "/dev/null") (literal "/dev/tty") (literal "/dev/dtracehelper") (regex #"^/dev/fd/")${writable.map((dir) => ` (subpath ${quote(dir)})`).join("")})
+${unreadable ? `(deny file-read* file-write*${unreadable})
+` : ""}`;
+}
+var CommandRunner = class {
+  constructor(cwd, writable, env, options) {
+    this.cwd = cwd;
+    this.writable = writable;
+    this.env = env;
+    this.options = options;
+  }
+  cwd;
+  writable;
+  env;
+  options;
+  kind = "none";
+  prefix = [];
+  enter() {
+    if (this.options.osSandbox === "off") return this;
+    const sandboxExec = which("sandbox-exec");
+    if (sandboxExec) {
+      const profile = path8.join(this.options.privateDir, "run.sb");
+      writeFileSync3(profile, macosRunProfile(this.writable, this.options.hidden ?? []), { mode: 384 });
+      const prefix = [sandboxExec, "-f", profile];
+      if (probeRun([...prefix, "/bin/sh", "-c", "true"], this.env, this.cwd)) {
+        this.kind = "sandbox-exec";
+        this.prefix = prefix;
+        return this;
+      }
+    }
+    const bwrap = which("bwrap");
+    if (bwrap) {
+      const hide = (this.options.hidden ?? []).flatMap((target) => lstatSync2(target).isDirectory() ? ["--tmpfs", target] : ["--ro-bind", "/dev/null", target]);
+      const prefix = [
+        bwrap,
+        "--die-with-parent",
+        "--new-session",
+        "--unshare-all",
+        "--ro-bind",
+        "/",
+        "/",
+        "--dev",
+        "/dev",
+        "--proc",
+        "/proc",
+        "--tmpfs",
+        "/tmp",
+        ...hide,
+        ...this.writable.flatMap((dir) => ["--bind", dir, dir]),
+        "--chdir",
+        this.cwd,
+        "--"
+      ];
+      if (probeRun([...prefix, "/bin/sh", "-c", "true"], this.env, this.cwd)) {
+        this.kind = "bwrap";
+        this.prefix = prefix;
+      }
+    }
+    return this;
+  }
+  async run(command, timeoutSeconds) {
+    if (this.kind === "none" && !this.options.allowUnsandboxed) {
+      throw new ValidationError(
+        "run is unavailable: this host has no OS sandbox (sandbox-exec or bwrap) to confine it, and the operator has not set FREELLAMA_CODER_UNSANDBOXED_RUN=1. Finish and say the change is untested."
+      );
+    }
+    const started = performance.now();
+    const capture = new OutputCapture();
+    const argv = [...this.prefix, "/bin/sh", "-c", command];
+    const outcome = await new Promise((resolve, reject) => {
+      const child = spawn2(argv[0], argv.slice(1), { cwd: this.cwd, env: this.env, stdio: ["ignore", "pipe", "pipe"] });
+      let timedOut = false;
+      let grace;
+      const settle = (code, signal) => {
+        clearTimeout(timer);
+        clearTimeout(grace);
+        resolve({ code, signal, timedOut });
+      };
+      const release = (code, signal) => {
+        grace = setTimeout(() => {
+          child.stdout.destroy();
+          child.stderr.destroy();
+          settle(code, signal);
+        }, 2e3);
+      };
+      const timer = setTimeout(() => {
+        timedOut = true;
+        if (child.pid !== void 0) killTree(child.pid);
+        release(null, "SIGKILL");
+      }, Math.max(timeoutSeconds, 1e-3) * 1e3);
+      child.stdout.on("data", (chunk) => capture.push(chunk));
+      child.stderr.on("data", (chunk) => capture.push(chunk));
+      child.once("error", (error) => {
+        clearTimeout(timer);
+        clearTimeout(grace);
+        reject(error);
+      });
+      child.once("exit", (code, signal) => {
+        if (grace === void 0) release(code, signal);
+      });
+      child.once("close", (code, signal) => settle(code, signal));
+    });
+    const { text, gap } = capture.text();
+    return {
+      command,
+      exitCode: outcome.code,
+      signal: outcome.signal,
+      timedOut: outcome.timedOut,
+      durationMs: Math.round(performance.now() - started),
+      observed: headTail(text, OBSERVATION_LINES, gap),
+      kept: headTail(text, RESULT_LINES, gap)
+    };
+  }
+};
+function probeRun(argv, env, cwd) {
+  const result = spawnSync2(argv[0], argv.slice(1), { cwd, env, stdio: ["ignore", "pipe", "pipe"], timeout: 1e4, killSignal: "SIGKILL" });
+  return !result.error && result.status === 0;
+}
+function describeRun(outcome) {
+  const seconds2 = (outcome.durationMs / 1e3).toFixed(1);
+  const ended = outcome.timedOut ? `timed out after ${seconds2} s and was killed` : outcome.exitCode !== null ? `exit code ${outcome.exitCode} (${seconds2} s)` : `killed by ${outcome.signal ?? "a signal"} (${seconds2} s)`;
+  return `$ ${outcome.command}
+${ended}
+${outcome.observed.trim() ? outcome.observed : "(no output)"}`;
+}
+function runEnvironment(source, tmp) {
+  const env = {};
+  for (const key of [
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "CARGO_HOME",
+    "RUSTUP_HOME",
+    "COREPACK_HOME",
+    "XDG_CACHE_HOME",
+    "npm_config_cache"
+  ]) {
+    if (source[key] !== void 0) env[key] = source[key];
+  }
+  return {
+    ...env,
+    PATH: env.PATH ?? "/usr/bin:/bin",
+    TMPDIR: tmp,
+    TMP: tmp,
+    TEMP: tmp,
+    CI: "1",
+    NO_COLOR: "1",
+    FORCE_COLOR: "0",
+    TERM: "dumb",
+    // The sandbox has no network: let cargo use its cache instead of failing on a registry update.
+    CARGO_NET_OFFLINE: "true",
+    GIT_TERMINAL_PROMPT: "0"
+  };
+}
+
+// src/research/isolated-copy.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
+import {
+  cpSync,
+  existsSync as existsSync7,
+  lstatSync as lstatSync3,
+  mkdirSync as mkdirSync5,
+  mkdtempSync as mkdtempSync3,
+  readFileSync as readFileSync8,
+  readdirSync as readdirSync4,
+  realpathSync as realpathSync4,
+  rmSync as rmSync3,
+  symlinkSync as symlinkSync2,
+  writeFileSync as writeFileSync4
+} from "node:fs";
+import { tmpdir as tmpdir3 } from "node:os";
+import path9 from "node:path";
+var WORKTREE_NAME = "freellama-coder";
+var COPY_SKIPPED = ["node_modules", "target", "dist", ".git"];
+var DEFAULT_MAX_COPY_BYTES = 200 * 1024 * 1024;
+var LINK_SKIPPED_DOT = /* @__PURE__ */ new Set([".bin", ".pnpm"]);
+var LINK_MAX_DEPTH = 4;
+var LINK_MAX_DIRS = 32;
+var GIT_MAX_BUFFER = 512 * 1024 * 1024;
+var GIT_FLAGS = ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false"];
+function baseGitEnv() {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== void 0 && !key.startsWith("GIT_")) env[key] = value;
+  }
+  return { ...env, GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" };
+}
+function git(args, cwd, env = baseGitEnv(), input) {
+  const result = spawnSync3("git", [...GIT_FLAGS, ...args], { cwd, env, input, maxBuffer: GIT_MAX_BUFFER, stdio: ["pipe", "pipe", "pipe"] });
+  if (result.error) throw new ValidationError(`git ${args[0]} could not run: ${result.error.message}`);
+  return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr.toString("utf8").trim() };
+}
+function gitOk(args, cwd, env, input) {
+  const result = git(args, cwd, env, input);
+  if (result.status !== 0) throw new ValidationError(`git ${args.join(" ")} failed: ${result.stderr || `exit ${result.status}`}`);
+  return result.stdout;
+}
+var line = (bytes) => bytes.toString("utf8").trim();
+function repositoryTop(dir) {
+  const top = git(["rev-parse", "--show-toplevel"], dir);
+  if (top.status !== 0) return null;
+  if (git(["rev-parse", "--verify", "--quiet", "HEAD"], dir).status !== 0) return null;
+  return realpathSync4(line(top.stdout));
+}
+function commonDirOf(top) {
+  const raw = line(gitOk(["rev-parse", "--git-common-dir"], top));
+  return realpathSync4(path9.resolve(top, raw));
+}
+function treeBytes(dir, limit) {
+  let total = 0;
+  const walk = (current) => {
+    for (const entry of readdirSync4(current, { withFileTypes: true })) {
+      if (COPY_SKIPPED.includes(entry.name)) continue;
+      const absolute = path9.join(current, entry.name);
+      if (entry.isDirectory()) walk(absolute);
+      else if (entry.isFile()) {
+        total += lstatSync3(absolute).size;
+        if (total > limit) {
+          throw new ValidationError(
+            `the workspace is larger than the ${limit >= 1024 * 1024 ? `${Math.round(limit / 1024 / 1024)} MB` : `${limit}-byte`} copy limit (node_modules, target, dist and .git excluded); point workspacePath at a smaller directory, or make it a git repository so a worktree is used instead`
+          );
+        }
+      }
+    }
+  };
+  walk(dir);
+  return total;
+}
+function linkDependencies(sourceTop, copyTop) {
+  const linked = [];
+  const walk = (rel, depth) => {
+    if (depth > LINK_MAX_DEPTH || linked.length >= LINK_MAX_DIRS) return;
+    let entries;
+    try {
+      entries = readdirSync4(path9.join(sourceTop, rel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const child = rel ? path9.join(rel, entry.name) : entry.name;
+      if (entry.name === "node_modules") {
+        const target = path9.join(copyTop, child);
+        if (existsSync7(target) || !existsSync7(path9.join(copyTop, rel))) continue;
+        mkdirSync5(target);
+        for (const item of readdirSync4(path9.join(sourceTop, child), { withFileTypes: true })) {
+          if (item.name.startsWith(".") && item.isDirectory() && !LINK_SKIPPED_DOT.has(item.name)) continue;
+          symlinkSync2(path9.join(sourceTop, child, item.name), path9.join(target, item.name));
+        }
+        linked.push(child);
+        if (linked.length >= LINK_MAX_DIRS) return;
+        continue;
+      }
+      if (entry.name.startsWith(".") || COPY_SKIPPED.includes(entry.name)) continue;
+      walk(child, depth + 1);
+    }
+  };
+  walk("", 0);
+  return linked;
+}
+function newCopyContainer() {
+  return realpathSync4(mkdtempSync3(path9.join(tmpdir3(), "freellama-coder-")));
+}
+function createIsolatedCopy(workspace, container, options = {}) {
+  const source = realpathSync4(workspace);
+  mkdirSync5(container, { recursive: true });
+  const box = realpathSync4(container);
+  if (readdirSync4(box).length > 0) throw new ValidationError(`copy directory ${box} is not empty`);
+  const tmp = path9.join(box, "tmp");
+  const privateDir = path9.join(box, "private");
+  mkdirSync5(tmp);
+  mkdirSync5(privateDir, { mode: 448 });
+  try {
+    const top = repositoryTop(source);
+    const copy = top ? worktreeCopy(source, top, box) : plainCopy(source, box, options.maxCopyBytes ?? DEFAULT_MAX_COPY_BYTES);
+    const linked = options.linkDependencies === false ? [] : linkDependencies(top ?? source, copy.top);
+    return { ...copy, container: box, tmp, privateDir, linked };
+  } catch (error) {
+    removeIsolatedCopy(source, box);
+    throw error;
+  }
+}
+function worktreeCopy(source, repoTop, box) {
+  const work = path9.join(box, WORKTREE_NAME);
+  gitOk(["worktree", "add", "--detach", "--quiet", work, "HEAD"], repoTop);
+  const top = realpathSync4(work);
+  const gitDir = realpathSync4(line(gitOk(["rev-parse", "--absolute-git-dir"], top)));
+  const gitEnv = { ...baseGitEnv(), GIT_DIR: gitDir, GIT_WORK_TREE: top };
+  const head = line(gitOk(["rev-parse", "HEAD"], top, gitEnv));
+  const changes = gitOk([
+    "diff",
+    "HEAD",
+    "--binary",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--ignore-submodules=all",
+    "--src-prefix=a/",
+    "--dst-prefix=b/"
+  ], repoTop);
+  if (changes.length > 0) {
+    const applied = git(["apply", "--index", "--whitespace=nowarn", "-"], top, gitEnv, changes);
+    if (applied.status !== 0) {
+      throw new ValidationError(`could not reproduce your uncommitted changes in the isolated copy (${applied.stderr}); commit or stash them and retry`);
+    }
+  }
+  const baseTree = line(gitOk(["write-tree"], top, gitEnv));
+  const relative = path9.relative(repoTop, source);
+  if (relative && !existsSync7(path9.join(top, relative))) {
+    throw new ValidationError(`${relative} holds no file tracked at HEAD, so a worktree of the repository has no copy of it; commit its files, or point workspacePath at a tracked directory`);
+  }
+  return {
+    kind: "git_worktree",
+    top,
+    root: relative ? path9.join(top, relative) : top,
+    relative,
+    gitEnv,
+    commonDir: commonDirOf(repoTop),
+    baseTree,
+    head,
+    callerChanges: changes.length > 0
+  };
+}
+function plainCopy(source, box, maxCopyBytes) {
+  treeBytes(source, maxCopyBytes);
+  const top = path9.join(box, "copy");
+  cpSync(source, top, {
+    recursive: true,
+    verbatimSymlinks: true,
+    filter: (from) => from === source || !COPY_SKIPPED.includes(path9.basename(from))
+  });
+  const gitDir = path9.join(box, "private", "git");
+  const gitEnv = { ...baseGitEnv(), GIT_DIR: gitDir, GIT_WORK_TREE: top, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null" };
+  gitOk(["-c", "init.templateDir=", "init", "--quiet"], top, gitEnv);
+  mkdirSync5(path9.join(gitDir, "info"), { recursive: true });
+  writeFileSync4(path9.join(gitDir, "info", "exclude"), COPY_SKIPPED.map((name) => `${name}/`).join("\n") + "\n");
+  gitOk(["-c", "core.autocrlf=false", "add", "-A", "."], top, gitEnv);
+  const baseTree = line(gitOk(["write-tree"], top, gitEnv));
+  return { kind: "copy", top, root: top, relative: "", gitEnv, commonDir: null, baseTree, head: null, callerChanges: false };
+}
+var STATUS = { M: "modified", A: "added", D: "deleted", T: "type_changed" };
+function agentChanges(copy) {
+  const scope = copy.relative ? [`--relative=${copy.relative}`] : [];
+  const excluded = copy.linked.filter((rel) => git(["check-ignore", "-q", "--", rel], copy.top, copy.gitEnv).status !== 0).map((rel) => `:(exclude)${rel}`);
+  gitOk(["-c", "core.autocrlf=false", "add", "-A", "--", copy.relative || ".", ...excluded], copy.top, copy.gitEnv);
+  const common = ["diff", "--cached", "--no-renames", "--no-color", "--no-ext-diff", "--no-textconv", ...scope];
+  const patch = gitOk([...common, "--binary", "--src-prefix=a/", "--dst-prefix=b/", copy.baseTree], copy.top, copy.gitEnv);
+  const names = gitOk([...common, "--name-status", "-z", copy.baseTree], copy.top, copy.gitEnv).toString("utf8").split("\0");
+  const files = [];
+  for (let index = 0; index + 1 < names.length; index += 2) {
+    files.push({ path: names[index + 1], status: STATUS[names[index].charAt(0)] ?? "modified" });
+  }
+  return { patch, files };
+}
+function removeIsolatedCopy(workspace, container) {
+  const work = path9.join(container, WORKTREE_NAME);
+  let commonDir = null;
+  try {
+    const top = repositoryTop(realpathSync4(workspace));
+    commonDir = top ? commonDirOf(top) : null;
+    if (top && existsSync7(work)) git(["worktree", "remove", "--force", work], top);
+  } catch {
+  }
+  try {
+    rmSync3(container, { recursive: true, force: true });
+  } catch {
+  }
+  if (!commonDir) return;
+  const entries = path9.join(commonDir, "worktrees");
+  let names;
+  try {
+    names = readdirSync4(entries);
+  } catch {
+    return;
+  }
+  const ours = /* @__PURE__ */ new Set([path9.join(work, ".git"), path9.join(container, WORKTREE_NAME, ".git")]);
+  for (const name of names) {
+    try {
+      if (ours.has(readFileSync8(path9.join(entries, name, "gitdir"), "utf8").trim())) {
+        rmSync3(path9.join(entries, name), { recursive: true, force: true });
+      }
+    } catch {
+    }
+  }
+}
+
+// ../rust-core/src/model_catalog.json
+var model_catalog_default = {
+  snapshot: "2026-11-01",
+  measured_on: "Apple M2 Pro, 32 GB, Ollama 0.40.13, with other work running",
+  how_to_read: "quality is measured (run here with known answers), published (the publisher's figure), or untested. memory_gb is what FreeLlama asks to have available, including its reserve; null means not previewed. Discovery never authorizes a pull: ask for one exact tag and its size first.",
+  jobs: [
+    { job: "classify", title: "Classify, triage, yes/no", call: 'run_task {task:"decision"}', cookbook: "cookbooks/classify", picks: [
+      { tag: "strands-decider:2b-nvfp4", role: "default", file_gb: 1.3, memory_gb: 3.8, quality: "measured", evidence: "53/56 in all 3 rounds, 7 ms median; published 182/231 JevBench" },
+      { tag: "nimble-v3:9b-q4_K_M", role: "alternative", file_gb: 5.6, memory_gb: 11.5, quality: "measured", evidence: "51/56 in all 3 rounds, 1.5 s median: no better here despite published 198/231 JevBench" }
+    ] },
+    { job: "find-code", title: "Find the code for an issue", call: 'run_task {task:"embedding", nearest:{query}}', cookbook: "cookbooks/find-code", picks: [
+      { tag: "embeddinggemma-2:740m-q8_0", role: "default", file_gb: 1.3, memory_gb: 1.4, quality: "measured", evidence: "right file first 9/10, top 3 9/10; 899 chunks indexed in 67 s" },
+      { tag: "nomic-embed-text:v1.5", role: "alternative", file_gb: 0.3, memory_gb: 1.4, quality: "measured", evidence: "right file first 6/10, top 3 8/10; faster, 881 chunks in 42 s" }
+    ] },
+    { job: "duplicates", title: "Find duplicates", call: 'run_task {task:"embedding", nearest:{}}', cookbook: "cookbooks/duplicates", picks: [
+      { tag: "nomic-embed-text:v1.5", role: "default", file_gb: 0.3, memory_gb: 1.4, quality: "measured", evidence: "8/12 real issue pairs" }
+    ] },
+    { job: "ocr", title: "Read text from an image", call: 'run_task {task:"vision", files:[path]}', cookbook: "cookbooks/ocr", picks: [
+      { tag: "hf.co/openbmb/MiniCPM-OCR-1.0-gguf:Q4_K_M", role: "default", file_gb: 1.4, memory_gb: 3.8, quality: "measured", evidence: "30/30 in all 3 rounds, 257 ms median, clean rendered text" },
+      { tag: "glm-ocr:latest", role: "alternative", file_gb: 2.2, memory_gb: 5.8, quality: "measured", evidence: "30/30 in all 3 rounds, 1,885 ms median" }
+    ] },
+    { job: "image-recognition", title: "Understand what an image shows", call: 'run_task {task:"vision", files:[path], prompt}', cookbook: "cookbooks/image-recognition", picks: [
+      { tag: "lfm3-vl:2b-q4_K_M", role: "default", file_gb: 1.5, memory_gb: 4.1, quality: "measured", evidence: "20/20 drawn images in all 3 rounds, 299 ms median" },
+      { tag: "lfm3-omni:2b-q4_K_M", role: "alternative", file_gb: 2, memory_gb: 5.5, quality: "measured", evidence: "18/20 in all 3 rounds, 269 ms median; also does audio" },
+      { tag: "bonsai-2:9b", role: "alternative", file_gb: 3.2, memory_gb: 10.3, quality: "measured", evidence: "17/20 in all 3 rounds, 1.4 s median" }
+    ] },
+    { job: "image-search", title: "Find an image by describing it", call: 'run_task {task:"embedding", files:[images], nearest:{query}}', cookbook: "cookbooks/image-search", picks: [
+      { tag: "embeddinggemma-2:740m-q8_0", role: "default", file_gb: 1.3, memory_gb: 1.4, quality: "measured", evidence: "5/5 on five drawn screens" }
+    ] },
+    { job: "speech-to-text", title: "Recording to text", call: 'audio {action:"transcribe", file}', cookbook: "cookbooks/speech-to-text", picks: [
+      { tag: "lfm3-audio:2b-q4_K_M", role: "default", file_gb: 1.7, memory_gb: 5.5, quality: "measured", evidence: "1.7% word error on generated speech, 276 ms median, translation worked" },
+      { tag: "lfm3-omni:2b-q4_K_M", role: "alternative", file_gb: 2, memory_gb: 5.5, quality: "measured", evidence: "1.7% word error, 280 ms median, translation worked, also does images" }
+    ] },
+    { job: "text-to-speech", title: "Text to speech", call: 'audio {action:"speak", text}', cookbook: "cookbooks/text-to-speech", picks: [
+      { tag: "phonon:en", role: "default", file_gb: 0.1, memory_gb: null, quality: "measured", evidence: "0.8-1.7% word error when transcribed back, 102 ms median: about 9x faster" },
+      { tag: "lfm3-audio:2b-q4_K_M", role: "alternative", file_gb: 1.7, memory_gb: 5.5, quality: "measured", evidence: "0% word error, 950 ms median; the judge is an LFM3 model and may favour it" },
+      { tag: "lfm3-omni:2b-q4_K_M", role: "alternative", file_gb: 2, memory_gb: 5.5, quality: "measured", evidence: "0% word error, 950 ms median; same judge caveat" }
+    ] },
+    { job: "coding", title: "Small coding tasks", call: 'run_task {task:"coding", files:[path]}', cookbook: "cookbooks/coding", picks: [
+      { tag: "lfm3:1.7b-q4_K_M", role: "default", file_gb: 1.1, memory_gb: 3.3, quality: "measured", evidence: "21, 20, 20 of 25 small questions, 579 ms median" },
+      { tag: "hf.co/nvidia/NVIDIA-Nemotron-3.5-Bolt-E4B-4GB:Q4_K_M", role: "stronger", file_gb: 6.2, memory_gb: 13.5, quality: "measured", evidence: "23, 22, 23 of 25, 267 ms median" },
+      { tag: "bonsai-2:9b", role: "alternative", file_gb: 3.2, memory_gb: 10.3, quality: "measured", evidence: "19, 19, 17 of 25, 475 ms median" },
+      { tag: "bonsai-2:27b", role: "stronger", file_gb: 8.3, memory_gb: 16.3, quality: "published", evidence: "publisher: SWE-bench Verified 60.8%, LiveCodeBench 90.1%; not measured here, never had 16.3 GB available" }
+    ] },
+    { job: "research-agent", title: "Research a repository", call: 'delegate_research {adapter:"octocode" or "github"}', cookbook: "cookbooks/research-agent", picks: [
+      { tag: "bonsai-2:9b", role: "default", file_gb: 3.2, memory_gb: 10.3, quality: "measured", evidence: "4, 5, 5 of 8 local and 3, 5, 5 of 6 GitHub over 3 rounds, 82 s median per question" },
+      { tag: "hf.co/nvidia/NVIDIA-Nemotron-3.5-Bolt-E4B-4GB:Q4_K_M", role: "stronger", file_gb: 6.2, memory_gb: 13.5, quality: "measured", evidence: "6/8 local and 5/6 GitHub in all 3 rounds, 96 s median per question" },
+      { tag: "lfm3:1.7b-q4_K_M", role: "small", file_gb: 1.1, memory_gb: 3.3, quality: "measured", evidence: "6, 5, 5 of 8 local but 1/6 GitHub, 20 s median per question" }
+    ] }
+  ]
+};
+
+// src/local-prompts.ts
+var catalog = model_catalog_default;
+function picksOf(job) {
+  return catalog.jobs.find((entry) => entry.job === job)?.picks.map((pick) => pick.tag) ?? [];
+}
+var cookbook = (name) => `docs/cookbooks/${name}.md`;
+var SOURCES = {
+  miniCpmOcr: ["https://huggingface.co/openbmb/MiniCPM-OCR-1.0", "https://huggingface.co/openbmb/MiniCPM-OCR-1.0-gguf"],
+  glmOcr: ["https://ollama.com/library/glm-ocr", "https://huggingface.co/zai-org/GLM-OCR"],
+  lfm3Vl: ["https://huggingface.co/LiquidAI/LFM3-VL-2B", "https://huggingface.co/LiquidAI/LFM3-VL-2B-GGUF", "https://ollama.com/library/lfm3-vl"],
+  lfm3Omni: ["https://huggingface.co/LiquidAI/LFM3-Omni-2B", "https://ollama.com/library/lfm3-omni"],
+  embeddingGemma: ["https://huggingface.co/google/embeddinggemma-2", "https://ai.google.dev/gemma/docs/embeddinggemma/inference-embeddinggemma-with-sentence-transformers"],
+  nomic: ["https://huggingface.co/nomic-ai/nomic-embed-text-v1.5"],
+  strandsDecider: ["https://ollama.com/library/strands-decider", "https://raw.githubusercontent.com/strands-labs/strands-decider/main/README.md"],
+  nimble: ["https://ollama.com/library/nimble-v3:latest"],
+  bonsai9b: ["https://huggingface.co/prism-ml/Ternary-Bonsai-2-9B-gguf", "https://ollama.com/library/bonsai-2:9b"],
+  bonsai27b: ["https://huggingface.co/prism-ml/Ternary-Bonsai-2-27B-gguf", "https://ollama.com/library/bonsai-2"],
+  lfm3: ["https://huggingface.co/LiquidAI/LFM3-1.7B", "https://ollama.com/library/lfm3"],
+  nemotronBolt: ["https://huggingface.co/nvidia/NVIDIA-Nemotron-3.5-Bolt-E4B-4GB"],
+  lfm3Audio: ["https://huggingface.co/LiquidAI/LFM3-Audio-2B", "https://ollama.com/library/lfm3-audio"],
+  qwen38: ["https://huggingface.co/Qwen/Qwen3.8-27B", "https://ollama.com/library/qwen3.8"],
+  qwen35: ["https://huggingface.co/Qwen/Qwen3.5-4B", "https://ollama.com/library/qwen3.5"],
+  phonon: ["https://ollama.com/library/phonon:en"]
+};
+var EMBEDDING_PREFIXES = {
+  embeddinggemma: {
+    query: "task: search result | query: ",
+    document: "title: none | text: ",
+    codeQuery: "task: code retrieval | query: ",
+    similarity: "task: sentence similarity | query: ",
+    clustering: "task: clustering | query: ",
+    classification: "task: classification | query: "
+  },
+  // A prefix is required; the card names clustering: for removing semantic duplicates.
+  "nomic-embed-text": { query: "search_query: ", document: "search_document: ", clustering: "clustering: ", classification: "classification: " }
+};
+var GEMMA = EMBEDDING_PREFIXES.embeddinggemma;
+var NOMIC = EMBEDDING_PREFIXES["nomic-embed-text"];
+var OCR_PROMPTS = { text: "Text Recognition:", table: "Table Recognition:", formula: "Formula Recognition:" };
+var OCR_TRAINED = ["minicpm-ocr", "glm-ocr"];
+var OCR_PLAIN = {
+  text: "Transcribe all text in the image exactly, line by line. Output only the text.",
+  table: "Transcribe the table in the image as a Markdown table. Output only the table."
+};
+var ocrPrompt = (kind, model) => {
+  const name = (model ?? "").toLowerCase().replace(/^(?:hf\.co|huggingface\.co)\/[^/]+\//, "");
+  return model === void 0 || OCR_TRAINED.some((family) => name.startsWith(family)) ? OCR_PROMPTS[kind] : OCR_PLAIN[kind];
+};
+var EDIT_FORMAT = `Return each change to an existing file as the file's path (copied from its "--- file:" line), then:
+<<<<<<< SEARCH
+exact current lines (5 to 30, unique in the file, indentation exact)
+=======
+replacement lines
+>>>>>>> REPLACE
+Copy SEARCH lines character for character; prefer several small blocks to one large one. For a new file, or one under 30 lines, give its path on one line and the whole file in one fenced block. If the file was not shown, give the code in one fenced block and say which file and function it belongs in.`;
+var NO_TOOLS = "You have no tools and cannot open files: everything you need is in this message. Answer in plain text.";
+var WORKFLOWS = {
+  "read-text": {
+    job: "ocr",
+    title: "Read all text in an image, exactly",
+    input: "files: the images",
+    prompt: (_request, model) => ocrPrompt("text", model)
+  },
+  "read-table": {
+    job: "ocr",
+    title: "Read a table in an image as Markdown",
+    input: "files: the images",
+    prompt: (_request, model) => ocrPrompt("table", model)
+  },
+  "read-fields": {
+    job: "ocr",
+    title: "Pull named fields from a receipt, invoice or form image as JSON",
+    input: "files: the images; prompt: the field names",
+    prompt: (request) => `Extract these fields from the image: ${request ?? "all labelled fields"}. Format the output as a JSON object with these keys, values exactly as printed; use "###" for a field the image does not show.`
+  },
+  "answer-image": {
+    job: "image-recognition",
+    title: "Answer a question about an image",
+    input: "files: the images; prompt: the question",
+    system: `Answer the question about the image.
+1. Find the part of the image the question is about.
+2. Read any text there exactly as printed.
+3. Answer with just the value or label, or one or two sentences.
+If the image does not show it, answer "not visible". Never guess at what is cut off.`
+  },
+  "describe-screen": {
+    job: "image-recognition",
+    title: "Describe a screenshot for a developer: text, errors, state",
+    input: "files: the screenshot; prompt: what to look for (optional)",
+    system: `You describe a software screenshot for a developer, in short bullets, in this order:
+- the app or page shown;
+- headings and main text, quoted exactly;
+- any error, warning or empty state, quoted exactly;
+- the state of the controls that matter (selected, disabled, filled in);
+- anything that looks broken or misaligned.
+Describe only what is visible.`
+  },
+  "change-code": {
+    job: "coding",
+    title: "Make one small code change",
+    input: "files: the file to change; prompt: the change",
+    system: `${NO_TOOLS}
+You make one small code change.
+1. Find where the change belongs in the code shown.
+2. Follow the file's existing names, style and error handling.
+3. Change as few lines as the task needs; touch nothing else.
+${EDIT_FORMAT}
+Explain nothing unless asked. If the task is a question, answer it in a few lines.`
+  },
+  "fix-bug": {
+    prefer: "capable",
+    job: "coding",
+    title: "Fix a bug with the smallest change",
+    input: "files: the suspect code; prompt: the error message or symptom",
+    system: `${NO_TOOLS}
+You fix one bug with the smallest change.
+1. Read the error or symptom, then the code shown.
+2. Name the cause in one sentence, quoting the line that causes it.
+3. Change only what the fix needs.
+Answer with the cause line, then the edits.
+${EDIT_FORMAT}
+If the code shown cannot cause the symptom, say so and name the file or function to look at instead.`
+  },
+  implement: {
+    prefer: "capable",
+    job: "coding",
+    title: "Add a small feature to existing code",
+    input: "files: the code; prompt: the feature",
+    system: `${NO_TOOLS}
+You add one small feature to the code shown.
+1. Find the function or place it belongs; reuse helpers the file already has.
+2. Follow the file's names, style and error handling.
+3. Handle the empty and error cases the feature can meet.
+${EDIT_FORMAT}
+End with one line: what to test.`
+  },
+  "write-tests": {
+    prefer: "capable",
+    job: "coding",
+    title: "Write unit tests for the code shown",
+    input: "files: the code (and an existing test, for style); prompt: what to cover (optional)",
+    system: `${NO_TOOLS}
+You write unit tests for the code shown; you never change that code.
+1. List the behaviours: the normal case, edge cases (empty, zero, missing, boundary) and one failure case.
+2. Use the test framework and import style the project already uses; copy them from the files shown.
+3. Write one small test per behaviour, named after it, with literal expected values.
+Answer with the test file's path on one line, then the whole file in one fenced block.`
+  },
+  "review-code": {
+    prefer: "capable",
+    job: "coding",
+    title: "Find real defects in code (not style)",
+    input: "files: the code; prompt: what to focus on (optional)",
+    system: `${NO_TOOLS}
+You review the code shown for real defects only: wrong logic, unhandled errors, off-by-one, null or undefined access, leaks, injection, races. Ignore style and naming.
+For each defect write one line: path:line - the problem - the fix.
+Report at most 5, the surest first. If you find none, answer "no defects found". Never invent a line you did not see.`
+  },
+  "explain-code": {
+    job: "coding",
+    title: "Explain code to someone about to change it",
+    input: "files: the code; prompt: what to explain (optional)",
+    system: `${NO_TOOLS}
+Explain the code shown to a developer who is about to change it, in at most 6 bullets:
+what it does (one sentence); its inputs and outputs; side effects (files, network, shared state); what calls it, if visible; the one thing most likely to break when it changes.
+Name functions and variables exactly.`
+  },
+  "summarize-log": {
+    think: false,
+    prefer: "capable",
+    job: "summarize",
+    title: "Summarize a log: errors grouped, counted, first failure",
+    input: "files: the log; prompt: what you are investigating (optional)",
+    system: `${NO_TOOLS}
+You read a log for a developer. Report:
+1. Errors and warnings, grouped by message, each with its count and first and last timestamp.
+2. The first error in time order, quoted exactly.
+3. The likely cause, only if the log shows it.
+Quote messages exactly, skip routine lines, at most 10 bullets.`
+  },
+  "summarize-text": {
+    think: false,
+    job: "summarize",
+    title: "Summarize text for someone who will act on it",
+    input: "files: the text; prompt: what you need from it (optional)",
+    system: `${NO_TOOLS}
+Summarize the text for someone who will act on it, in short bullets: the decisions, the numbers, the deadlines and the open questions, plus whatever the request asks for.
+Quote numbers, names, versions and paths exactly. Write "not stated" when the text does not say; never guess. No introduction or closing.`
+  },
+  "summarize-diff": {
+    think: false,
+    prefer: "capable",
+    job: "summarize",
+    title: "Summarize a diff for a reviewer: changes and risks",
+    input: "files: the diff or patch",
+    system: `${NO_TOOLS}
+You summarize a code diff for a reviewer, in at most 8 bullets:
+one line per file on what changed; any change in behaviour; risks such as a removed check, a changed default, a new dependency or a missing test.
+Name files, functions and settings exactly.`
+  },
+  "extract-json": {
+    think: false,
+    job: "summarize",
+    title: "Extract named fields from text into JSON",
+    input: "files: the text; prompt: the field names (or a JSON schema)",
+    system: `${NO_TOOLS}
+Extract the fields the request names from the text into one JSON object.
+Use the values exactly as written in the text; use null for a field the text does not give; never invent a value.
+Output only the JSON object.`,
+    format: "json"
+  }
+};
+var WORKFLOW_NAMES = Object.keys(WORKFLOWS);
+var BONSAI_9B = {
+  think: false,
+  options: { temperature: 0.7, top_p: 0.8, top_k: 20, min_p: 0, presence_penalty: 1.5, repeat_penalty: 1 },
+  notes: "With think:true use the card's thinking preset (temperature 1.0, top_p 0.95, presence_penalty 1.0) and allow at least 8,192 output tokens; never greedy decoding with thinking on.",
+  sources: SOURCES.bonsai9b
+};
+var qwenNonThinking = (sources) => ({
+  think: false,
+  options: { temperature: 0.7, top_p: 0.8, top_k: 20, min_p: 0, presence_penalty: 1.5, repeat_penalty: 1 },
+  notes: "Thinks by default; with think:true use the card's thinking preset (temperature 1.0, top_p 0.95, top_k 20; Qwen3.8 presence_penalty 0, Qwen3.5 1.5, or 0 with temperature 0.6 for precise coding) and a large output budget (Qwen3.5 32,768 tokens). Raise presence_penalty (up to 2) if it repeats.",
+  sources
+});
+var CHAT_MODELS = {
+  lfm3: {
+    options: { temperature: 0.1, top_k: 50, repeat_penalty: 1.1 },
+    notes: "Thinks by default; its card calls thinking off inconsistent, so it stays on. Not for agentic coding or multi-step reasoning.",
+    sources: SOURCES.lfm3
+  },
+  "nvidia-nemotron-3.5-bolt": {
+    options: { temperature: 1, top_p: 0.95 },
+    // `ollama show` of the hf.co Q4_K_M tag, 2026-11-08: no thinking capability, and the template
+    // defaults enable_thinking to false.
+    notes: "The card says it reasons by default, but its GGUF template turns thinking off and Ollama reports no thinking capability, so it answers directly; think:true is refused.",
+    sources: SOURCES.nemotronBolt
+  },
+  "bonsai-2": BONSAI_9B,
+  // The card documents the same instruct (non-thinking) preset as the 9B; Ollama lists think
+  // values false, low, medium and xhigh for this tag.
+  "bonsai-2:27b": {
+    ...BONSAI_9B,
+    notes: "With think:true (or low, medium, xhigh) use the card's thinking preset (temperature 1.0, top_p 0.95, top_k 20, min_p 0.05, presence_penalty 0) and allow about 16,384 output tokens.",
+    sources: SOURCES.bonsai27b
+  },
+  "qwen3.8": qwenNonThinking(SOURCES.qwen38),
+  "qwen3.5": qwenNonThinking(SOURCES.qwen35)
+};
+var CHAT_SOURCES = [...SOURCES.lfm3, ...SOURCES.nemotronBolt, ...SOURCES.bonsai9b, ...SOURCES.bonsai27b, ...SOURCES.qwen38, ...SOURCES.qwen35];
+var LOCAL_JOBS = {
+  classify: {
+    job: "classify",
+    task: "decision",
+    catalogJob: "classify",
+    defaultPicks: picksOf("classify"),
+    models: {
+      "strands-decider": { notes: "State and questions together must fit 4,096 tokens; weak on long, multi-step documents. Its README: answers at confidence 0.9 or more are right about 95% of the time; confirm the rest.", sources: SOURCES.strandsDecider },
+      "nimble-v3": { notes: "Documents num_ctx 32768 (routing sizes it here); CC BY-NC 4.0, noncommercial.", sources: SOURCES.nimble }
+    },
+    notes: "A decision model reads state and questions, no prompt. Ask short questions about the state, one concern each, and give a choice question an explicit fallback option such as other.",
+    sources: [...SOURCES.strandsDecider, ...SOURCES.nimble, cookbook("classify")]
+  },
+  "find-code": {
+    job: "find-code",
+    task: "embedding",
+    catalogJob: "find-code",
+    defaultPicks: picksOf("find-code"),
+    needs: "nearest.query: the issue, or what the code does",
+    prefixes: { embeddinggemma: { query: GEMMA.codeQuery, document: GEMMA.document }, "nomic-embed-text": { query: NOMIC.query, document: NOMIC.document } },
+    // Measured 2026-11-08 on the find-code set (10 questions, 1,039 chunks): code retrieval with
+    // title: none 8 first / 9 in top 3; search result 8/8; code retrieval with the file as title 7/9.
+    notes: "task: code retrieval (EmbeddingGemma's code-search prefix) measured best here: right file first 8/10, in the top 3 9/10. Read the top ranges before relying on them.",
+    sources: [...SOURCES.embeddingGemma, ...SOURCES.nomic, cookbook("find-code")]
+  },
+  duplicates: {
+    job: "duplicates",
+    task: "embedding",
+    catalogJob: "duplicates",
+    defaultPicks: picksOf("duplicates"),
+    // Symmetric: every item, the query included, takes the same prefix.
+    prefixes: {
+      // The measured 8/12 used search_document:; the card's clustering: is documented but unmeasured here.
+      "nomic-embed-text": { query: NOMIC.document, document: NOMIC.document },
+      embeddinggemma: { query: GEMMA.similarity, document: GEMMA.similarity }
+    },
+    notes: "Uses the measured search_document: (8/12 real issue pairs); nomic's card also documents clustering: for deduplication, unmeasured here. A high score is a candidate, never a verdict.",
+    sources: [...SOURCES.nomic, ...SOURCES.embeddingGemma, cookbook("duplicates")]
+  },
+  ocr: {
+    job: "ocr",
+    task: "vision",
+    catalogJob: "ocr",
+    defaultPicks: picksOf("ocr"),
+    prompt: ({ model }) => ocrPrompt("text", model),
+    // Both publishers' Ollama Modelfiles set temperature 0; the hf.co MiniCPM tag ships no parameters.
+    models: {
+      "minicpm-ocr": {
+        options: { temperature: 0 },
+        notes: "Chinese and English; tables come back as HTML. Its Modelfile sets num_ctx 8192.",
+        sources: [...SOURCES.miniCpmOcr, "https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/docs/ollama_deploy.md"]
+      },
+      "glm-ocr": {
+        options: { temperature: 0 },
+        notes: "Also documents Figure Recognition:.",
+        sources: [...SOURCES.glmOcr, "https://github.com/zai-org/GLM-OCR/blob/main/examples/ollama-deploy/README.md"]
+      }
+    },
+    notes: "The OCR picks were trained on Text Recognition:, Table Recognition: and Formula Recognition:; a general vision model gets the same request in plain words. Crop to the text first.",
+    sources: [...SOURCES.miniCpmOcr, ...SOURCES.glmOcr, cookbook("ocr")]
+  },
+  "image-recognition": {
+    job: "image-recognition",
+    task: "vision",
+    catalogJob: "image-recognition",
+    defaultPicks: picksOf("image-recognition"),
+    needs: "prompt: your question about the image",
+    systemPrompt: WORKFLOWS["answer-image"].system,
+    models: {
+      "lfm3-vl": {
+        options: { temperature: 0.1, top_p: 1, top_k: 50, min_p: 0, repeat_penalty: 1.1 },
+        notes: "Thinks before it answers by default (Ollama lists think values true and false; off is unmeasured here); images go in at native resolution, so a large one costs many tokens.",
+        sources: SOURCES.lfm3Vl
+      },
+      "lfm3-omni": {
+        systemPrompt: "Answer questions about the provided image. Base every answer only on what can be seen.",
+        options: { temperature: 0 },
+        notes: "Non-reasoning: never send think:true. Up to 2,048 tokens per image. The card gives 32K context; the Ollama tag advertises 128K.",
+        sources: SOURCES.lfm3Omni
+      },
+      "bonsai-2": BONSAI_9B,
+      "qwen3.8": qwenNonThinking(SOURCES.qwen38),
+      "qwen3.5": qwenNonThinking(SOURCES.qwen35)
+    },
+    notes: 'Ask a specific question, not "describe this". Tested on drawn images only.',
+    sources: [...SOURCES.lfm3Vl, ...SOURCES.lfm3Omni, ...SOURCES.bonsai9b, cookbook("image-recognition")]
+  },
+  "image-search": {
+    job: "image-search",
+    task: "embedding",
+    catalogJob: "image-search",
+    defaultPicks: picksOf("image-search"),
+    needs: "nearest.query: a description of the image",
+    prefixes: { embeddinggemma: { query: GEMMA.query, document: GEMMA.document } },
+    notes: "Images are embedded bare: the prefixes apply to text only. Open the top match.",
+    sources: [...SOURCES.embeddingGemma, cookbook("image-search")]
+  },
+  coding: {
+    job: "coding",
+    task: "coding",
+    catalogJob: "coding",
+    defaultPicks: picksOf("coding"),
+    needs: "prompt: the change to make",
+    systemPrompt: WORKFLOWS["change-code"].system,
+    models: CHAT_MODELS,
+    notes: "The answer is SEARCH/REPLACE blocks: apply one only where its SEARCH text matches exactly once, then run the tests.",
+    sources: [...CHAT_SOURCES, cookbook("coding")]
+  },
+  summarize: {
+    job: "summarize",
+    task: "completion",
+    catalogJob: "coding",
+    defaultPicks: picksOf("coding"),
+    prompt: () => "Summarize the text below.",
+    systemPrompt: WORKFLOWS["summarize-text"].system,
+    models: CHAT_MODELS,
+    notes: "The coding picks: the same chat models apply (docs/cookbooks/batch-text.md). Check every number and name you reuse.",
+    sources: [...CHAT_SOURCES, cookbook("batch-text")]
+  }
+};
+var TOOL_JOBS = {
+  "speech-to-text": {
+    tool: "audio",
+    defaultPicks: picksOf("speech-to-text"),
+    // The audio tool calls Ollama's transcription endpoint, which builds the model's prompt; these
+    // are lfm3-audio's documented prompts for a direct chat call.
+    systemPrompts: {
+      transcribe: (language) => language ? `Perform ASR in ${language}.` : "Perform ASR.",
+      translate: (source, target) => `Translate the following speech from ${source} to ${target} in text form.`
+    },
+    notes: "WAV input only. Numbers and names are the usual misses; translation works best to or from English.",
+    sources: [...SOURCES.lfm3Audio, cookbook("speech-to-text")]
+  },
+  "text-to-speech": {
+    tool: "audio",
+    defaultPicks: picksOf("text-to-speech"),
+    notes: "Send plain text: Markdown marks may be read aloud. One voice (default); 24 kHz mono WAV.",
+    sources: [...SOURCES.phonon, cookbook("text-to-speech")]
+  },
+  "research-agent": {
+    tool: "delegate_research",
+    defaultPicks: picksOf("research-agent"),
+    notes: "The adapters' system prompts are below. Discard an escalate verdict and verify the citations.",
+    sources: [cookbook("research-agent")]
+  },
+  sweep: {
+    tool: "sweep",
+    defaultPicks: picksOf("classify"),
+    /** The decision state of one chunk, and the explain step's user message for a confirmed flag. */
+    state: (label, text) => `Source: ${label}
+
+${text}`,
+    explain: (prompt, label, text) => `${prompt}
+
+Source: ${label}
+
+${text}`,
+    // FreeLlama's own setting for the short explain note, not a model's documented value.
+    explainControls: { think: false, temperature: 0 },
+    notes: 'One yes/no question per concern, phrased about one chunk ("Does this code ..."); a noul answer flags at p >= 0.5.',
+    sources: [cookbook("sweep")]
+  }
+};
+var CODER_SYSTEM_PROMPT = [
+  "You change code in an isolated copy of the user's project (the current directory) and test the change. The user's own files are never touched: they review your diff afterwards. Reply with exactly one JSON object per turn and nothing else.",
+  "",
+  "Actions, in order of preference:",
+  '{"action":"search","pattern":"parsePort"} finds text in files and prints path:line:text. Literal and case-sensitive; add "regex":true, "ignoreCase":true, "glob":"*.ts" or "path":"src" to narrow it.',
+  '{"action":"read","path":"src/config.ts","start":40,"end":70} shows numbered lines of one file.',
+  '{"action":"edit","path":"src/config.ts","search":"  const port = 8080;\\n  return port;","replace":"  const port = Number(env.PORT ?? 8080);\\n  return port;"} replaces text that occurs exactly once in the file. Copy "search" from the read output without the line numbers and with its exact indentation: 5 to 30 lines, enough to be unique.',
+  '{"action":"write","path":"src/limits.ts","content":"export const MAX = 10;\\n"} creates a file, or replaces a whole small file.',
+  '{"action":"run","command":"yarn test"} runs one of the allowed commands listed with the task, exactly as written there, and shows its exit code and output.',
+  '{"action":"list","path":"src"} shows files and folders two levels deep.',
+  '{"action":"shell","command":"git diff --stat"} runs one read-only pipeline (rg, grep, find, head, sed -n, wc, git log/diff/show). It cannot change files; edit and write do.',
+  '{"action":"page","step":2,"page":2} shows the next page of a long earlier result.',
+  '{"action":"finish","answer":"Changed src/config.ts to read PORT from the environment, because the port was fixed. Test: yarn test passed."} ends the task.',
+  "",
+  "How to work:",
+  "1. Search for the names in the task, then read the lines you will change.",
+  "2. Edit with a search block copied exactly from the read output. If an edit fails, read those lines again and copy them; never guess.",
+  "3. Run an allowed command to test the change. If it fails, read the error, fix the code and run it again.",
+  "4. Finish with what changed, why, and the last test result. With no allowed command, say the change is untested.",
+  "Keep results small: read line ranges, not whole files, and end long shell output with | head -n 40."
+].join("\n");
+var APPLY_EDITS = "Apply the edits yourself: for each block, check that its SEARCH text occurs exactly once in the named file, indentation included; replace it with the REPLACE text; skip a block that matches zero or several times. A path followed by one fenced block is a whole new file. Then run the tests: the edits are a small model's candidates.";
+var AGENT_GUIDE = `Use FreeLlama to run bounded work on local models and keep it out of your context.
+
+Offload when the answer is cheap to check and the work is 10 or more similar items, or an input over about 2,000 tokens you would otherwise read whole. Do it yourself: judgment you must stand behind, edits across files, one short item.
+
+Name a workflow and run_task does the rest: it picks the first catalog model for the job that is installed and fits now and gives it step-by-step instructions for the task. Workflows: read-text, read-table, read-fields (images); answer-image, describe-screen; change-code, fix-bug, implement, write-tests, review-code, explain-code; summarize-log, summarize-text, summarize-diff, extract-json. For labels, code search and duplicates use job classify, find-code or duplicates. Any field you pass wins; job_profile says what was filled in. Name inputs with files; for one answer per file send tasks:[{id, independent:true, task:{files:[path]}}] with job at the top level. For a whole code tree, log or site use sweep; for a question about a repository, delegate_research.
+
+Verify: local answers are candidates. Each run_task result ends with check: lines worked out from it (uncertain answers, close matches, facts not in the source, edits that do not match the file); act on those first, and discard a research result whose verification.recommendation is "escalate".
+
+Coding: the answer is SEARCH/REPLACE blocks. ${APPLY_EDITS}
+
+Hand a result on: saveAs:"<name>" writes the answer to handoffs/<name>.md and returns handoff_file; a later run_task reads it with files:[handoff_file].
+
+Approval: pull a model only after the user approves one exact tag and its size (ollama_pull approvedSizeBytes). Unload only a model you warmed or the user named; delete only a tag the user names. A memory refusal names what holds memory: tell the user and never stop their processes.`;
+
+// src/research/structured-call.ts
+async function structuredSearch(shell, action, timeoutSeconds) {
+  const notes = [];
+  const resolved = resolveNamedPath(shell.workspace, action.path, "any");
+  let target = resolved.path;
+  if (target === void 0) {
+    notes.push(`(${resolved.note}; searched the whole workspace)`);
+    target = ".";
+  } else if (resolved.note) {
+    notes.push(resolved.note);
+  }
+  const ripgrep = shell.hasTool("rg");
+  const run = (regex) => shell.runTool(searchArgv(shell.workspace, { ...action, path: target, regex }, ripgrep), timeoutSeconds);
+  let output = await run(action.regex);
+  if (output === "(no matches)" && action.regex === void 0 && looksLikeRegex(action.pattern)) {
+    try {
+      const asRegex = await run(true);
+      if (asRegex !== "(no matches)") {
+        notes.push("(no literal match; searched as a regular expression)");
+        output = asRegex;
+      }
+    } catch {
+    }
+  }
+  return notes.length > 0 ? `${notes.join("\n")}
+${output}` : output;
+}
+function structuredCall(shell, action, timeoutSeconds) {
+  const name = String(action.action);
+  const args = Object.fromEntries(Object.entries(action).filter(([key]) => key !== "action"));
+  const run = async () => {
+    if (name === "read") return readLines(shell.workspace, args);
+    if (name === "list") return listEntries(shell.workspace, args.path);
+    return structuredSearch(shell, args, timeoutSeconds);
+  };
+  return {
+    signature: { [name]: args },
+    run,
+    record: { name, raw_name: name, arguments: args },
+    ledger: (status) => ({ action: name, status, source: JSON.stringify(args) })
+  };
+}
+
+// src/research/workspace-overview.ts
+import { readdirSync as readdirSync5 } from "node:fs";
+import path10 from "node:path";
+var SKIP = /* @__PURE__ */ new Set(["node_modules", "target", ".git", "dist", "build", ".venv", "venv", "vendor", "__pycache__", ".octocode", "site-packages", "coverage"]);
+var MAX_ENTRIES = 2e4;
+var MAX_DEPTH = 8;
+var SOURCE_DIRS = /* @__PURE__ */ new Set(["src", "lib", "app", "source", "pkg", "cmd", "internal", "crates"]);
+function workspaceOverview(root) {
+  let top;
+  try {
+    top = readdirSync5(root, { withFileTypes: true });
+  } catch {
+    return "";
+  }
+  const extensions = /* @__PURE__ */ new Map();
+  const sourceRoots = /* @__PURE__ */ new Map();
+  let files = 0;
+  let seen = 0;
+  const walk = (dir, depth, sourceRoot) => {
+    if (depth > MAX_DEPTH || seen > MAX_ENTRIES) return;
+    let entries;
+    try {
+      entries = readdirSync5(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (++seen > MAX_ENTRIES) return;
+      if (entry.isDirectory()) {
+        if (SKIP.has(entry.name) || entry.name.startsWith(".")) continue;
+        const child = path10.join(dir, entry.name);
+        walk(child, depth + 1, sourceRoot ?? (SOURCE_DIRS.has(entry.name) ? path10.relative(root, child) : void 0));
+      } else if (entry.isFile()) {
+        files += 1;
+        const extension = path10.extname(entry.name).toLowerCase() || "(none)";
+        extensions.set(extension, (extensions.get(extension) ?? 0) + 1);
+        if (sourceRoot) sourceRoots.set(sourceRoot, (sourceRoots.get(sourceRoot) ?? 0) + 1);
+      }
+    }
+  };
+  walk(root, 0);
+  const listing = top.filter((entry) => !SKIP.has(entry.name) && !entry.name.startsWith(".")).sort((left, right) => Number(right.isDirectory()) - Number(left.isDirectory()) || left.name.localeCompare(right.name)).slice(0, 25).map((entry) => entry.isDirectory() ? `${entry.name}/` : entry.name);
+  const types = [...extensions.entries()].sort((left, right) => right[1] - left[1]).slice(0, 8).map(([extension, count]) => `${extension} ${count}`);
+  const sources = [...sourceRoots.entries()].sort((left, right) => right[1] - left[1]).slice(0, 8).map(([dir, count]) => `${dir}/ (${count})`);
+  return `Workspace overview (generated, not a search result): top level: ${listing.join(", ") || "(empty)"}${top.length > 25 ? ", \u2026" : ""}. ${files}${seen > MAX_ENTRIES ? "+" : ""} files; most common types: ${types.join(", ") || "none"}. ` + (sources.length > 0 ? `Source folders: ${sources.join(", ")}. Paths are relative to the workspace root. ` : "") + "Search the file types that exist here, and search contents before concluding something is absent.";
+}
+
+// src/research/entry.ts
+import path11 from "node:path";
+import { pathToFileURL } from "node:url";
+function isEntry(moduleUrl, name, script = process.argv[1]) {
+  if (!script || moduleUrl !== pathToFileURL(script).href) return false;
+  return path11.basename(script).replace(/\.[cm]?[jt]s$/, "") === name;
+}
+
+// src/research/coder-agent.ts
+var OPT_IN_ENV = "FREELLAMA_MCP_ALLOW_CODER";
+var ACTIONS = ["search", "read", "list", "shell", "edit", "write", "run", "page", "finish"];
+var KEPT_RUN_OUTPUTS = 3;
+var requireString = (value, key, action, nonEmpty = true) => {
+  const field = value[key];
+  if (typeof field !== "string" || nonEmpty && !field) {
+    throw new ValidationError(`${action} action requires a ${nonEmpty ? "non-empty " : ""}string ${key}`);
+  }
+};
+function parseAction(content) {
+  const value = parseJsonAction(content);
+  const action = String(value.action);
+  if (!ACTIONS.includes(action)) throw new ValidationError(`unsupported action for coder adapter: ${action} (use ${ACTIONS.join(", ")})`);
+  if (action === "shell" && (typeof value.command !== "string" || !trimSpace(value.command))) {
+    throw new ValidationError("shell action requires a non-empty string command");
+  }
+  if (action === "run") requireString(value, "command", "run");
+  if (action === "page" && (!isPositiveInt(value.step) || !isPositiveInt(value.page))) {
+    throw new ValidationError("page action requires positive integer step and page");
+  }
+  if (action === "finish") requireString(value, "answer", "finish", false);
+  if (action === "search") validateSearch(value);
+  if (action === "read") validateRead(value);
+  if (action === "list" && value.path !== void 0 && typeof value.path !== "string") throw new ValidationError("list path must be a string");
+  if (action === "edit") {
+    requireString(value, "path", "edit");
+    requireString(value, "search", "edit");
+    requireString(value, "replace", "edit", false);
+    if (value.search === value.replace) throw new ValidationError("edit search and replace are identical; nothing would change");
+  }
+  if (action === "write") {
+    requireString(value, "path", "write");
+    requireString(value, "content", "write", false);
+  }
+  return value;
+}
+function positiveNumber(raw, fallback, max) {
+  const value = raw === void 0 || raw === "" ? Number.NaN : Number(raw);
+  return Number.isFinite(value) && value > 0 ? Math.min(value, max) : fallback;
+}
+function coderOptionsFromEnv(env) {
+  let commands;
+  try {
+    commands = JSON.parse(env.FREELLAMA_CODER_COMMANDS ?? "[]");
+  } catch {
+    throw new ValidationError("FREELLAMA_CODER_COMMANDS must be a JSON array of command strings");
+  }
+  return {
+    commands: normalizeAllowedCommands(commands),
+    container: env.FREELLAMA_CODER_COPY_DIR || void 0,
+    patchPath: env.FREELLAMA_CODER_PATCH || void 0,
+    runTimeoutSeconds: positiveNumber(env.FREELLAMA_CODER_RUN_TIMEOUT_SECONDS, DEFAULT_RUN_TIMEOUT_SECONDS, MAX_RUN_TIMEOUT_SECONDS),
+    maxCopyBytes: positiveNumber(env.FREELLAMA_CODER_MAX_COPY_BYTES, DEFAULT_MAX_COPY_BYTES, Number.MAX_SAFE_INTEGER),
+    writable: (env.FREELLAMA_CODER_WRITABLE ?? "").split(path12.delimiter).filter(Boolean),
+    allowUnsandboxedRun: env.FREELLAMA_CODER_UNSANDBOXED_RUN === "1",
+    osSandbox: env.FREELLAMA_AGENT_OS_SANDBOX === "off" ? "off" : "auto"
+  };
+}
+function writableDirs(dirs, workspace) {
+  return dirs.map((dir) => {
+    if (!path12.isAbsolute(dir)) throw new ValidationError(`FREELLAMA_CODER_WRITABLE entry ${dir} must be absolute`);
+    const real = existsSync8(dir) ? realpathSync5(dir) : path12.resolve(dir);
+    if (!escapesRoot(workspace, real) || !escapesRoot(real, workspace)) {
+      throw new ValidationError(`FREELLAMA_CODER_WRITABLE entry ${dir} overlaps the workspace; the coder never writes the user's files`);
+    }
+    return real;
+  });
+}
+var sha1 = (file) => {
+  try {
+    return createHash3("sha1").update(readFileSync9(file)).digest("hex");
+  } catch {
+    return "missing";
+  }
+};
+var CoderSession = class {
+  constructor(source, copy, options) {
+    this.source = source;
+    this.copy = copy;
+    this.options = options;
+    this.workspace = copy.root;
+    const extra = writableDirs(options.writable ?? [], source);
+    this.shell = new ReadOnlyShell(copy.root, { readPaths: copy.commonDir ? [copy.commonDir] : [] }).enter();
+    try {
+      this.runner = new CommandRunner(copy.root, [copy.top, copy.tmp, ...extra], runEnvironment(process.env, copy.tmp), {
+        privateDir: copy.privateDir,
+        osSandbox: options.osSandbox ?? "auto",
+        allowUnsandboxed: options.allowUnsandboxedRun === true,
+        // A secret location that holds the workspace or the copy would hide the work itself.
+        hidden: secretPaths(process.env).filter((secret) => escapesRoot(source, secret) && escapesRoot(copy.top, secret))
+      }).enter();
+    } catch (error) {
+      this.shell.close();
+      throw error;
+    }
+  }
+  source;
+  copy;
+  options;
+  workspace;
+  shell;
+  runner;
+  runs = [];
+  /** Bumped by every change to the copy, so a read or run after a change is not a repeat. */
+  revision = 0;
+  appliedEdits = /* @__PURE__ */ new Map();
+  closed = false;
+  changed() {
+    this.revision += 1;
+    forgetWorkspaceIndex(this.workspace);
+  }
+  toolCall(action, root, runtime) {
+    const name = String(action.action);
+    if (name === "search" || name === "read" || name === "list") {
+      const call = structuredCall(this.shell, action, runtime.tool_timeout_seconds);
+      return { ...call, signature: { ...call.signature, revision: this.revision } };
+    }
+    if (name === "edit") {
+      const edit = { path: String(action.path), search: String(action.search), replace: String(action.replace) };
+      const key = JSON.stringify(edit);
+      return {
+        // The file's content is part of the identity: a failed edit may be retried once the file changed.
+        signature: { edit, file: sha1(path12.resolve(root, edit.path)) },
+        run: async () => {
+          const step = this.appliedEdits.get(key);
+          if (step !== void 0) throw new ValidationError(`this exact edit was already applied (edit ${step}); read the file to see its current lines`);
+          const result = applyEdit(root, edit);
+          this.appliedEdits.set(key, this.appliedEdits.size + 1);
+          this.changed();
+          return result;
+        },
+        record: { name: "edit", raw_name: "edit", arguments: edit },
+        ledger: (status) => ({ action: "edit", status, source: edit.path })
+      };
+    }
+    if (name === "write") {
+      const write = { path: String(action.path), content: String(action.content) };
+      const bytes = Buffer.byteLength(write.content, "utf8");
+      return {
+        signature: { write },
+        run: async () => {
+          const result = writeWholeFile(root, write);
+          this.changed();
+          return result;
+        },
+        // The content reaches the caller through the diff; the trail keeps its size.
+        record: { name: "write", raw_name: "write", arguments: { path: write.path, content_bytes: bytes, content_limit_bytes: WRITE_MAX_BYTES } },
+        ledger: (status) => ({ action: "write", status, source: write.path })
+      };
+    }
+    if (name === "run") {
+      const requested = String(action.command);
+      return {
+        signature: { run: requested.trim(), revision: this.revision },
+        run: async () => {
+          const command = allowedCommand(requested, this.options.commands);
+          const outcome = await this.runner.run(command, this.options.runTimeoutSeconds ?? DEFAULT_RUN_TIMEOUT_SECONDS);
+          this.runs.push(outcome);
+          this.changed();
+          return describeRun(outcome);
+        },
+        record: { name: "run", raw_name: "run", arguments: { command: requested } },
+        ledger: (status) => ({ action: "run", status, source: requested })
+      };
+    }
+    const commandText = String(action.command ?? "");
+    return {
+      signature: { command: commandText, revision: this.revision },
+      run: () => this.shell.run(commandText, runtime.tool_timeout_seconds),
+      record: { name: "shell", raw_name: action.action ?? "", arguments: { command: commandText } },
+      ledger: (status) => ({ action: "shell", status, source: commandText })
+    };
+  }
+  /** The result's `coder` field: the agent's diff, the files it changed and its runs. */
+  report() {
+    const runs = this.runs.map((outcome, index) => ({
+      command: outcome.command,
+      exit_code: outcome.exitCode,
+      ...outcome.signal ? { signal: outcome.signal } : {},
+      timed_out: outcome.timedOut,
+      duration_ms: outcome.durationMs,
+      ...index >= this.runs.length - KEPT_RUN_OUTPUTS ? { output: outcome.kept } : {}
+    }));
+    const base = {
+      isolation: this.copy.kind,
+      base: { head: this.copy.head, caller_changes: this.copy.callerChanges },
+      linked_dependencies: this.copy.linked,
+      run_sandbox: this.runner.kind,
+      runs
+    };
+    try {
+      const changes = agentChanges(this.copy);
+      let patchFile = null;
+      if (this.options.patchPath && changes.patch.length > 0) {
+        mkdirSync6(path12.dirname(this.options.patchPath), { recursive: true });
+        writeFileSync5(this.options.patchPath, changes.patch, { mode: 384 });
+        patchFile = this.options.patchPath;
+      }
+      return {
+        coder: { ...base, diff: changes.patch.toString("utf8"), patch_bytes: changes.patch.length, patch_file: patchFile, changed_files: changes.files }
+      };
+    } catch (error) {
+      return { coder: { ...base, diff: "", changed_files: [], error: `could not collect the changes: ${error instanceof Error ? error.message : String(error)}` } };
+    }
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.shell.close();
+    removeIsolatedCopy(this.source, this.copy.container);
+  }
+};
+function briefing(commands) {
+  return (workspace) => {
+    const overview = workspaceOverview(workspace);
+    const allowed = commands.length > 0 ? `Allowed run commands, exactly as written: ${commands.map((command) => JSON.stringify(command)).join(", ")}.` : "No run commands are allowed in this task: you cannot test, so say the change is untested when you finish.";
+    return overview ? `${overview}
+
+${allowed}` : allowed;
+  };
+}
+function coderAdapter(options) {
+  const commands = normalizeAllowedCommands(options.commands);
+  const settings = { ...options, commands };
+  return {
+    defaultToolTimeoutSeconds: 30,
+    systemPrompt: () => CODER_SYSTEM_PROMPT,
+    briefing: briefing(commands),
+    parseAction,
+    requireSource: false,
+    open: (workspace) => {
+      const container = settings.container ?? newCopyContainer();
+      const copy = createIsolatedCopy(workspace, container, { maxCopyBytes: settings.maxCopyBytes, linkDependencies: settings.linkDependencies });
+      try {
+        return new CoderSession(realpathSync5(workspace), copy, settings);
+      } catch (error) {
+        removeIsolatedCopy(workspace, copy.container);
+        throw error;
+      }
+    },
+    remaining: (count) => `
+
+Actions remaining: ${count}. Finish once the change is made and tested; do not repeat prior actions.`,
+    exhausted: "Action budget is exhausted. Return exactly a finish JSON action now: what changed, why, and the last test result. Do not request another action.",
+    adapterMetadata: (session) => {
+      const coder = session;
+      return {
+        adapter: "coder_agent_v1",
+        sandbox: coder?.shell.kind ?? "restricted-bash",
+        run_sandbox: coder?.runner.kind ?? "none",
+        isolation: coder?.copy.kind ?? null
+      };
+    },
+    report: (session) => session instanceof CoderSession ? session.report() : {}
+  };
+}
+if (isEntry(import.meta.url, "coder-agent")) {
+  const result = process.env.FREELLAMA_AGENT_RESULT;
+  const refuse = (message) => {
+    process.stderr.write(`${message}
+`);
+    if (result) writeFailureResult(result, message);
+    process.exitCode = 1;
+  };
+  if (process.env[OPT_IN_ENV] !== "1") {
+    refuse(`the coder adapter is off: the operator enables it with ${OPT_IN_ENV}=1 in the MCP server's environment`);
+  } else {
+    let options;
+    try {
+      options = coderOptionsFromEnv(process.env);
+    } catch (error) {
+      refuse(`invalid coder adapter configuration: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (options) process.exitCode = await runAdapter(coderAdapter(options));
+  }
+}
+export {
+  OPT_IN_ENV,
+  coderAdapter,
+  coderOptionsFromEnv,
+  parseAction
+};