@quikit/quikpilot-runner 9.1.0 → 9.2.0-rc.2

package/dist/index.js

@@ -624,8 +624,8 @@ var TS_SIBLINGS = { ".js": [".ts", ".tsx"], ".jsx": [".tsx"], ".mjs": [".mts"],
 function resolveImport(fromPath, specifier, listing) {
   if (/^(?:@\/|~\/|#|\$|\/)/.test(specifier)) return { kind: "unresolved", reason: "alias" };
   const clean = specifier.replace(/[?#].*$/, "");
-  const relative4 = clean === "." || clean === ".." || clean.startsWith("./") || clean.startsWith("../");
-  if (!relative4) return { kind: "external" };
+  const relative5 = clean === "." || clean === ".." || clean.startsWith("./") || clean.startsWith("../");
+  if (!relative5) return { kind: "external" };
   const base = import_node_path.posix.normalize(import_node_path.posix.join(import_node_path.posix.dirname(fromPath), clean));
   if (base === ".." || base.startsWith("../") || import_node_path.posix.isAbsolute(base)) return { kind: "unresolved", reason: "not found" };
   const ext = import_node_path.posix.extname(base);
@@ -1563,8 +1563,8 @@ async function reportToQuikTest(params) {
   try {
     console.log(`reporting ${report}`);
     const ciUrl = buildCiUrl(githubServerUrl, githubRepository, githubRunId);
-    const { readFileSync: readFileSync7 } = await import("node:fs");
-    const body = readFileSync7(report);
+    const { readFileSync: readFileSync8 } = await import("node:fs");
+    const body = readFileSync8(report);
     let url = `${resultsUrl}?ciUrl=${encodeURIComponent(ciUrl)}&automationIdFormat=bracket`;
     if (generatedFiles) {
       url += `&generatedFiles=${encodeURIComponent(generatedFiles.join(","))}`;
@@ -1982,7 +1982,7 @@ var FAILURE_ARTIFACT_DIR = "quikpilot-failure";
 var REPORT_COPY = "final-test-report.xml";
 var MAX_REPORT_BYTES = 5 * 1024 * 1024;
 var MAX_FILES = 200;
-var RUNNER_VERSION = true ? "9.1.0" : "dev";
+var RUNNER_VERSION = true ? "9.2.0-rc.2" : "dev";
 function safeDestination(base, repoPath) {
   if (!repoPath || (0, import_node_path6.isAbsolute)(repoPath)) return null;
   const destination = (0, import_node_path6.resolve)(base, repoPath);
@@ -2118,7 +2118,685 @@ function describeScopeViolations(check) {
 }
 
 // src/targeting.ts
+var import_node_path9 = require("node:path");
+
+// src/targetingErrors.ts
+var DeniedPathError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DeniedPathError";
+  }
+};
+var TargetingHttpError = class extends Error {
+  status;
+  constructor(status, statusText) {
+    super(`Targeting call failed: ${status} ${statusText}`);
+    this.name = "TargetingHttpError";
+    this.status = status;
+  }
+};
+
+// src/targetingMode.ts
+var TARGETING_MODE_ENV = "QUIKPILOT_TARGETING_MODE";
+function parse(value) {
+  if (typeof value !== "string") return null;
+  const v = value.trim().toLowerCase();
+  if (v === "loop") return "loop";
+  if (v === "single") return "single";
+  return null;
+}
+function resolveTargetingMode(env2 = process.env, packetSetting) {
+  const fromSetting = parse(packetSetting);
+  if (fromSetting) return fromSetting;
+  return parse(env2[TARGETING_MODE_ENV]) ?? "single";
+}
+
+// src/targetingPaths.ts
 var import_node_path7 = require("node:path");
+var MAX_PATH_CHARS = 300;
+function hasControlChar(s) {
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c < 32 || c === 127) return true;
+  }
+  return false;
+}
+function normaliseToolPath(raw, options = {}) {
+  const allowRoot = options.allowRoot === true;
+  if ((raw === void 0 || raw === null || raw === "") && allowRoot) return { ok: true, path: "" };
+  if (typeof raw !== "string" || raw.length === 0 || raw.length > MAX_PATH_CHARS) {
+    return { ok: false, reason: "path_invalid" };
+  }
+  if (hasControlChar(raw)) return { ok: false, reason: "path_invalid" };
+  if (raw.includes("\\")) return { ok: false, reason: "path_invalid" };
+  if (raw.startsWith("/") || /^[A-Za-z]:/.test(raw)) return { ok: false, reason: "path_invalid" };
+  if (raw.split("/").includes("..")) return { ok: false, reason: "outside_workspace" };
+  const normalised = import_node_path7.posix.normalize(raw).replace(/\/+$/, "");
+  if (normalised === "" || normalised === ".") {
+    return allowRoot ? { ok: true, path: "" } : { ok: false, reason: "path_invalid" };
+  }
+  return { ok: true, path: normalised };
+}
+function matchesPrefix(path, prefix) {
+  if (prefix === "") return true;
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+function buildVisibleListing(listing, deniedPaths) {
+  return listing.filter((p) => !matchesDeniedPath(p, deniedPaths)).sort();
+}
+
+// src/targetingTools.ts
+var import_node_fs9 = require("node:fs");
+var import_node_path8 = require("node:path");
+var DEFAULT_LIMITS = {
+  maxTurns: 12,
+  maxToolCalls: 25,
+  maxCallsPerTurn: 8,
+  readCharsPerRead: 2e4,
+  // The per-run read cap stops the COST; the per-turn ceiling below stops the FAILURE. Different jobs.
+  readCharsTotal: 6e4,
+  resultCharsTotal: 8e4,
+  // 131,072 (the smallest 128k-class window) - 8,192 reserved output - a 3,741-token real request leaves
+  // ~116,000; 90,000 keeps ~26,000 for a repository whose listing is thousands of paths, and stays well
+  // clear of the per-minute quota, which binds before the window does. Set by the AI Runtime owner.
+  maxRequestTokens: 9e4,
+  grepMaxMatches: 40,
+  grepLineChars: 200,
+  grepFileBytes: 262144,
+  grepMaxFiles: 3e3,
+  grepMaxBytes: 2e7,
+  fileBytesMax: 1e6,
+  listMaxEntries: 500,
+  maxReasoningChars: 500,
+  maxPatternChars: 200
+};
+function createNodeToolFs(rootDir = process.cwd()) {
+  const rootReal = (0, import_node_fs9.realpathSync)(rootDir);
+  return {
+    rootReal,
+    lstat(rel) {
+      const s = (0, import_node_fs9.lstatSync)((0, import_node_path8.join)(rootDir, rel));
+      return { isSymlink: s.isSymbolicLink(), isFile: s.isFile(), size: s.size };
+    },
+    realpathInside(rel) {
+      const real = (0, import_node_fs9.realpathSync)((0, import_node_path8.join)(rootDir, rel));
+      const r = (0, import_node_path8.relative)(rootReal, real);
+      return r !== "" && !r.startsWith("..") && !(0, import_node_path8.isAbsolute)(r);
+    },
+    readBytes(rel) {
+      return (0, import_node_fs9.readFileSync)((0, import_node_path8.join)(rootDir, rel));
+    }
+  };
+}
+function newLedger() {
+  return { toolCalls: 0, readChars: 0, resultChars: 0, refused: 0, seen: /* @__PURE__ */ new Map() };
+}
+var INVALID_PATH = "(invalid path)";
+var CUT = "\u2026[line cut]";
+function isPlainObject(x) {
+  return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function bad(message) {
+  return { fail: { status: "bad_args", message } };
+}
+function optionalInt(v) {
+  if (v === void 0 || v === null) return void 0;
+  return typeof v === "number" && Number.isInteger(v) ? v : "bad";
+}
+function hasNul(bytes) {
+  const n = Math.min(bytes.length, 8e3);
+  for (let i = 0; i < n; i++) if (bytes[i] === 0) return true;
+  return false;
+}
+function gatePath(raw, env2) {
+  const n = normaliseToolPath(raw);
+  if (!n.ok) {
+    return { ok: false, path: INVALID_PATH, fail: { status: "refused", reason: n.reason, message: "That path is not allowed." } };
+  }
+  if (matchesDeniedPath(n.path, env2.deniedPaths)) {
+    return { ok: false, path: n.path, fail: { status: "refused", reason: "denied", message: "That path is protected and cannot be read." } };
+  }
+  if (!env2.listing.has(n.path)) {
+    return { ok: false, path: n.path, fail: { status: "not_found", message: "Not a tracked file. Use list_files to see the available paths." } };
+  }
+  return { ok: true, path: n.path };
+}
+function prepareReadFile(args, env2, ledger) {
+  const start = optionalInt(args.startLine);
+  const end = optionalInt(args.endLine);
+  if (start === "bad" || end === "bad") return bad("startLine and endLine must be whole numbers.");
+  if (start !== void 0 && end !== void 0 && end < start) return bad("endLine must not be before startLine.");
+  if (typeof args.path !== "string") return bad("path must be a string.");
+  const gate = gatePath(args.path, env2);
+  if (!gate.ok) {
+    const read = gate.fail.status === "refused" ? { path: gate.path, chars: 0, refused: true } : void 0;
+    return { fail: gate.fail, ...read ? { read } : {} };
+  }
+  const path = gate.path;
+  const key = JSON.stringify({ path, startLine: start ?? null, endLine: end ?? null });
+  return {
+    key,
+    exec: () => {
+      let size;
+      try {
+        const st = env2.fs.lstat(path);
+        if (st.isSymlink) {
+          return { result: { status: "refused", reason: "symlink", message: "Links are not followed." }, read: { path, chars: 0, refused: true } };
+        }
+        if (!st.isFile) return { result: { status: "unreadable", reason: "not_a_file", message: "That entry is not a regular file." } };
+        size = st.size;
+        if (size > env2.limits.fileBytesMax) {
+          return { result: { status: "unreadable", reason: "too_large", message: "That file is too large to read." } };
+        }
+        if (!env2.fs.realpathInside(path)) {
+          return { result: { status: "refused", reason: "outside_workspace", message: "That path is not allowed." }, read: { path, chars: 0, refused: true } };
+        }
+      } catch {
+        return { result: { status: "unreadable", reason: "io", message: "That file could not be read." } };
+      }
+      let bytes;
+      try {
+        bytes = env2.fs.readBytes(path);
+      } catch {
+        return { result: { status: "unreadable", reason: "io", message: "That file could not be read." } };
+      }
+      if (hasNul(bytes)) return { result: { status: "unreadable", reason: "binary", message: "That file is binary." } };
+      let text;
+      try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      } catch {
+        return { result: { status: "unreadable", reason: "not_utf8", message: "That file is not valid UTF-8 text." } };
+      }
+      if (text.charCodeAt(0) === 65279) text = text.slice(1);
+      text = text.replace(/\r\n/g, "\n");
+      const lines = text === "" ? [] : text.split("\n");
+      if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+      const totalLines = lines.length;
+      const startLine = Math.max(1, start ?? 1);
+      const endWanted = Math.min(totalLines, end ?? totalLines);
+      if (startLine > totalLines) {
+        return {
+          result: { status: "ok", output: { path, startLine, endLine: totalLines, totalLines, truncated: false, content: "" } },
+          read: { path, startLine, endLine: totalLines, chars: 0 }
+        };
+      }
+      const budget = Math.max(0, Math.min(env2.limits.readCharsPerRead, env2.limits.readCharsTotal - ledger.readChars));
+      const out = [];
+      let used = 0;
+      let endLine = startLine - 1;
+      let truncated = false;
+      for (let n = startLine; n <= endWanted; n++) {
+        const line = `${n}	${lines[n - 1]}`;
+        const cost = line.length + (out.length > 0 ? 1 : 0);
+        if (used + cost <= budget) {
+          out.push(line);
+          used += cost;
+          endLine = n;
+          continue;
+        }
+        truncated = true;
+        if (out.length === 0) {
+          const keep = Math.max(0, budget - CUT.length);
+          out.push(line.slice(0, keep) + CUT);
+          used = out[0].length;
+          endLine = n;
+        }
+        break;
+      }
+      let content = out.join("\n");
+      ledger.readChars += used;
+      const output = { path, startLine, endLine, totalLines, truncated };
+      if (truncated) {
+        if (endLine < totalLines) {
+          output.nextStartLine = endLine + 1;
+          content += `
+[truncated: showing lines ${startLine}-${endLine} of ${totalLines}; call read_file with startLine=${endLine + 1}]`;
+        } else {
+          content += `
+[truncated: line ${endLine} was cut]`;
+        }
+      }
+      output.content = content;
+      return { result: { status: "ok", output }, read: { path, startLine, endLine, chars: used } };
+    }
+  };
+}
+function prepareListFiles(args, env2) {
+  const max = optionalInt(args.maxEntries);
+  if (max === "bad" || max !== void 0 && max < 1) return bad("maxEntries must be a whole number of at least 1.");
+  if (args.prefix !== void 0 && args.prefix !== null && typeof args.prefix !== "string") return bad("prefix must be a string.");
+  const n = normaliseToolPath(args.prefix, { allowRoot: true });
+  if (!n.ok) return { fail: { status: "refused", reason: n.reason, message: "That path is not allowed." } };
+  const prefix = n.path;
+  const cap = Math.min(max ?? env2.limits.listMaxEntries, env2.limits.listMaxEntries);
+  return {
+    key: JSON.stringify({ prefix, maxEntries: cap }),
+    exec: () => {
+      const matching = env2.visible.filter((p) => matchesPrefix(p, prefix));
+      const entries = matching.slice(0, cap);
+      const truncated = matching.length > cap;
+      const output = { entries, total: matching.length, truncated };
+      if (truncated) {
+        const counts = /* @__PURE__ */ new Map();
+        for (const p of matching) {
+          const rest = prefix === "" ? p : p.slice(prefix.length + 1);
+          const slash = rest.indexOf("/");
+          if (slash > 0) counts.set(rest.slice(0, slash), (counts.get(rest.slice(0, slash)) ?? 0) + 1);
+        }
+        output.subdirs = [...counts.entries()].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count || (a.name < b.name ? -1 : 1)).slice(0, 50);
+      }
+      return { result: { status: "ok", output } };
+    }
+  };
+}
+var WORD_CHAR = /[A-Za-z0-9_$]/;
+function lineMatches(line, needle, ignoreCase, wholeWord) {
+  const hay = ignoreCase ? line.toLowerCase() : line;
+  let from = 0;
+  for (; ; ) {
+    const i = hay.indexOf(needle, from);
+    if (i === -1) return -1;
+    if (!wholeWord) return i;
+    const before = i > 0 ? hay[i - 1] : "";
+    const after = i + needle.length < hay.length ? hay[i + needle.length] : "";
+    if (!(before && WORD_CHAR.test(before)) && !(after && WORD_CHAR.test(after))) return i;
+    from = i + 1;
+  }
+}
+function excerpt(line, at, max) {
+  const t = line.trim();
+  if (t.length <= max) return t;
+  const lead = line.length - line.trimStart().length;
+  const pos = Math.max(0, at - lead);
+  const from = Math.max(0, Math.min(pos - 40, t.length - max));
+  const piece = t.slice(from, from + max);
+  return `${from > 0 ? "\u2026" : ""}${piece}${from + max < t.length ? "\u2026" : ""}`;
+}
+function prepareGrep(args, env2) {
+  const pattern = args.pattern;
+  if (typeof pattern !== "string" || pattern.length === 0 || pattern.length > env2.limits.maxPatternChars) {
+    return bad("pattern must be a non-empty string within the length limit.");
+  }
+  if (/[\u0000\r\n]/.test(pattern)) return bad("pattern must be a single line of plain text.");
+  for (const flag of ["ignoreCase", "wholeWord"]) {
+    if (args[flag] !== void 0 && typeof args[flag] !== "boolean") return bad(`${flag} must be true or false.`);
+  }
+  const maxIn = optionalInt(args.maxResults);
+  if (maxIn === "bad" || maxIn !== void 0 && maxIn < 1) return bad("maxResults must be a whole number of at least 1.");
+  if (args.pathPrefix !== void 0 && args.pathPrefix !== null && typeof args.pathPrefix !== "string") return bad("pathPrefix must be a string.");
+  const n = normaliseToolPath(args.pathPrefix, { allowRoot: true });
+  if (!n.ok) return { fail: { status: "refused", reason: n.reason, message: "That path is not allowed." } };
+  const prefix = n.path;
+  const ignoreCase = args.ignoreCase === true;
+  const wholeWord = args.wholeWord === true;
+  const maxMatches = Math.min(maxIn ?? env2.limits.grepMaxMatches, env2.limits.grepMaxMatches);
+  const needle = ignoreCase ? pattern.toLowerCase() : pattern;
+  return {
+    key: JSON.stringify({ pattern, pathPrefix: prefix, maxResults: maxMatches, ignoreCase, wholeWord }),
+    exec: () => {
+      const matches = [];
+      const skipped = { large: 0, binary: 0 };
+      let filesScanned = 0;
+      let bytesScanned = 0;
+      let scanCapped = false;
+      let truncated = false;
+      scan: for (const path of env2.visible) {
+        if (!matchesPrefix(path, prefix)) continue;
+        if (filesScanned >= env2.limits.grepMaxFiles || bytesScanned >= env2.limits.grepMaxBytes) {
+          scanCapped = true;
+          break;
+        }
+        filesScanned += 1;
+        let bytes;
+        try {
+          const st = env2.fs.lstat(path);
+          if (st.isSymlink || !st.isFile) continue;
+          if (st.size > env2.limits.grepFileBytes) {
+            skipped.large += 1;
+            continue;
+          }
+          if (!env2.fs.realpathInside(path)) continue;
+          bytes = env2.fs.readBytes(path);
+        } catch {
+          continue;
+        }
+        bytesScanned += bytes.length;
+        if (hasNul(bytes)) {
+          skipped.binary += 1;
+          continue;
+        }
+        const lines = new TextDecoder("utf-8").decode(bytes).replace(/\r\n/g, "\n").split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          const at = lineMatches(lines[i], needle, ignoreCase, wholeWord);
+          if (at === -1) continue;
+          if (matches.length >= maxMatches) {
+            truncated = true;
+            break scan;
+          }
+          matches.push({ path, line: i + 1, text: excerpt(lines[i], at, env2.limits.grepLineChars) });
+        }
+      }
+      const output = { matches, truncated, filesScanned, skipped };
+      if (scanCapped) output.scanCapped = true;
+      return { result: { status: "ok", output } };
+    }
+  };
+}
+function budgetResult(reason) {
+  return { status: "budget_exhausted", reason, message: "That limit has been reached; give your answer from what you have." };
+}
+function executeToolCall(call, env2, ledger) {
+  const wrap = (r) => ({ id: call.id, name: call.name, ...r });
+  const finish = (r, read) => {
+    const result = wrap(r);
+    ledger.resultChars += JSON.stringify(result).length;
+    if (result.status === "refused") ledger.refused += 1;
+    return read ? { result, read } : { result };
+  };
+  if (ledger.toolCalls >= env2.limits.maxToolCalls) return finish(budgetResult("tool_calls"));
+  if (ledger.resultChars >= env2.limits.resultCharsTotal) return finish(budgetResult("result_chars"));
+  if (call.name === "read_file" && ledger.readChars >= env2.limits.readCharsTotal) return finish(budgetResult("read_chars"));
+  ledger.toolCalls += 1;
+  let prepared;
+  try {
+    if (call.name !== "read_file" && call.name !== "list_files" && call.name !== "grep") {
+      return finish({ status: "unknown_tool", message: "Unknown tool. Use list_files, read_file or grep." });
+    }
+    if (!isPlainObject(call.args)) return finish({ status: "bad_args", message: "Arguments must be an object." });
+    prepared = call.name === "read_file" ? prepareReadFile(call.args, env2, ledger) : call.name === "list_files" ? prepareListFiles(call.args, env2) : prepareGrep(call.args, env2);
+  } catch {
+    return finish({ status: "bad_args", message: "Those arguments could not be used." });
+  }
+  if ("fail" in prepared) return finish(prepared.fail, prepared.read);
+  const dupKey = `${call.name}:${prepared.key}`;
+  const earlier = ledger.seen.get(dupKey);
+  if (earlier !== void 0) {
+    return finish({ status: "duplicate", reason: earlier, message: "Identical call already made; see its result." });
+  }
+  ledger.seen.set(dupKey, call.id);
+  let executed;
+  try {
+    executed = prepared.exec();
+  } catch {
+    executed = { result: { status: "unreadable", reason: "io", message: "That could not be read." } };
+  }
+  return finish(executed.result, executed.read);
+}
+
+// src/tokenEstimate.ts
+var TOKENS_PER_ALPHA_CHAR = 0.3;
+var TOKENS_PER_DIGIT_CHAR = 0.18;
+var TOKENS_PER_SPACE_CHAR = 0.05;
+var TOKENS_PER_PUNCTUATION_CHAR = 1.05;
+var TOKENS_PER_NON_ASCII_CHAR = 1;
+var PROMPT_OVERHEAD_TOKENS = 5e3;
+function estimateTokens(text) {
+  let alpha = 0;
+  let digit = 0;
+  let space = 0;
+  let punct = 0;
+  let nonAscii = 0;
+  for (const ch of text) {
+    const code = ch.codePointAt(0);
+    if (code >= 128) nonAscii++;
+    else if (code >= 65 && code <= 90 || code >= 97 && code <= 122) alpha++;
+    else if (code >= 48 && code <= 57) digit++;
+    else if (code === 32 || code === 9 || code === 13 || code === 10) space++;
+    else punct++;
+  }
+  return Math.ceil(
+    alpha * TOKENS_PER_ALPHA_CHAR + digit * TOKENS_PER_DIGIT_CHAR + space * TOKENS_PER_SPACE_CHAR + punct * TOKENS_PER_PUNCTUATION_CHAR + nonAscii * TOKENS_PER_NON_ASCII_CHAR
+  );
+}
+function estimateRequestTokens(contextData) {
+  return PROMPT_OVERHEAD_TOKENS + estimateTokens(JSON.stringify(contextData ?? {}, null, 2));
+}
+
+// src/targetingLoop.ts
+var LOOP_CONTRACT_VERSION = "targeting-loop-1";
+var LoopFailure = class extends Error {
+  reason;
+  runtimeCode;
+  /** What the loop had done when it failed, so reads made before the failure are not lost. */
+  summary;
+  constructor(reason, runtimeCode, cause) {
+    super(`pilot.targeting loop failed: ${reason}${runtimeCode ? ` (${runtimeCode})` : ""}`);
+    this.name = "LoopFailure";
+    this.reason = reason;
+    this.runtimeCode = runtimeCode;
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+var SafetyRefusalError = class extends RuntimeReplyError {
+  constructor(message, summary) {
+    super(message, summary);
+    this.name = "SafetyRefusalError";
+  }
+};
+var NO_FALLBACK_CODES = /* @__PURE__ */ new Set(["RUN_BUDGET_EXCEEDED", "RUN_CREDENTIAL_SCOPE"]);
+var TOOL_NAMES = /* @__PURE__ */ new Set(["list_files", "read_file", "grep"]);
+var MAX_ID_CHARS = 64;
+var MAX_CALLS_IN_A_REPLY = 50;
+var MAX_ARGS_JSON_CHARS = 1e3;
+function isPlainObject2(x) {
+  return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function safeArgs(args) {
+  try {
+    return JSON.stringify(args).length <= MAX_ARGS_JSON_CHARS ? args : { _omitted: "too large" };
+  } catch {
+    return { _omitted: "unreadable" };
+  }
+}
+function classifyTransport(err) {
+  if (err instanceof TargetingHttpError) return new LoopFailure("http_error", void 0, err);
+  const name = err?.name;
+  if (name === "TimeoutError" || name === "AbortError") return new LoopFailure("turn_timeout", void 0, err);
+  return new LoopFailure("transport", void 0, err);
+}
+async function runTargetingLoop(args, deps) {
+  const limits = { ...DEFAULT_LIMITS, ...deps.limits };
+  const now = deps.now ?? Date.now;
+  const log = deps.log ?? ((e) => console.log(JSON.stringify(e)));
+  const turnTimeoutMs = deps.turnTimeoutMs ?? 18e4;
+  const deadlineMs = deps.deadlineMs ?? 6e5;
+  const env2 = {
+    listing: new Set(args.listing),
+    visible: buildVisibleListing(args.listing, args.deniedPaths),
+    deniedPaths: args.deniedPaths,
+    fs: deps.fs ?? createNodeToolFs(),
+    limits
+  };
+  const ledger = newLedger();
+  const reads = [];
+  const transcript = [];
+  const toolResults = [];
+  const usedIds = /* @__PURE__ */ new Set();
+  let turns = 0;
+  let noProgressStreak = 0;
+  let forced = null;
+  const started = now();
+  const buildContext = (turn, isFinal, finalReason) => ({
+    ...args.baseContext,
+    contractVersion: LOOP_CONTRACT_VERSION,
+    loop: {
+      turn,
+      maxTurns: limits.maxTurns,
+      final: isFinal,
+      ...isFinal ? { finalReason } : {},
+      remaining: {
+        toolCalls: Math.max(0, limits.maxToolCalls - ledger.toolCalls),
+        readChars: Math.max(0, limits.readCharsTotal - ledger.readChars)
+      },
+      transcript,
+      toolResults
+    }
+  });
+  const snapshot = (stopReason) => ({
+    turns,
+    toolCalls: ledger.toolCalls,
+    readChars: ledger.readChars,
+    refused: ledger.refused,
+    stopReason,
+    reads: [...reads]
+  });
+  log({ event: "targeting.loop_start", mode: "loop", maxTurns: limits.maxTurns, maxToolCalls: limits.maxToolCalls, listingFiles: args.listing.length });
+  try {
+    for (let turn = 1; turn <= limits.maxTurns; turn++) {
+      turns = turn;
+      if (now() - started > deadlineMs) throw new LoopFailure("loop_deadline");
+      const isFinal = forced !== null || turn === limits.maxTurns;
+      const finalReason = forced ?? "max_turns";
+      const contextData = buildContext(turn, isFinal, finalReason);
+      const requestChars = JSON.stringify(contextData).length;
+      const requestTokens = estimateRequestTokens(contextData);
+      if (requestTokens > limits.maxRequestTokens) {
+        log({ event: "targeting.loop_ceiling", turn, action: "not_sent", projectedTokens: requestTokens, ceiling: limits.maxRequestTokens });
+        throw new LoopFailure("token_ceiling");
+      }
+      const turnStarted = now();
+      let envelope;
+      try {
+        envelope = await deps.post(contextData, AbortSignal.timeout(turnTimeoutMs));
+      } catch (err) {
+        throw classifyTransport(err);
+      }
+      const code = envelope?.errorCode;
+      try {
+        checkHardFailure(envelope, "pilot.targeting");
+      } catch (err) {
+        throw new LoopFailure(code === "CONTRACT_REJECTED" ? "contract_rejected" : "semantic_mismatch", String(code), err);
+      }
+      if (envelope?.success === false) {
+        const runtimeCode = typeof code === "string" ? code : void 0;
+        if (runtimeCode && NO_FALLBACK_CODES.has(runtimeCode)) {
+          let inner;
+          try {
+            unwrapExecute(envelope, "pilot.targeting");
+          } catch (e) {
+            inner = e instanceof RuntimeReplyError ? e : void 0;
+          }
+          const fallbackText = `pilot.targeting failed: ${runtimeCode}`;
+          throw new SafetyRefusalError(inner?.message ?? fallbackText, inner?.summary ?? fallbackText);
+        }
+        throw new LoopFailure("runtime_failed", runtimeCode);
+      }
+      let body;
+      try {
+        body = unwrapExecute(envelope, "pilot.targeting");
+      } catch (err) {
+        throw new LoopFailure("bad_reply", void 0, err);
+      }
+      if (body.outcome === "TARGETED" || body.outcome === "NO_TARGET") {
+        log({ event: "targeting.loop_turn", turn, outcome: "final", requestChars, requestTokens, elapsedMs: now() - turnStarted, calls: [] });
+        const stopReason = isFinal ? `forced_${finalReason}` : "model_final";
+        log({ event: "targeting.loop_done", turns, toolCalls: ledger.toolCalls, readChars: ledger.readChars, refused: ledger.refused, stopReason });
+        return { body, summary: snapshot(stopReason) };
+      }
+      if (body.outcome !== "TOOL_CALLS") throw new LoopFailure("bad_reply");
+      if (isFinal) throw new LoopFailure("final_not_produced");
+      const rawCalls = body.toolCalls;
+      if (!Array.isArray(rawCalls) || rawCalls.length === 0 || rawCalls.length > MAX_CALLS_IN_A_REPLY) {
+        throw new LoopFailure("bad_reply");
+      }
+      const calls = [];
+      for (const c of rawCalls) {
+        if (!isPlainObject2(c) || typeof c.id !== "string" || c.id.length === 0 || c.id.length > MAX_ID_CHARS || typeof c.name !== "string") {
+          throw new LoopFailure("bad_reply");
+        }
+        if (usedIds.has(c.id) || calls.some((x) => x.id === c.id)) throw new LoopFailure("duplicate_call_ids");
+        calls.push({ id: c.id, name: c.name, args: c.args });
+      }
+      for (const c of calls) usedIds.add(c.id);
+      const results = [];
+      const logged = [];
+      const turnReads = [];
+      calls.forEach((call, index) => {
+        let result;
+        let read;
+        if (index >= limits.maxCallsPerTurn) {
+          result = {
+            id: call.id,
+            name: call.name,
+            status: "budget_exhausted",
+            reason: "too_many_calls",
+            message: "Too many calls in one turn; this one was not run."
+          };
+        } else {
+          try {
+            ({ result, read } = executeToolCall(call, env2, ledger));
+          } catch (err) {
+            throw new LoopFailure("executor_error", void 0, err);
+          }
+        }
+        results.push(result);
+        turnReads[index] = read;
+        if (read) reads.push(read);
+        const tool = TOOL_NAMES.has(call.name) ? call.name : "unknown";
+        const path = read && read.path !== "(invalid path)" ? { path: read.path } : {};
+        logged.push({ tool, status: result.status, ...result.reason && result.status !== "duplicate" ? { reason: result.reason } : {}, ...path });
+        if (result.status === "refused") {
+          log({ event: "targeting.loop_refused", turn, tool, reason: result.reason, ...path });
+        }
+      });
+      const reasoning = typeof body.reasoning === "string" ? body.reasoning.slice(0, limits.maxReasoningChars) : void 0;
+      transcript.push({
+        turn,
+        ...reasoning ? { reasoning } : {},
+        toolCalls: calls.map((c) => ({ id: c.id, name: c.name, args: safeArgs(c.args) }))
+      });
+      toolResults.push(...results);
+      noProgressStreak = results.every((r) => r.status === "duplicate") ? noProgressStreak + 1 : 0;
+      if (noProgressStreak >= 2) forced = "no_progress";
+      else if (ledger.toolCalls >= limits.maxToolCalls) forced = "tool_budget";
+      else if (ledger.readChars >= limits.readCharsTotal || ledger.resultChars >= limits.resultCharsTotal) forced = "read_budget";
+      const nextTurn = turn + 1;
+      if (nextTurn <= limits.maxTurns) {
+        const nextFinal = forced !== null || nextTurn === limits.maxTurns;
+        const projected = estimateRequestTokens(buildContext(nextTurn, nextFinal, forced ?? "max_turns"));
+        if (projected > limits.maxRequestTokens) {
+          results.forEach((r, idx) => {
+            if (r.status !== "ok") return;
+            toolResults[toolResults.indexOf(r)] = {
+              id: r.id,
+              name: r.name,
+              status: "budget_exhausted",
+              reason: "token_ceiling",
+              message: "Too large to include; answer from what you have."
+            };
+            const dropped = turnReads[idx];
+            if (dropped) {
+              const at = reads.indexOf(dropped);
+              if (at >= 0) reads.splice(at, 1);
+            }
+            logged[idx].status = "budget_exhausted";
+            logged[idx].reason = "token_ceiling";
+          });
+          forced = "read_budget";
+          const trimmed = estimateRequestTokens(buildContext(nextTurn, true, "read_budget"));
+          const fits = trimmed <= limits.maxRequestTokens;
+          log({
+            event: "targeting.loop_ceiling",
+            turn,
+            action: fits ? "dropped_results" : "fallback",
+            projectedTokens: projected,
+            ceiling: limits.maxRequestTokens
+          });
+          if (!fits) throw new LoopFailure("token_ceiling");
+        }
+      }
+      log({ event: "targeting.loop_turn", turn, outcome: "tool_calls", requestChars, requestTokens, elapsedMs: now() - turnStarted, calls: logged });
+    }
+    throw new LoopFailure("final_not_produced");
+  } catch (err) {
+    if (err instanceof SafetyRefusalError) throw err;
+    const failure = err instanceof LoopFailure ? err : new LoopFailure("internal_error", void 0, err);
+    failure.summary ??= snapshot("fallback");
+    throw failure;
+  }
+}
+
+// src/targeting.ts
 var CONTRACT_VERSION2 = "test-targets-1";
 function listWorkspaceFiles(workspaceRoot) {
   return listFiles(workspaceRoot ?? ".");
@@ -2126,13 +2804,13 @@ function listWorkspaceFiles(workspaceRoot) {
 function validateTarget(target, workspaceRoot, workspaceListing, deniedPaths) {
   const denied = matchesDeniedPath(target.path, deniedPaths);
   if (denied) {
-    throw new Error(
+    throw new DeniedPathError(
       `pilot.targeting proposed a target matching a denied path (${denied}): ${target.path}`
     );
   }
   const deniedContext = findDeniedContextPath(target.contextPaths ?? [], deniedPaths);
   if (deniedContext) {
-    throw new Error(
+    throw new DeniedPathError(
       `pilot.targeting cited a denied path as context (${deniedContext.pattern}): ${deniedContext.path} (target ${target.path})`
     );
   }
@@ -2147,15 +2825,15 @@ function validateTarget(target, workspaceRoot, workspaceListing, deniedPaths) {
     }
     return;
   }
-  const root = (0, import_node_path7.resolve)(workspaceRoot ?? ".");
-  const rel = (0, import_node_path7.relative)(root, (0, import_node_path7.resolve)(target.path));
-  if (rel.startsWith("..") || (0, import_node_path7.isAbsolute)(rel)) {
+  const root = (0, import_node_path9.resolve)(workspaceRoot ?? ".");
+  const rel = (0, import_node_path9.relative)(root, (0, import_node_path9.resolve)(target.path));
+  if (rel.startsWith("..") || (0, import_node_path9.isAbsolute)(rel)) {
     throw new Error(
       `pilot.targeting named a NEW_FILE path that escapes the workspace root: ${target.path}`
     );
   }
 }
-async function runTargeting(gateway, design, workspaceRoot, workspaceListing, requiredTests, deniedPaths, testDiscovery, outOfScope = []) {
+function buildContextData(design, workspaceListing, requiredTests, deniedPaths, testDiscovery, outOfScope) {
   const contextData = {
     // NESTED, NOT FLATTENED — a second vocabulary for the design shape is exactly what
     // QUIKTR-1034 cost.
@@ -2174,6 +2852,9 @@ async function runTargeting(gateway, design, workspaceRoot, workspaceListing, re
     contextData.outOfScope = outOfScope;
   }
   contextData.testDiscovery = testDiscovery;
+  return contextData;
+}
+async function postTargeting(gateway, contextData, signal) {
   const res = await fetchWithRetry(`${gateway.baseUrl}/ai/execute`, {
     method: "POST",
     headers: { "content-type": "application/json", "x-run-token": gateway.token },
@@ -2183,14 +2864,15 @@ async function runTargeting(gateway, design, workspaceRoot, workspaceListing, re
       expectedOutputType: "json",
       userPrompt: "",
       contextData
-    })
+    }),
+    ...signal ? { signal } : {}
   });
   if (!res.ok) {
-    throw new Error(`Targeting call failed: ${res.status} ${res.statusText}`);
+    throw new TargetingHttpError(res.status, res.statusText);
   }
-  const envelope = await res.json();
-  checkHardFailure(envelope, "pilot.targeting");
-  const body = unwrapExecute(envelope, "pilot.targeting");
+  return res.json();
+}
+function finalizeTargeting(body, workspaceRoot, workspaceListing, deniedPaths) {
   if (body.outcome === "NO_TARGET") {
     return { outcome: "NO_TARGET", reason: body.noTargetReason ?? null };
   }
@@ -2219,6 +2901,66 @@ async function runTargeting(gateway, design, workspaceRoot, workspaceListing, re
     ...correctedKinds.length > 0 ? { correctedKinds } : {}
   };
 }
+async function runSingleShot(gateway, design, workspaceRoot, workspaceListing, requiredTests, deniedPaths, testDiscovery, outOfScope = []) {
+  const contextData = buildContextData(design, workspaceListing, requiredTests, deniedPaths, testDiscovery, outOfScope);
+  const envelope = await postTargeting(gateway, contextData);
+  checkHardFailure(envelope, "pilot.targeting");
+  const body = unwrapExecute(envelope, "pilot.targeting");
+  return finalizeTargeting(body, workspaceRoot, workspaceListing, deniedPaths);
+}
+var CODE_LIKE = /^[A-Z0-9_]{1,40}$/;
+async function runTargeting(gateway, design, workspaceRoot, workspaceListing, requiredTests, deniedPaths, testDiscovery, outOfScope = [], options = {}) {
+  const mode = options.mode ?? resolveTargetingMode();
+  if (mode !== "loop") {
+    return runSingleShot(gateway, design, workspaceRoot, workspaceListing, requiredTests, deniedPaths, testDiscovery, outOfScope);
+  }
+  const baseContext = buildContextData(design, workspaceListing, requiredTests, deniedPaths, testDiscovery, outOfScope);
+  let summary;
+  let runtimeCode;
+  let reason;
+  try {
+    const looped = await runTargetingLoop(
+      { baseContext, listing: workspaceListing, deniedPaths },
+      { ...options.loopDeps, post: (contextData, signal) => postTargeting(gateway, contextData, signal) }
+    );
+    summary = looped.summary;
+    const result = finalizeTargeting(looped.body, workspaceRoot, workspaceListing, deniedPaths);
+    return { ...result, loop: summary };
+  } catch (err) {
+    if (err instanceof DeniedPathError || err instanceof SafetyRefusalError) throw err;
+    if (err instanceof LoopFailure) {
+      reason = err.reason;
+      runtimeCode = err.runtimeCode;
+      summary = err.summary ?? summary;
+    } else {
+      reason = "final_invalid";
+    }
+  }
+  const fellBack = {
+    turns: summary?.turns ?? 0,
+    toolCalls: summary?.toolCalls ?? 0,
+    readChars: summary?.readChars ?? 0,
+    refused: summary?.refused ?? 0,
+    reads: summary?.reads ?? [],
+    stopReason: "fallback",
+    fellBack: true,
+    fallbackReason: reason
+  };
+  const log = options.loopDeps?.log ?? ((e) => console.log(JSON.stringify(e)));
+  log({
+    event: "targeting.loop_fallback",
+    reason,
+    turn: fellBack.turns,
+    toolCalls: fellBack.toolCalls,
+    ...runtimeCode && CODE_LIKE.test(runtimeCode) ? { runtimeCode } : {}
+  });
+  const single = await runSingleShot(gateway, design, workspaceRoot, workspaceListing, requiredTests, deniedPaths, testDiscovery, outOfScope);
+  return {
+    ...single,
+    loop: fellBack,
+    warnings: [`QuikPilot's read-only targeting could not complete (${reason}); standard targeting was used instead.`]
+  };
+}
 
 // src/targetingRecord.ts
 var MAX_TARGETS = 25;
@@ -2228,9 +2970,11 @@ var MAX_ADDED_PATHS = 20;
 var MAX_SKIPPED_CONTEXT = 20;
 var MAX_SKIPPED_CASES = 200;
 var MAX_CONTEXT_RECORDS = 25;
-var MAX_PATH_CHARS = 300;
-var MAX_ID_CHARS = 100;
+var MAX_PATH_CHARS2 = 300;
+var MAX_ID_CHARS2 = 100;
 var MAX_REASON_CHARS = 300;
+var MAX_LOOP_READS = 50;
+var MAX_FALLBACK_REASON_CHARS = 40;
 function clampList(values, max, maxChars) {
   let cut = false;
   const kept = [];
@@ -2245,6 +2989,41 @@ function clampList(values, max, maxChars) {
   }
   return { kept, cut };
 }
+function wholeNumber(n) {
+  return typeof n === "number" && Number.isInteger(n) && n >= 0 ? n : 0;
+}
+function clampLoop(loop) {
+  let cut = false;
+  const reads = [];
+  for (const r of loop.reads ?? []) {
+    if (reads.length >= MAX_LOOP_READS) {
+      cut = true;
+      break;
+    }
+    const path = typeof r.path === "string" ? r.path.trim() : "";
+    if (path.length === 0 || path.length > MAX_PATH_CHARS2) {
+      cut = true;
+      continue;
+    }
+    reads.push({
+      path,
+      ...Number.isInteger(r.startLine) ? { startLine: r.startLine } : {},
+      ...Number.isInteger(r.endLine) ? { endLine: r.endLine } : {},
+      chars: wholeNumber(r.chars),
+      ...r.refused ? { refused: true } : {}
+    });
+  }
+  return {
+    turns: wholeNumber(loop.turns),
+    toolCalls: wholeNumber(loop.toolCalls),
+    refused: wholeNumber(loop.refused),
+    stopReason: loop.stopReason,
+    ...loop.fellBack ? { fellBack: true } : {},
+    ...loop.fallbackReason ? { fallbackReason: String(loop.fallbackReason).slice(0, MAX_FALLBACK_REASON_CHARS) } : {},
+    reads,
+    ...cut ? { truncated: true } : {}
+  };
+}
 function buildTargetingRecord(targeting, contextLog) {
   let truncated = false;
   const note = (cut) => {
@@ -2257,6 +3036,7 @@ function buildTargetingRecord(targeting, contextLog) {
       record2.noTargetReason = reason.slice(0, MAX_REASON_CHARS);
       if (reason.length > MAX_REASON_CHARS) record2.noTargetReasonTruncated = true;
     }
+    if (targeting.loop) record2.loop = clampLoop(targeting.loop);
     return record2;
   }
   const targets = [];
@@ -2266,12 +3046,12 @@ function buildTargetingRecord(targeting, contextLog) {
       break;
     }
     const path = typeof t.path === "string" ? t.path.trim() : "";
-    if (path.length === 0 || path.length > MAX_PATH_CHARS) {
+    if (path.length === 0 || path.length > MAX_PATH_CHARS2) {
       truncated = true;
       continue;
     }
-    const contextPaths = clampList(t.contextPaths, MAX_CONTEXT_PATHS, MAX_PATH_CHARS);
-    const automationIds = clampList(t.automationIds, MAX_IDS_PER_TARGET, MAX_ID_CHARS);
+    const contextPaths = clampList(t.contextPaths, MAX_CONTEXT_PATHS, MAX_PATH_CHARS2);
+    const automationIds = clampList(t.automationIds, MAX_IDS_PER_TARGET, MAX_ID_CHARS2);
     note(contextPaths.cut);
     note(automationIds.cut);
     targets.push({ path, kind: t.kind, contextPaths: contextPaths.kept, automationIds: automationIds.kept });
@@ -2279,7 +3059,7 @@ function buildTargetingRecord(targeting, contextLog) {
   const skipped = clampList(
     (targeting.skippedCases ?? []).map((c) => c.automationId),
     MAX_SKIPPED_CASES,
-    MAX_ID_CHARS
+    MAX_ID_CHARS2
   );
   note(skipped.cut);
   const codegenContext = [];
@@ -2289,16 +3069,16 @@ function buildTargetingRecord(targeting, contextLog) {
       break;
     }
     const targetPath = typeof entry.targetPath === "string" ? entry.targetPath.trim() : "";
-    if (targetPath.length === 0 || targetPath.length > MAX_PATH_CHARS) {
+    if (targetPath.length === 0 || targetPath.length > MAX_PATH_CHARS2) {
       truncated = true;
       continue;
     }
-    const contextPaths = clampList(entry.contextPaths, MAX_CONTEXT_PATHS, MAX_PATH_CHARS);
-    const addedPaths = clampList(entry.addedPaths, MAX_ADDED_PATHS, MAX_PATH_CHARS);
+    const contextPaths = clampList(entry.contextPaths, MAX_CONTEXT_PATHS, MAX_PATH_CHARS2);
+    const addedPaths = clampList(entry.addedPaths, MAX_ADDED_PATHS, MAX_PATH_CHARS2);
     const skippedPaths = clampList(
       (entry.skipped ?? []).map((s) => s.path),
       MAX_SKIPPED_CONTEXT,
-      MAX_PATH_CHARS
+      MAX_PATH_CHARS2
     );
     note(contextPaths.cut);
     note(addedPaths.cut);
@@ -2319,6 +3099,7 @@ function buildTargetingRecord(targeting, contextLog) {
     codegenContext
   };
   if (truncated) record.truncated = true;
+  if (targeting.loop) record.loop = clampLoop(targeting.loop);
   return record;
 }
 
@@ -2431,6 +3212,10 @@ async function run(env2) {
       outOfScope
     );
     targetingResult = targeting;
+    for (const w of targeting.warnings ?? []) {
+      warnings.push(w);
+      console.warn(`QuikPilot targeting warning (not blocking): ${w}`);
+    }
     if (targeting.outcome === "TARGETED") {
       for (const path of targeting.correctedKinds ?? []) {
         const w = `QuikPilot named ${path} as a new file, but it already exists in the repository. It was treated as an existing file so its current content was kept in view.`;