squad-kit 0.7.2 → 0.9.0

package/dist/cli.js

@@ -163,8 +163,8 @@ ${body}
 }
 
 // src/ui/error.ts
-function renderError(err) {
-  const msg = err instanceof Error ? err.message : String(err);
+function renderError(err2) {
+  const msg = err2 instanceof Error ? err2.message : String(err2);
   process.stderr.write(`  ${danger("\u2717")} ${msg}
 `);
 }
@@ -178,8 +178,8 @@ var SquadExit = class extends Error {
   exitCode;
   name = "SquadExit";
 };
-function isSquadExit(err) {
-  return err instanceof SquadExit;
+function isSquadExit(err2) {
+  return err2 instanceof SquadExit;
 }
 
 // src/commands/init.ts
@@ -303,15 +303,15 @@ function clampPlannerMaxOut(raw) {
     Math.max(MIN_PLANNER_MAX_OUTPUT_TOKENS, Math.round(n))
   );
 }
-function rejectSecretsInYaml(node, configFile, path34 = []) {
+function rejectSecretsInYaml(node, configFile, path38 = []) {
   if (node === null || typeof node !== "object") return;
   for (const [key, value] of Object.entries(node)) {
     if (FORBIDDEN_KEYS.includes(key.toLowerCase())) {
       throw new Error(
-        `Refusing to load ${configFile}: key "${[...path34, key].join(".")}" looks like a secret. Run \`squad config set planner\` or \`squad config set tracker\` to save it to .squad/secrets.yaml, then remove the key from config.yaml. Provider keys also work via ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY.`
+        `Refusing to load ${configFile}: key "${[...path38, key].join(".")}" looks like a secret. Run \`squad config set planner\` or \`squad config set tracker\` to save it to .squad/secrets.yaml, then remove the key from config.yaml. Provider keys also work via ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY.`
       );
     }
-    if (typeof value === "object") rejectSecretsInYaml(value, configFile, [...path34, key]);
+    if (typeof value === "object") rejectSecretsInYaml(value, configFile, [...path38, key]);
   }
 }
 function mergePlanner(base, override) {
@@ -323,8 +323,7 @@ function mergePlanner(base, override) {
     budget: {
       maxFileReads: override.budget?.maxFileReads ?? base?.budget?.maxFileReads ?? 25,
       maxContextBytes: override.budget?.maxContextBytes ?? base?.budget?.maxContextBytes ?? 5e4,
-      maxDurationSeconds: override.budget?.maxDurationSeconds ?? base?.budget?.maxDurationSeconds ?? 180,
-      maxCostUsd: override.budget?.maxCostUsd ?? base?.budget?.maxCostUsd
+      maxDurationSeconds: override.budget?.maxDurationSeconds ?? base?.budget?.maxDurationSeconds ?? 180
     },
     modelOverride: {
       ...base?.modelOverride ?? {},
@@ -333,7 +332,24 @@ function mergePlanner(base, override) {
     cache: {
       enabled: override.cache?.enabled ?? base?.cache?.enabled ?? true
     },
-    maxOutputTokens: clampPlannerMaxOut(override.maxOutputTokens ?? base?.maxOutputTokens)
+    maxOutputTokens: clampPlannerMaxOut(override.maxOutputTokens ?? base?.maxOutputTokens),
+    stages: {
+      scout: {
+        enabled: override.stages?.scout?.enabled ?? base?.stages?.scout?.enabled ?? true,
+        modelOverride: override.stages?.scout?.modelOverride ?? base?.stages?.scout?.modelOverride,
+        maxFiles: override.stages?.scout?.maxFiles ?? base?.stages?.scout?.maxFiles ?? 12,
+        maxOutputTokens: override.stages?.scout?.maxOutputTokens ?? base?.stages?.scout?.maxOutputTokens ?? 2048
+      }
+    },
+    tools: {
+      grep: override.tools?.grep ?? base?.tools?.grep ?? true,
+      listDir: override.tools?.listDir ?? base?.tools?.listDir ?? true,
+      rangedRead: override.tools?.rangedRead ?? base?.tools?.rangedRead ?? true
+    },
+    validation: {
+      enabled: override.validation?.enabled ?? base?.validation?.enabled ?? true,
+      strict: override.validation?.strict ?? base?.validation?.strict ?? false
+    }
   };
   if (merged.modelOverride) {
     const pruned = Object.fromEntries(
@@ -363,9 +379,9 @@ function parseConfig(raw, configFile) {
   let parsed;
   try {
     parsed = yaml.load(raw);
-  } catch (err) {
+  } catch (err2) {
     throw new Error(
-      `Invalid YAML in ${configFile}: ${err.message}. Run \`squad doctor\` to review, or fix the file, or \`squad init --force\` to replace it.`
+      `Invalid YAML in ${configFile}: ${err2.message}. Run \`squad doctor\` to review, or fix the file, or \`squad init --force\` to replace it.`
     );
   }
   if (!parsed || typeof parsed !== "object") {
@@ -450,17 +466,17 @@ function loadSecrets(secretsFile) {
   let raw;
   try {
     raw = fs4.readFileSync(secretsFile, "utf8");
-  } catch (err) {
+  } catch (err2) {
     throw new Error(
-      `Failed to read ${secretsFile}: ${err.message}. Run \`squad doctor\` to diagnose, or delete the file and run \`squad config set planner\` or \`squad config set tracker\` to re-enter credentials.`
+      `Failed to read ${secretsFile}: ${err2.message}. Run \`squad doctor\` to diagnose, or delete the file and run \`squad config set planner\` or \`squad config set tracker\` to re-enter credentials.`
     );
   }
   let parsed;
   try {
     parsed = yaml2.load(raw);
-  } catch (err) {
+  } catch (err2) {
     throw new Error(
-      `Invalid YAML in ${secretsFile}: ${err.message}. Run \`squad doctor\` to review paths and permissions, or fix the file, or delete it and run \`squad config set planner\` / \`squad config set tracker\` to re-enter secrets.`
+      `Invalid YAML in ${secretsFile}: ${err2.message}. Run \`squad doctor\` to review paths and permissions, or fix the file, or delete it and run \`squad config set planner\` / \`squad config set tracker\` to re-enter secrets.`
     );
   }
   if (parsed === null || parsed === void 0) return EMPTY;
@@ -515,21 +531,25 @@ function filterEmpty(obj) {
 var PLANNER_MODEL_MAP = {
   anthropic: {
     plan: "claude-opus-4-7",
-    execute: "claude-haiku-4-5-20251001"
+    execute: "claude-haiku-4-5-20251001",
+    scout: "claude-haiku-4-5-20251001"
   },
   openai: {
     // Unverified for 0.2.0. 0.2.1 will pin to dated snapshots once a maintainer can probe.
     plan: "gpt-5.3-thinking",
-    execute: "gpt-5.3-mini"
+    execute: "gpt-5.3-mini",
+    scout: "gpt-5.3-mini"
   },
   google: {
     // Unverified for 0.2.0. 0.2.1 will pin to dated snapshots once a maintainer can probe.
     plan: "gemini-3-pro-latest",
-    execute: "gemini-3-flash-latest"
+    execute: "gemini-3-flash-latest",
+    scout: "gemini-3-flash-latest"
   }
 };
-function modelFor(provider, phase, override) {
+function modelFor(provider, phase, override, scoutModelId) {
   if (phase === "plan" && override?.[provider]) return override[provider];
+  if (phase === "scout" && scoutModelId?.trim()) return scoutModelId.trim();
   return PLANNER_MODEL_MAP[provider][phase];
 }
 function providerEnvVar(provider) {
@@ -850,8 +870,8 @@ async function probeJiraConnectivity(secrets, config2) {
     });
     if (res.ok) return { ok: true };
     return { ok: false, status: res.status, detail: (await res.text()).slice(0, 200) };
-  } catch (err) {
-    return { ok: false, detail: err.message };
+  } catch (err2) {
+    return { ok: false, detail: err2.message };
   }
 }
 async function probeAzureConnectivity(secrets, config2) {
@@ -864,8 +884,8 @@ async function probeAzureConnectivity(secrets, config2) {
     const res = await fetch(url, { headers: { Authorization: `Basic ${auth}` } });
     if (res.ok) return { ok: true };
     return { ok: false, status: res.status, detail: (await res.text()).slice(0, 200) };
-  } catch (err) {
-    return { ok: false, detail: err.message };
+  } catch (err2) {
+    return { ok: false, detail: err2.message };
   }
 }
 async function probeGitHubConnectivity(secrets, _config) {
@@ -885,8 +905,8 @@ async function probeGitHubConnectivity(secrets, _config) {
     });
     if (res.ok) return { ok: true };
     return { ok: false, status: res.status, detail: (await res.text()).slice(0, 200) };
-  } catch (err) {
-    return { ok: false, detail: err.message };
+  } catch (err2) {
+    return { ok: false, detail: err2.message };
   }
 }
 
@@ -1211,12 +1231,12 @@ async function one(ref, targetDir, headers, maxBytes, maxMb) {
   let res;
   try {
     res = await fetch(ref.url, { headers });
-  } catch (err) {
+  } catch (err2) {
     return {
       source: ref,
       outcome: "skipped-error",
       bytesWritten: 0,
-      skipReason: `network error: ${err.message}`
+      skipReason: `network error: ${err2.message}`
     };
   }
   if (!res.ok) {
@@ -1318,8 +1338,8 @@ var AzureDevOpsClient = class {
         headers: { ...this.headers(), "content-type": "application/json" },
         body: JSON.stringify({ query: `${wiql}` })
       });
-    } catch (err) {
-      throw new TrackerError(`Azure DevOps search failed: ${err.message}`, "network");
+    } catch (err2) {
+      throw new TrackerError(`Azure DevOps search failed: ${err2.message}`, "network");
     }
     if (!wiqlRes.ok) throw this.mapHttpError(wiqlRes.status, "search");
     const wiqlBody = await wiqlRes.json();
@@ -1329,8 +1349,8 @@ var AzureDevOpsClient = class {
     let batchRes;
     try {
       batchRes = await fetch(batchUrl, { headers: this.headers() });
-    } catch (err) {
-      throw new TrackerError(`Azure DevOps work items fetch failed: ${err.message}`, "network");
+    } catch (err2) {
+      throw new TrackerError(`Azure DevOps work items fetch failed: ${err2.message}`, "network");
     }
     if (!batchRes.ok) throw this.mapHttpError(batchRes.status, "search");
     const batchBody = await batchRes.json();
@@ -1352,8 +1372,8 @@ var AzureDevOpsClient = class {
     let res;
     try {
       res = await fetch(url, { headers: this.headers() });
-    } catch (err) {
-      throw new TrackerError(`Azure DevOps fetch failed: ${err.message}`, "network");
+    } catch (err2) {
+      throw new TrackerError(`Azure DevOps fetch failed: ${err2.message}`, "network");
     }
     if (!res.ok) throw this.mapHttpError(res.status, id);
     const body = await res.json();
@@ -1459,8 +1479,8 @@ var GitHubClient = class {
     let res;
     try {
       res = await fetch(url, { headers: this.headers() });
-    } catch (err) {
-      throw new TrackerError(`GitHub fetch failed: ${err.message}`, "network");
+    } catch (err2) {
+      throw new TrackerError(`GitHub fetch failed: ${err2.message}`, "network");
     }
     if (!res.ok) throw this.mapHttpError(res, number);
     const body = await res.json();
@@ -1475,8 +1495,8 @@ var GitHubClient = class {
       let res2;
       try {
         res2 = await fetch(url2, { headers: this.headers() });
-      } catch (err) {
-        throw new TrackerError(`GitHub search failed: ${err.message}`, "network");
+      } catch (err2) {
+        throw new TrackerError(`GitHub search failed: ${err2.message}`, "network");
       }
       if (!res2.ok) throw this.mapHttpError(res2, "search");
       const body2 = await res2.json();
@@ -1494,9 +1514,9 @@ var GitHubClient = class {
             url: issue.url
           }
         ];
-      } catch (err) {
-        if (err instanceof TrackerError && err.kind === "not-found") return [];
-        throw err;
+      } catch (err2) {
+        if (err2 instanceof TrackerError && err2.kind === "not-found") return [];
+        throw err2;
       }
     }
     const searchQuery = `${q} repo:${this.cfg.owner}/${this.cfg.repo}`;
@@ -1504,8 +1524,8 @@ var GitHubClient = class {
     let res;
     try {
       res = await fetch(url, { headers: this.headers() });
-    } catch (err) {
-      throw new TrackerError(`GitHub search failed: ${err.message}`, "network");
+    } catch (err2) {
+      throw new TrackerError(`GitHub search failed: ${err2.message}`, "network");
     }
     if (!res.ok) throw this.mapHttpError(res, "search");
     const body = await res.json();
@@ -1645,10 +1665,13 @@ var JiraClient = class {
     let res;
     try {
       res = await fetch(url, { headers: this.headers() });
-    } catch (err) {
-      throw new TrackerError(`Jira fetch failed: ${err.message}`, "network");
+    } catch (err2) {
+      throw new TrackerError(`Jira fetch failed: ${err2.message}`, "network");
+    }
+    if (!res.ok) {
+      const errBody = await res.text().catch(() => "");
+      throw this.mapHttpError(res.status, id, errBody);
     }
-    if (!res.ok) throw this.mapHttpError(res.status, id);
     const body = await res.json();
     const fields = body.fields ?? {};
     const rendered = body.renderedFields ?? {};
@@ -1680,19 +1703,22 @@ var JiraClient = class {
     if (/^[A-Z][A-Z0-9_]+-\d+$/i.test(q)) {
       jql = `issuekey = "${q.toUpperCase()}"`;
     } else if (q.length === 0) {
-      jql = "order by updated DESC";
+      jql = "updated >= -90d ORDER BY updated DESC";
     } else {
       const esc = q.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
       jql = `text ~ "${esc}" order by updated DESC`;
     }
-    const url = `${this.baseUrl}/rest/api/3/search?jql=${encodeURIComponent(jql)}&fields=summary,status,issuetype&maxResults=${limit}`;
+    const url = `${this.baseUrl}/rest/api/3/search/jql?jql=${encodeURIComponent(jql)}&fields=summary,status,issuetype&maxResults=${limit}`;
     let res;
     try {
       res = await fetch(url, { headers: this.headers() });
-    } catch (err) {
-      throw new TrackerError(`Jira search failed: ${err.message}`, "network");
+    } catch (err2) {
+      throw new TrackerError(`Jira search failed: ${err2.message}`, "network");
+    }
+    if (!res.ok) {
+      const errBody = await res.text().catch(() => "");
+      throw this.mapHttpError(res.status, "search", errBody);
     }
-    if (!res.ok) throw this.mapHttpError(res.status, "search");
     const body = await res.json();
     const issues = body.issues ?? [];
     return issues.map((it) => {
@@ -1716,7 +1742,7 @@ var JiraClient = class {
       accept: "application/json"
     };
   }
-  mapHttpError(status, id) {
+  mapHttpError(status, id, body = "") {
     if (status === 401 || status === 403) {
       return new TrackerError(
         `Jira authentication failed (HTTP ${status}). Check your email and API token in .squad/secrets.yaml.`,
@@ -1734,16 +1760,44 @@ var JiraClient = class {
     if (status === 429) {
       return new TrackerError(`Jira rate limit hit (HTTP 429). Wait a minute and retry.`, "rate-limited", status);
     }
-    return new TrackerError(
-      id === "search" ? `Jira search failed (HTTP ${status}).` : `Jira request failed (HTTP ${status}).`,
-      "other",
-      status
-    );
+    if (status === 410) {
+      return new TrackerError(
+        id === "search" ? `Jira search endpoint has been removed by Atlassian (HTTP 410). squad-kit must call /rest/api/3/search/jql instead \u2014 upgrade squad-kit to a version that includes this fix.` : `Jira endpoint has been removed by Atlassian (HTTP 410). Upgrade squad-kit to a version that calls the current Jira Cloud REST API.`,
+        "other",
+        status
+      );
+    }
+    const reason = extractJiraErrorMessages(body);
+    const base = id === "search" ? `Jira search failed (HTTP ${status}).` : `Jira request failed (HTTP ${status}).`;
+    return new TrackerError(reason ? `${base} ${reason}` : base, "other", status);
   }
 };
 function stripHtml2(html) {
   return html.replace(/<\s*br\s*\/?>/gi, "\n").replace(/<\/(p|div|li|h[1-6])>/gi, "\n\n").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/\n{3,}/g, "\n\n").trim();
 }
+function extractJiraErrorMessages(body) {
+  if (!body) return "";
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return body.slice(0, 200);
+  }
+  const messages = [];
+  if (Array.isArray(parsed.errorMessages)) {
+    for (const m of parsed.errorMessages) {
+      if (typeof m === "string" && m.trim().length > 0) messages.push(m.trim());
+    }
+  }
+  if (parsed.errors && typeof parsed.errors === "object") {
+    for (const [k, v] of Object.entries(parsed.errors)) {
+      if (typeof v === "string" && v.trim().length > 0) messages.push(`${k}: ${v.trim()}`);
+    }
+  }
+  if (messages.length === 0) return "";
+  const joined = messages.join(" ");
+  return joined.length > 200 ? `${joined.slice(0, 197)}...` : joined;
+}
 
 // src/tracker/index.ts
 function clientFor(config2, secrets) {
@@ -3101,12 +3155,12 @@ async function tryFetchIssue(config2, id, opts, paths, attachmentsDir) {
   let issue;
   try {
     issue = await client.fetchIssue(id);
-  } catch (err) {
+  } catch (err2) {
     spin.fail("Tracker fetch failed");
-    if (err instanceof TrackerError) {
-      return { outcome: "failed", reason: err.message, hint: explainTrackerErrorHint(err) };
+    if (err2 instanceof TrackerError) {
+      return { outcome: "failed", reason: err2.message, hint: explainTrackerErrorHint(err2) };
     }
-    return { outcome: "failed", reason: err.message };
+    return { outcome: "failed", reason: err2.message };
   }
   spin.succeed(`Fetched ${issue.id}: ${truncate(issue.title, 60)}`);
   let downloads = [];
@@ -3128,8 +3182,8 @@ async function tryFetchIssue(config2, id, opts, paths, attachmentsDir) {
   }
   return { outcome: "ok", issue, downloads };
 }
-function explainTrackerErrorHint(err) {
-  switch (err.kind) {
+function explainTrackerErrorHint(err2) {
+  switch (err2.kind) {
     case "auth":
       return "Run `squad config set tracker` to re-enter credentials, or `squad doctor` to verify.";
     case "not-found":
@@ -3147,8 +3201,8 @@ function truncate(s, n) {
 }
 
 // src/commands/new-plan.ts
-import fs26 from "fs";
-import path19 from "path";
+import fs31 from "fs";
+import path23 from "path";
 import { confirm as confirm6, select as select6 } from "@inquirer/prompts";
 
 // src/utils/clipboard.ts
@@ -3176,16 +3230,16 @@ function tryCopy(cmd, text) {
     let child;
     try {
       child = spawn(cmd.command, cmd.args, { stdio: ["pipe", "ignore", "pipe"] });
-    } catch (err) {
-      resolve2({ ok: false, reason: `${cmd.command} failed to spawn: ${err.message}` });
+    } catch (err2) {
+      resolve2({ ok: false, reason: `${cmd.command} failed to spawn: ${err2.message}` });
       return;
     }
     let stderr = "";
     child.stderr?.on("data", (chunk) => {
       stderr += chunk.toString();
     });
-    child.on("error", (err) => {
-      resolve2({ ok: false, reason: `${cmd.command} spawn error: ${err.message}` });
+    child.on("error", (err2) => {
+      resolve2({ ok: false, reason: `${cmd.command} spawn error: ${err2.message}` });
     });
     child.on("close", (code) => {
       if (code === 0) {
@@ -3240,63 +3294,189 @@ function noCandidateReason() {
 }
 
 // src/planner/loop.ts
-import path15 from "path";
+import path19 from "path";
+import fs27 from "fs";
+import { APICallError as APICallError2 } from "ai";
 
-// src/planner/tools.ts
+// src/planner/tools/read-file.ts
 import fs21 from "fs";
 import path13 from "path";
-var READ_FILE_TOOL = {
-  name: "read_file",
-  description: "Read a UTF-8 text file from the project, returning its contents so you can plan against real code. Paths must be relative to the project root. Binary files and files outside the project are refused. You have a bounded context budget; prefer small, targeted reads.",
-  inputSchema: {
-    type: "object",
-    additionalProperties: false,
-    required: ["path"],
-    properties: {
-      path: { type: "string", description: "Repo-relative POSIX path." }
-    }
-  }
-};
-var MAX_BYTES_PER_READ = 32e3;
+import { tool } from "ai";
+import { z } from "zod";
+var READ_FILE_TOOL_NAME = "read_file";
+var MAX_BYTES_PER_FULL_READ = 32e3;
+var MAX_LINES_PER_RANGED_READ = 400;
+var MAX_BYTES_FOR_SYNC_LINE_SPLIT = 2e6;
 function readFileTool(root, budget, input5) {
-  const raw = input5?.path;
-  if (typeof raw !== "string" || raw.length === 0) {
-    return error('read_file: missing or invalid "path" argument.');
+  const raw = typeof input5.path === "string" ? input5.path : "";
+  if (!raw.length) {
+    return err('read_file: missing or invalid "path" argument.');
+  }
+  const offset = typeof input5.offset === "number" && Number.isInteger(input5.offset) ? input5.offset : void 0;
+  const limit = typeof input5.limit === "number" && Number.isInteger(input5.limit) ? input5.limit : void 0;
+  if (offset !== void 0 && offset < 1) {
+    return err("read_file: offset must be a 1-indexed line number \u2265 1.");
+  }
+  if (limit !== void 0 && (limit < 1 || limit > MAX_LINES_PER_RANGED_READ)) {
+    return err(`read_file: limit must be between 1 and ${MAX_LINES_PER_RANGED_READ}.`);
+  }
+  if (offset === void 0 !== (limit === void 0)) {
+    return err("read_file: pass both offset and limit for a ranged read, or neither for a full read.");
   }
   const resolved = path13.resolve(root, raw);
   const relCheck = path13.relative(root, resolved);
   if (relCheck.startsWith("..") || path13.isAbsolute(relCheck)) {
-    return error(`read_file: path "${raw}" escapes the project root and was refused.`);
+    return err(`read_file: path "${raw}" escapes the project root and was refused.`);
   }
   if (!fs21.existsSync(resolved)) {
-    return error(`read_file: not found "${raw}".`);
+    return err(`read_file: not found "${raw}".`);
   }
   const stat = fs21.statSync(resolved);
   if (stat.isDirectory()) {
-    return error(`read_file: "${raw}" is a directory. Ask for a specific file path.`);
+    return err(`read_file: "${raw}" is a directory. Ask for a specific file path.`);
   }
-  if (stat.size > MAX_BYTES_PER_READ) {
-    return error(
-      `read_file: "${raw}" is ${stat.size} bytes (> ${MAX_BYTES_PER_READ}). Ask for a smaller file or a specific range.`
+  if (offset !== void 0 && limit !== void 0) {
+    return readFileRanged(resolved, raw, budget, stat.size, offset, limit);
+  }
+  if (stat.size > MAX_BYTES_PER_FULL_READ) {
+    return err(
+      `read_file: "${raw}" is ${stat.size} bytes (> ${MAX_BYTES_PER_FULL_READ}). Use offset/limit for a ranged read or ask for a smaller region.`
     );
   }
   const capacity = budget.canRead(stat.size);
   if (!capacity.ok) {
-    return error(`read_file: ${capacity.reason}. Finalise the plan with what you already have.`);
+    return err(`read_file: ${capacity.reason}. Finalise the plan with what you already have.`);
   }
   let buf;
   try {
     buf = fs21.readFileSync(resolved);
   } catch (e) {
-    return error(`read_file: failed to read "${raw}" (${e.message}).`);
+    return err(`read_file: failed to read "${raw}" (${e.message}).`);
   }
   if (looksBinary(buf)) {
-    return error(`read_file: "${raw}" looks binary and was refused.`);
+    return err(`read_file: "${raw}" looks binary and was refused.`);
   }
   budget.recordRead(stat.size);
   return { content: buf.toString("utf8"), isError: false };
 }
-function error(msg) {
+function readFileRanged(resolved, rawRel, budget, fileSize, offset, limit) {
+  const est = Math.min(fileSize, limit * 200);
+  const cap = budget.canRead(est);
+  if (!cap.ok) {
+    return err(`read_file: ${cap.reason}. Finalise the plan with what you already have.`);
+  }
+  if (fileSize > MAX_BYTES_FOR_SYNC_LINE_SPLIT) {
+    return err(
+      `read_file: "${rawRel}" is too large for a ranged read in-process (${fileSize} bytes). Grep for a symbol or narrow the path.`
+    );
+  }
+  let data;
+  try {
+    data = fs21.readFileSync(resolved);
+  } catch (e) {
+    return err(`read_file: failed to read "${rawRel}" (${e.message}).`);
+  }
+  if (looksBinary(data)) {
+    return err(`read_file: "${rawRel}" looks binary and was refused.`);
+  }
+  const text = data.toString("utf8");
+  const lines = text.split(/\r?\n/);
+  if (offset > lines.length) {
+    return err(
+      `read_file: offset ${offset} is past the end of the file (only ${lines.length} lines).`
+    );
+  }
+  const slice = lines.slice(offset - 1, offset - 1 + limit);
+  const out = slice.map((line2, i) => `${String(offset + i).padStart(6, " ")}\u2502 ${line2}`).join("\n");
+  const bytes = Buffer.byteLength(out, "utf8");
+  budget.recordRead(bytes);
+  return { content: out, isError: false };
+}
+function readFileToolFactory(root, budget, hooks, opts) {
+  const ranged = opts?.ranged ?? true;
+  const params = ranged ? z.object({
+    path: z.string().min(1).describe("Repo-relative POSIX path."),
+    offset: z.number().int().min(1).optional().describe("1-indexed line number to start reading at (use with limit)."),
+    limit: z.number().int().min(1).max(MAX_LINES_PER_RANGED_READ).optional().describe(`Line count from offset (max ${MAX_LINES_PER_RANGED_READ}).`)
+  }).refine(
+    (o) => o.offset === void 0 && o.limit === void 0 || o.offset !== void 0 && o.limit !== void 0,
+    { message: "Provide both offset and limit for a ranged read, or neither for a full read." }
+  ) : z.object({
+    path: z.string().min(1).describe("Repo-relative POSIX path.")
+  });
+  return tool({
+    description: "Read a UTF-8 text file from the project, returning its contents so you can plan against real code. " + (ranged ? "Pass `offset` and `limit` together to read a line range (preferred when you know the region). Without them the whole file is read, capped at 32 KB. " : "Whole-file reads only; capped at 32 KB. ") + "Paths must be relative to the project root. Binary files are refused. You have a bounded context budget; prefer small, targeted reads.",
+    parameters: params,
+    execute: async (args, { toolCallId }) => {
+      const tc = {
+        id: toolCallId,
+        name: READ_FILE_TOOL_NAME,
+        input: { path: args.path, offset: args.offset, limit: args.limit }
+      };
+      const before = budget.snapshot().bytes;
+      let result = readFileTool(root, budget, args);
+      let after = budget.snapshot().bytes;
+      let bytesLoaded = after - before;
+      hooks.onToolCall?.(tc, bytesLoaded, after);
+      hooks.bus.emit({
+        kind: "tool_call",
+        runId: hooks.runId,
+        turn: hooks.turn,
+        toolCall: tc,
+        bytesLoaded,
+        totalBytes: after
+      });
+      if (readBudgetishError(result)) {
+        const decide = hooks.decideOnLimit;
+        if (decide) {
+          const d = await decide(hooks.getLimitCtx());
+          if (d === "cancel") {
+            throw new PlannerUserCancelledError(
+              hooks.getAccumulatedText(),
+              hooks.runId,
+              hooks.turn,
+              "budget_reads",
+              tc,
+              result
+            );
+          }
+          hooks.extendSessionLimits();
+          result = readFileTool(root, budget, args);
+          after = budget.snapshot().bytes;
+          bytesLoaded = after - before;
+        } else {
+          hooks.setBudgetExhausted(true);
+        }
+      }
+      return { content: result.content, isError: result.isError };
+    }
+  });
+}
+var PlannerUserCancelledError = class _PlannerUserCancelledError extends Error {
+  constructor(planText, runId, turn, incompleteKind, toolCall, pendingResult) {
+    super("PlannerUserCancelledError");
+    this.planText = planText;
+    this.runId = runId;
+    this.turn = turn;
+    this.incompleteKind = incompleteKind;
+    this.toolCall = toolCall;
+    this.pendingResult = pendingResult;
+    this.name = "PlannerUserCancelledError";
+  }
+  planText;
+  runId;
+  turn;
+  incompleteKind;
+  toolCall;
+  pendingResult;
+  static is(e) {
+    return e instanceof _PlannerUserCancelledError;
+  }
+};
+function readBudgetishError(result) {
+  return result.isError && (/budget/i.test(result.content) || /max file reads/i.test(result.content));
+}
+function err(msg) {
   return { content: msg, isError: true };
 }
 function looksBinary(buf) {
@@ -3307,6 +3487,436 @@ function looksBinary(buf) {
   return false;
 }
 
+// src/planner/tools/grep.ts
+import fs23 from "fs";
+import path15 from "path";
+import { tool as tool2 } from "ai";
+import { z as z2 } from "zod";
+
+// src/core/repo-map.ts
+import fs22 from "fs";
+import path14 from "path";
+import ignore from "ignore";
+var DEFAULT_IGNORES = [
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+  ".squad/plans"
+  // don't include existing plans as context; planner will see them separately
+];
+function buildRepoIgnore(root) {
+  const ig = ignore().add(DEFAULT_IGNORES);
+  const gitignore = path14.join(root, ".gitignore");
+  if (fs22.existsSync(gitignore)) {
+    try {
+      ig.add(fs22.readFileSync(gitignore, "utf8"));
+    } catch {
+    }
+  }
+  return ig;
+}
+function buildRepoMap(root, opts = {}) {
+  const maxEntries = opts.maxEntries ?? 5e3;
+  const format = opts.format ?? "flat";
+  const ig = buildRepoIgnore(root);
+  if (format === "tree") {
+    const entries2 = [];
+    collectFileEntries(root, root, ig, entries2, maxEntries, !!opts.includeHidden);
+    entries2.sort((a, b) => a.rel.localeCompare(b.rel));
+    return renderRepoTree(entries2) + "\n";
+  }
+  const entries = [];
+  walkFlat(root, root, ig, entries, maxEntries, !!opts.includeHidden);
+  entries.sort();
+  return entries.join("\n") + "\n";
+}
+function formatSizeKb(n) {
+  if (n < 1024) return `${n} B`;
+  return `${(n / 1024).toFixed(1)} KB`;
+}
+function insertTree(tree, relParts, size) {
+  if (relParts.length === 1) {
+    tree.files.push({ name: relParts[0], size });
+    return;
+  }
+  const [head, ...rest] = relParts;
+  if (!tree.dirs.has(head)) tree.dirs.set(head, { files: [], dirs: /* @__PURE__ */ new Map() });
+  insertTree(tree.dirs.get(head), rest, size);
+}
+function renderDirTree(name, tree, depth) {
+  const lines = [];
+  const indent = "  ".repeat(depth);
+  if (name) {
+    lines.push(`${indent}${name}/`);
+  }
+  const innerIndent = "  ".repeat(name ? depth + 1 : depth);
+  const dirNames = [...tree.dirs.keys()].sort((a, b) => a.localeCompare(b));
+  for (const d of dirNames) {
+    lines.push(...renderDirTree(d, tree.dirs.get(d), name ? depth + 1 : depth));
+  }
+  tree.files.sort((a, b) => a.name.localeCompare(b.name));
+  for (const f of tree.files) {
+    const left = `${innerIndent}${f.name}`;
+    const pad2 = Math.max(1, 48 - left.length);
+    lines.push(`${left}${" ".repeat(pad2)}${formatSizeKb(f.size)}`);
+  }
+  return lines;
+}
+function renderRepoTree(entries) {
+  const root = { files: [], dirs: /* @__PURE__ */ new Map() };
+  for (const e of entries) {
+    const parts = e.rel.split(path14.sep).filter(Boolean);
+    if (parts.length === 0) continue;
+    insertTree(root, parts, e.size);
+  }
+  return renderDirTree("", root, 0).join("\n");
+}
+function collectFileEntries(root, dir, ig, out, max, includeHidden) {
+  if (out.length >= max) return out;
+  let dirents;
+  try {
+    dirents = fs22.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of dirents) {
+    if (out.length >= max) break;
+    if (!includeHidden && entry.name.startsWith(".") && entry.name !== ".squad") continue;
+    const abs = path14.join(dir, entry.name);
+    const rel = path14.relative(root, abs);
+    if (!rel || ig.ignores(rel) || entry.isDirectory() && ig.ignores(rel + "/")) continue;
+    if (entry.isDirectory()) {
+      collectFileEntries(root, abs, ig, out, max, includeHidden);
+    } else if (entry.isFile()) {
+      let size = 0;
+      try {
+        size = fs22.statSync(abs).size;
+      } catch {
+        size = 0;
+      }
+      out.push({ rel: rel.split(path14.sep).join("/"), size });
+    }
+  }
+  return out;
+}
+function walkFlat(root, dir, ig, out, max, includeHidden) {
+  if (out.length >= max) return;
+  let entries;
+  try {
+    entries = fs22.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (out.length >= max) return;
+    if (!includeHidden && entry.name.startsWith(".") && entry.name !== ".squad") continue;
+    const abs = path14.join(dir, entry.name);
+    const rel = path14.relative(root, abs);
+    if (!rel || ig.ignores(rel) || entry.isDirectory() && ig.ignores(rel + "/")) continue;
+    if (entry.isDirectory()) {
+      walkFlat(root, abs, ig, out, max, includeHidden);
+    } else if (entry.isFile()) {
+      out.push(rel.split(path14.sep).join("/"));
+    }
+  }
+}
+
+// src/planner/tools/grep.ts
+var MAX_GREP_MATCHES = 200;
+var MAX_GREP_FILE_SIZE_BYTES = 1e6;
+var GREP_TOOL_NAME = "grep";
+function grepToolFactory(root, budget, hooks) {
+  return tool2({
+    description: "Search the project for a literal string or regex pattern. Returns up to 200 matches across files, each shown as `path:line:match`. Use this BEFORE `read_file` to locate symbols or call sites; it is much cheaper than reading whole files.",
+    parameters: z2.object({
+      pattern: z2.string().min(1).describe("Literal string or regex (default literal)."),
+      regex: z2.boolean().optional().default(false),
+      path: z2.string().optional().describe("Optional sub-path to scope the search to (relative)."),
+      caseInsensitive: z2.boolean().optional().default(false)
+    }),
+    execute: async (args, { toolCallId }) => {
+      const tc = {
+        id: toolCallId,
+        name: GREP_TOOL_NAME,
+        input: { ...args }
+      };
+      const before = budget.snapshot().bytes;
+      const out = runGrep(root, budget, args);
+      const after = budget.snapshot().bytes;
+      const bytesLoaded = after - before;
+      hooks.onToolCall?.(tc, bytesLoaded, after);
+      hooks.bus.emit({
+        kind: "tool_call",
+        runId: hooks.runId,
+        turn: hooks.turn,
+        toolCall: tc,
+        bytesLoaded,
+        totalBytes: after
+      });
+      return out;
+    }
+  });
+}
+function runGrep(root, budget, args) {
+  const exec = budget.canExecuteTool();
+  if (!exec.ok) {
+    return {
+      content: `grep: ${exec.reason}. Finalise the plan with what you already have.`,
+      isError: true
+    };
+  }
+  let re;
+  try {
+    if (args.regex) {
+      re = new RegExp(args.pattern, args.caseInsensitive ? "gi" : "g");
+    } else {
+      const esc = args.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      re = new RegExp(esc, args.caseInsensitive ? "gi" : "g");
+    }
+  } catch (e) {
+    return { content: `grep: invalid pattern (${e.message}).`, isError: true };
+  }
+  const ig = buildRepoIgnore(root);
+  const scopeRoot = args.path?.trim() ? path15.resolve(root, args.path) : root;
+  const relScope = path15.relative(root, scopeRoot);
+  if (relScope.startsWith("..") || path15.isAbsolute(relScope)) {
+    return { content: `grep: scope path escapes the project root and was refused.`, isError: true };
+  }
+  if (!fs23.existsSync(scopeRoot)) {
+    return { content: `grep: scope path not found "${args.path}".`, isError: true };
+  }
+  const matches = [];
+  const walk2 = (dir) => {
+    if (matches.length >= MAX_GREP_MATCHES) return;
+    let entries;
+    try {
+      entries = fs23.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (matches.length >= MAX_GREP_MATCHES) return;
+      const abs = path15.join(dir, entry.name);
+      const rel = path15.relative(root, abs).split(path15.sep).join("/");
+      if (!rel || ig.ignores(rel) || entry.isDirectory() && ig.ignores(rel + "/")) continue;
+      if (entry.isDirectory()) {
+        walk2(abs);
+      } else if (entry.isFile()) {
+        let st;
+        try {
+          st = fs23.statSync(abs);
+        } catch {
+          continue;
+        }
+        if (st.size > MAX_GREP_FILE_SIZE_BYTES) continue;
+        let buf;
+        try {
+          buf = fs23.readFileSync(abs);
+        } catch {
+          continue;
+        }
+        if (looksBinary(buf)) continue;
+        const text = buf.toString("utf8");
+        const lines = text.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+          if (matches.length >= MAX_GREP_MATCHES) return;
+          const line2 = lines[i] ?? "";
+          re.lastIndex = 0;
+          if (re.test(line2)) {
+            const trimmed = line2.trim().slice(0, 200);
+            matches.push(`${rel}:${i + 1}:${trimmed}`);
+          }
+        }
+      }
+    }
+  };
+  if (fs23.statSync(scopeRoot).isFile()) {
+    const rel = path15.relative(root, scopeRoot).split(path15.sep).join("/");
+    if (ig.ignores(rel)) {
+      return { content: `grep: file is ignored by repository filters.`, isError: true };
+    }
+    let st;
+    try {
+      st = fs23.statSync(scopeRoot);
+    } catch {
+      return { content: `grep: not found.`, isError: true };
+    }
+    if (st.size > MAX_GREP_FILE_SIZE_BYTES) {
+      return { content: `grep: file too large to search.`, isError: true };
+    }
+    let buf;
+    try {
+      buf = fs23.readFileSync(scopeRoot);
+    } catch (e) {
+      return { content: `grep: failed to read (${e.message}).`, isError: true };
+    }
+    if (looksBinary(buf)) return { content: `grep: file looks binary and was skipped.`, isError: true };
+    const text = buf.toString("utf8");
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      if (matches.length >= MAX_GREP_MATCHES) break;
+      const line2 = lines[i] ?? "";
+      re.lastIndex = 0;
+      if (re.test(line2)) {
+        matches.push(`${rel}:${i + 1}:${line2.trim().slice(0, 200)}`);
+      }
+    }
+  } else {
+    walk2(scopeRoot);
+  }
+  const header = matches.length >= MAX_GREP_MATCHES ? `Found ${matches.length} matches (capped at ${MAX_GREP_MATCHES}):` : `Found ${matches.length} match${matches.length === 1 ? "" : "es"}:`;
+  const body = matches.length ? `${header}
+${matches.join("\n")}` : `No matches found for "${args.pattern}".`;
+  const byteSize = Buffer.byteLength(body, "utf8");
+  const cap = budget.canRead(byteSize);
+  if (!cap.ok) {
+    return {
+      content: `grep: ${cap.reason}. Finalise the plan with what you already have.`,
+      isError: true
+    };
+  }
+  budget.recordRead(byteSize);
+  return { content: body, isError: false };
+}
+
+// src/planner/tools/list-dir.ts
+import fs24 from "fs";
+import path16 from "path";
+import { tool as tool3 } from "ai";
+import { z as z3 } from "zod";
+var MAX_ENTRIES_PER_LIST = 200;
+var LIST_DIR_TOOL_NAME = "list_dir";
+function listDirToolFactory(root, budget, hooks) {
+  return tool3({
+    description: "List the contents of a directory in the project (one level deep). Returns up to 200 entries with type (file/dir) and size. Cheap; use this to discover sibling files before reading them.",
+    parameters: z3.object({
+      path: z3.string().describe('Repo-relative directory path. Use "." for the project root.')
+    }),
+    execute: async (args, { toolCallId }) => {
+      const tc = {
+        id: toolCallId,
+        name: LIST_DIR_TOOL_NAME,
+        input: { path: args.path }
+      };
+      const before = budget.snapshot().bytes;
+      const out = runListDir(root, budget, args.path);
+      const after = budget.snapshot().bytes;
+      hooks.onToolCall?.(tc, after - before, after);
+      hooks.bus.emit({
+        kind: "tool_call",
+        runId: hooks.runId,
+        turn: hooks.turn,
+        toolCall: tc,
+        bytesLoaded: after - before,
+        totalBytes: after
+      });
+      return out;
+    }
+  });
+}
+function runListDir(root, budget, rawPath) {
+  const exec = budget.canExecuteTool();
+  if (!exec.ok) {
+    return {
+      content: `list_dir: ${exec.reason}. Finalise the plan with what you already have.`,
+      isError: true
+    };
+  }
+  const normalized = rawPath.trim() === "" ? "." : rawPath.trim();
+  const resolved = path16.resolve(root, normalized);
+  const relCheck = path16.relative(root, resolved);
+  if (relCheck.startsWith("..") || path16.isAbsolute(relCheck)) {
+    return {
+      content: `list_dir: path "${rawPath}" escapes the project root and was refused.`,
+      isError: true
+    };
+  }
+  const relNorm = relCheck.split(path16.sep).join("/");
+  const ig = buildRepoIgnore(root);
+  if (relNorm && (ig.ignores(relNorm) || ig.ignores(`${relNorm}/`))) {
+    return { content: "list_dir: (directory ignored by repo-map filter)", isError: true };
+  }
+  if (!fs24.existsSync(resolved)) {
+    return { content: `list_dir: not found "${rawPath}".`, isError: true };
+  }
+  const st = fs24.statSync(resolved);
+  if (!st.isDirectory()) {
+    return { content: `list_dir: "${rawPath}" is not a directory.`, isError: true };
+  }
+  let dirents;
+  try {
+    dirents = fs24.readdirSync(resolved, { withFileTypes: true });
+  } catch (e) {
+    return { content: `list_dir: failed to read (${e.message}).`, isError: true };
+  }
+  const rows = [];
+  for (const d of dirents) {
+    if (rows.length >= MAX_ENTRIES_PER_LIST) break;
+    const childAbs = path16.join(resolved, d.name);
+    const childRel = path16.relative(root, childAbs).split(path16.sep).join("/");
+    if (childRel && (ig.ignores(childRel) || d.isDirectory() && ig.ignores(`${childRel}/`))) continue;
+    if (d.isDirectory()) {
+      rows.push({ type: "d", name: d.name + "/", size: null });
+    } else if (d.isFile()) {
+      let size = 0;
+      try {
+        size = fs24.statSync(childAbs).size;
+      } catch {
+        size = 0;
+      }
+      rows.push({ type: "f", name: d.name, size });
+    }
+  }
+  rows.sort((a, b) => {
+    if (a.type !== b.type) return a.type === "d" ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+  const lines = rows.map((r) => {
+    const sz = r.type === "d" ? "\u2014" : String(r.size ?? 0);
+    return `${r.type}  ${sz.padStart(8, " ")}  ${r.name}`;
+  });
+  const body = lines.length > 0 ? `Entries (max ${MAX_ENTRIES_PER_LIST}):
+${lines.join("\n")}` : "(empty directory)";
+  const byteSize = Buffer.byteLength(body, "utf8");
+  const cap = budget.canRead(byteSize);
+  if (!cap.ok) {
+    return {
+      content: `list_dir: ${cap.reason}. Finalise the plan with what you already have.`,
+      isError: true
+    };
+  }
+  budget.recordRead(byteSize);
+  return { content: body, isError: false };
+}
+
+// src/planner/tools/index.ts
+function buildPlannerTools(opts) {
+  const enabled = opts.enabled ?? { rangedRead: true, grep: true, listDir: true };
+  const gh = opts.grepHooks ?? {
+    runId: opts.readHooks.runId,
+    turn: opts.readHooks.turn,
+    bus: opts.readHooks.bus,
+    onToolCall: opts.readHooks.onToolCall
+  };
+  const lh = opts.listDirHooks ?? {
+    runId: opts.readHooks.runId,
+    turn: opts.readHooks.turn,
+    bus: opts.readHooks.bus,
+    onToolCall: opts.readHooks.onToolCall
+  };
+  const readOpts = { ranged: enabled.rangedRead ?? true };
+  return {
+    read_file: readFileToolFactory(opts.root, opts.budget, opts.readHooks, readOpts),
+    ...enabled.grep ? { grep: grepToolFactory(opts.root, opts.budget, gh) } : {},
+    ...enabled.listDir ? { list_dir: listDirToolFactory(opts.root, opts.budget, lh) } : {}
+  };
+}
+
 // src/planner/provider-errors.ts
 function detectModelNotFound(provider, model, status, rawBody) {
   if (status !== 404) return void 0;
@@ -3315,16 +3925,16 @@ function detectModelNotFound(provider, model, status, rawBody) {
   if (!hints.some((h) => body.includes(h))) return void 0;
   return { provider, model, status, rawBody };
 }
-function modelNotFoundMessage(err) {
+function modelNotFoundMessage(err2) {
   return [
-    `The ${err.provider} planner model "${err.model}" is no longer available.`,
+    `The ${err2.provider} planner model "${err2.model}" is no longer available.`,
     "",
     "Recovery options:",
     `  1. Run \`squad upgrade\` to install a newer squad-kit (or install manually from npm).`,
     `  2. Run \`squad config set planner --provider openai\` (or another \`--provider\`) to switch models via a different provider, then save a key when prompted.`,
-    `  3. Run \`squad config set planner\` to set \`planner.modelOverride.${err.provider}\` to a still-valid id (no raw YAML), then \`squad doctor\` to confirm.`,
+    `  3. Run \`squad config set planner\` to set \`planner.modelOverride.${err2.provider}\` to a still-valid id (no raw YAML), then \`squad doctor\` to confirm.`,
     "",
-    `Raw provider response: ${err.rawBody.slice(0, 200)}`
+    `Raw provider response: ${err2.rawBody.slice(0, 200)}`
   ].join("\n");
 }
 function detectRateLimit(provider, status, headers, rawBody) {
@@ -3336,16 +3946,20 @@ function detectRateLimit(provider, status, headers, rawBody) {
     rawBody
   };
 }
-function parseRetryAfter(headers, body) {
+function parseRetryAfterSec(headers) {
   const raw = headerGet(headers, "retry-after");
-  if (raw) {
-    const sec = Number(raw);
-    if (Number.isFinite(sec) && sec >= 0) return Math.ceil(sec);
-    const asDate = Date.parse(raw);
-    if (Number.isFinite(asDate)) {
-      return Math.max(0, Math.ceil((asDate - Date.now()) / 1e3));
-    }
+  if (!raw) return void 0;
+  const sec = Number(raw);
+  if (Number.isFinite(sec) && sec >= 0) return Math.ceil(sec);
+  const asDate = Date.parse(raw);
+  if (Number.isFinite(asDate)) {
+    return Math.max(0, Math.ceil((asDate - Date.now()) / 1e3));
   }
+  return void 0;
+}
+function parseRetryAfter(headers, body) {
+  const fromHeader = parseRetryAfterSec(headers);
+  if (fromHeader !== void 0) return fromHeader;
   const bodyMatch = /"retryDelay"\s*:\s*"(\d+)(?:\.\d+)?s"/i.exec(body);
   if (bodyMatch) {
     const sec = Number(bodyMatch[1]);
@@ -3364,16 +3978,16 @@ function headerGet(h, name) {
   }
   return null;
 }
-function rateLimitMessage(err) {
-  const waitHint = err.retryAfterSec ?? 60;
+function rateLimitMessage(err2) {
+  const waitHint = err2.retryAfterSec ?? 60;
   const limitsUrl = {
     anthropic: "https://console.anthropic.com/settings/limits",
     openai: "https://platform.openai.com/settings/organization/limits",
     google: "https://aistudio.google.com/app/plan_information"
   };
-  const headline = err.retryAfterSec ? `${err.provider} rate limit hit \u2014 provider asked us to wait ${err.retryAfterSec}s before retrying.` : `${err.provider} rate limit hit.`;
-  const cap = err.maxRetrySec ?? 90;
-  const retried = err.retrySkippedReason === "retry_after_too_long" ? `squad-kit did not auto-retry: the provider's ${err.retryAfterSec}s wait is longer than our ${cap}s cap, so retrying would just burn another request inside the same throttle window.` : err.retryAlreadyAttempted ? "squad-kit already retried once automatically and was throttled again \u2014 your org is firmly over its per-minute quota." : "squad-kit aborted before retrying.";
+  const headline = err2.retryAfterSec ? `${err2.provider} rate limit hit \u2014 provider asked us to wait ${err2.retryAfterSec}s before retrying.` : `${err2.provider} rate limit hit.`;
+  const cap = err2.maxRetrySec ?? 90;
+  const retried = err2.retrySkippedReason === "retry_after_too_long" ? `squad-kit did not auto-retry: the provider's ${err2.retryAfterSec}s wait is longer than our ${cap}s cap, so retrying would just burn another request inside the same throttle window.` : err2.retryAlreadyAttempted ? "squad-kit already retried once automatically and was throttled again \u2014 your org is firmly over its per-minute quota." : "squad-kit aborted before retrying.";
   return [
     headline,
     retried,
@@ -3382,427 +3996,148 @@ function rateLimitMessage(err) {
     `  1. Wait ${waitHint}s and rerun \`squad new-plan --api\`. Per-minute limits reset quickly.`,
     `  2. Switch to a smaller planner model: \`squad config set planner\` (pick a cheaper model id).`,
     `  3. Tighten \`planner.budget\` in \`.squad/config.yaml\` (smaller \`maxContextBytes\` / \`maxFileReads\`) so each request carries fewer tokens.`,
-    `  4. Upgrade your ${err.provider} tier: ${limitsUrl[err.provider]}.`,
+    `  4. Upgrade your ${err2.provider} tier: ${limitsUrl[err2.provider]}.`,
     "",
     "Full runbook: docs/migrating-from-0.1.md (see \xA78. If something goes wrong).",
     "",
-    `Raw provider response: ${err.rawBody.slice(0, 200)}`
+    `Raw provider response: ${err2.rawBody.slice(0, 200)}`
   ].join("\n");
 }
 
-// src/planner/stable-json.ts
-function sortRecordKeys(v) {
-  if (v === null || typeof v !== "object") return v;
-  if (Array.isArray(v)) return v.map((x) => sortRecordKeys(x));
-  const o = v;
-  const out = {};
-  for (const k of Object.keys(o).sort()) {
-    out[k] = sortRecordKeys(o[k]);
+// src/planner/usage-map.ts
+function usageFromLanguageModelStep(usage, providerMetadata) {
+  const out = {
+    inputTokens: usage.promptTokens,
+    outputTokens: usage.completionTokens
+  };
+  const meta = providerMetadata;
+  const a = meta?.anthropic;
+  if (a) {
+    out.cacheCreationTokens = a.cacheCreationInputTokens ?? 0;
+    out.cacheReadTokens = a.cacheReadInputTokens ?? 0;
   }
   return out;
 }
 
-// src/planner/providers/anthropic.ts
-var API_URL = "https://api.anthropic.com/v1/messages";
-var API_VERSION = "2023-06-01";
-var anthropicProvider = {
-  name: "anthropic",
-  async send(req) {
-    return callAnthropic(req);
-  }
-};
-function buildAnthropicBody(req) {
-  if (req.cacheEnabled === false) {
-    const base2 = {
-      model: req.model,
-      max_tokens: req.maxOutputTokens ?? 4096,
-      system: req.systemPrompt,
-      tools: req.tools.map(toAnthropicTool)
-    };
-    if (req.turns.length === 0) {
-      return base2;
-    }
-    return { ...base2, messages: req.turns.map((t) => toAnthropicMessage(t)) };
-  }
-  const base = {
-    model: req.model,
-    max_tokens: req.maxOutputTokens ?? 4096,
-    system: [
-      {
-        type: "text",
-        text: req.systemPrompt,
-        cache_control: { type: "ephemeral" }
-      }
-    ],
-    tools: req.tools.map(toAnthropicTool)
-  };
-  if (req.turns.length === 0) {
-    return base;
-  }
-  return { ...base, messages: toMessagesWithCacheMarkers(req.turns) };
-}
-async function callAnthropic(req) {
-  const built = buildAnthropicBody(req);
-  const body = { ...built, messages: built.messages ?? [] };
-  const res = await fetch(API_URL, {
-    method: "POST",
-    headers: {
-      "x-api-key": req.apiKey,
-      "anthropic-version": API_VERSION,
-      "content-type": "application/json"
-    },
-    body: JSON.stringify(body),
-    signal: req.abort
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    const nf = detectModelNotFound("anthropic", req.model, res.status, text);
-    if (nf) {
-      return {
-        stopReason: "error",
-        rawError: modelNotFoundMessage(nf),
-        errorKind: "model_not_found"
-      };
-    }
-    const rl = detectRateLimit("anthropic", res.status, res.headers, text);
-    if (rl) {
-      return {
-        stopReason: "error",
-        rawError: `anthropic 429: ${text.slice(0, 500)}`,
-        errorKind: "rate_limit",
-        retryAfterSec: rl.retryAfterSec
-      };
-    }
-    return { stopReason: "error", rawError: `anthropic ${res.status}: ${text.slice(0, 500)}` };
-  }
-  const json = await res.json();
-  const textOut = json.content.filter((b) => b.type === "text").map((b) => b.text).join("");
-  const toolCalls = json.content.filter((b) => b.type === "tool_use").map((b) => ({ id: b.id, name: b.name, input: b.input }));
-  return {
-    text: textOut || void 0,
-    toolCalls: toolCalls.length ? toolCalls : void 0,
-    stopReason: mapStop(json.stop_reason),
-    usage: {
-      inputTokens: json.usage?.input_tokens ?? 0,
-      outputTokens: json.usage?.output_tokens ?? 0,
-      cacheCreationTokens: json.usage?.cache_creation_input_tokens ?? 0,
-      cacheReadTokens: json.usage?.cache_read_input_tokens ?? 0
-    }
-  };
-}
-function toMessagesWithCacheMarkers(turns) {
-  let lastUserWithToolResultIdx = -1;
-  for (let i = turns.length - 1; i >= 0; i -= 1) {
-    const t = turns[i];
-    if (t.role === "user" && hasToolResultBlock(t)) {
-      lastUserWithToolResultIdx = i;
-      break;
-    }
-  }
-  return turns.map((turn, idx) => {
-    const message = toAnthropicMessage(turn);
-    if (idx === lastUserWithToolResultIdx) {
-      return attachCacheControlToLastToolResult(message);
-    }
-    return message;
-  });
-}
-function hasToolResultBlock(turn) {
-  return (turn.toolResults?.length ?? 0) > 0;
-}
-function attachCacheControlToLastToolResult(msg) {
-  const content = [...msg.content];
-  for (let i = content.length - 1; i >= 0; i -= 1) {
-    const block = content[i];
-    if (block.type === "tool_result") {
-      content[i] = { ...block, cache_control: { type: "ephemeral" } };
-      break;
-    }
-  }
-  return { ...msg, content };
+// src/planner/system-prompt.ts
+function composeSystemPrompt(args) {
+  const base = readBundledPrompt("generate-plan.md").replace(/\{\{projectRoots\}\}/g, args.projectRoots.join(", ")).replace(/\{\{primaryLanguage\}\}/g, args.primaryLanguage).replace(/\{\{trackerType\}\}/g, args.trackerType).replace(
+    /\{\{intakeContent\}\}/g,
+    "_(The intake story is provided in the user message below. Do not ask for it.)_"
+  );
+  const apiPreamble = [
+    "",
+    "---",
+    "",
+    "## Direct-API mode notes",
+    "",
+    "You are being invoked by the squad-kit CLI, not by a human editor. The intake is already inlined below.",
+    "The repository tree is provided. Tools: **`list_dir`** (one-level directory listing), **`grep`** (search), **`read_file`** (whole file up to 32 KB, or **`offset` + `limit`** for a line range \u2014 preferred when you know the region).",
+    "You have a bounded context budget (tool calls, total bytes, wall-clock time). Prefer `grep` and ranged `read_file` over whole-file reads.",
+    "When you have enough information, output the **complete plan markdown** as your final assistant message. No prose around it, no code fences wrapping the whole plan. The CLI will write your final message verbatim to disk.",
+    "",
+    "## Repository tree",
+    "",
+    "```",
+    args.repoMap.trimEnd(),
+    "```",
+    ""
+  ].join("\n");
+  return base + apiPreamble;
 }
-function toAnthropicTool(t) {
-  return {
-    name: t.name,
-    description: t.description,
-    input_schema: sortRecordKeys(t.inputSchema)
-  };
+function composeScoutSystemPrompt(args) {
+  const plans = args.plansIndex?.trim() || "(no prior plans yet)";
+  const base = readBundledPrompt("scout.md").replace(/\{\{projectRoots\}\}/g, args.projectRoots.join(", ")).replace(/\{\{primaryLanguage\}\}/g, args.primaryLanguage).replace(/\{\{trackerType\}\}/g, args.trackerType).replace(/\{\{repoMap\}\}/g, args.repoMap.trimEnd()).replace(/\{\{plansIndex\}\}/g, plans);
+  return base;
 }
-function toAnthropicMessage(turn) {
-  const blocks = [];
-  if (turn.text) blocks.push({ type: "text", text: turn.text });
-  if (turn.toolCalls) {
-    for (const tc of turn.toolCalls) {
-      blocks.push({
-        type: "tool_use",
-        id: tc.id,
-        name: tc.name,
-        input: sortRecordKeys(tc.input)
-      });
-    }
-  }
-  if (turn.toolResults) {
-    for (const tr of turn.toolResults) {
-      blocks.push({
-        type: "tool_result",
-        tool_use_id: tr.toolCallId,
-        content: tr.content,
-        is_error: tr.isError ?? false
-      });
-    }
-  }
-  return { role: turn.role === "assistant" ? "assistant" : "user", content: blocks };
+var SCOUTED_USER_MESSAGE_CACHE_SENTINEL = "I have already scouted the project";
+function composeScoutedUserMessage(args) {
+  return [
+    SCOUTED_USER_MESSAGE_CACHE_SENTINEL + " for relevant files. Use this as your starting context; call `read_file`/`grep`/`list_dir` if you need to read more.",
+    "",
+    args.scoutedSection.trim(),
+    ""
+  ].join("\n");
 }
-function mapStop(r) {
-  if (r === "tool_use") return "tool_use";
-  if (r === "max_tokens") return "max_tokens";
-  return "end_turn";
+function composeUserPrompt(args) {
+  return [
+    "Produce the implementation plan for the following intake.",
+    "",
+    "---",
+    "",
+    args.intakeContent.trimEnd(),
+    ""
+  ].join("\n");
 }
 
-// src/planner/providers/openai.ts
-var API_URL2 = "https://api.openai.com/v1/chat/completions";
-var openaiProvider = {
-  name: "openai",
-  async send(req) {
-    return callOpenAI(req);
-  }
-};
-function buildOpenAIBody(req) {
-  const base = {
-    model: req.model,
-    max_completion_tokens: req.maxOutputTokens ?? 4096,
-    tools: req.tools.map(toOpenAITool)
-  };
-  if (req.turns.length === 0) {
-    return base;
-  }
-  const messages = [{ role: "system", content: req.systemPrompt }];
-  for (const turn of req.turns) messages.push(...toOpenAIMessages(turn));
-  return { ...base, messages };
-}
-async function callOpenAI(req) {
-  const built = buildOpenAIBody(req);
-  const messages = built.messages && built.messages.length > 0 ? built.messages : [{ role: "system", content: req.systemPrompt }];
-  const body = { ...built, messages };
-  const res = await fetch(API_URL2, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${req.apiKey}`,
-      "content-type": "application/json"
-    },
-    body: JSON.stringify(body),
-    signal: req.abort
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    const nf = detectModelNotFound("openai", req.model, res.status, text);
-    if (nf) {
-      return {
-        stopReason: "error",
-        rawError: modelNotFoundMessage(nf),
-        errorKind: "model_not_found"
-      };
-    }
-    const rl = detectRateLimit("openai", res.status, res.headers, text);
-    if (rl) {
-      return {
-        stopReason: "error",
-        rawError: `openai 429: ${text.slice(0, 500)}`,
-        errorKind: "rate_limit",
-        retryAfterSec: rl.retryAfterSec
-      };
-    }
-    return { stopReason: "error", rawError: `openai ${res.status}: ${text.slice(0, 500)}` };
-  }
-  const json = await res.json();
-  const choice = json.choices?.[0];
-  if (!choice) return { stopReason: "error", rawError: "openai: empty choices" };
-  const textOut = choice.message.content ?? "";
-  const toolCalls = (choice.message.tool_calls ?? []).map((tc) => ({
-    id: tc.id,
-    name: tc.function.name,
-    input: safeJson(tc.function.arguments)
-  }));
-  return {
-    text: textOut || void 0,
-    toolCalls: toolCalls.length ? toolCalls : void 0,
-    stopReason: mapStop2(choice.finish_reason),
-    usage: {
-      inputTokens: json.usage?.prompt_tokens ?? 0,
-      outputTokens: json.usage?.completion_tokens ?? 0
-    }
-  };
-}
-function toOpenAITool(t) {
-  return {
-    type: "function",
-    function: {
-      name: t.name,
-      description: t.description,
-      parameters: sortRecordKeys(t.inputSchema)
+// src/planner/core-messages.ts
+function turnsToCoreMessages(systemPrompt, turns, opts) {
+  const { cacheEnabled, provider } = opts;
+  const messages = [
+    {
+      role: "system",
+      content: systemPrompt,
+      ...cacheEnabled && provider === "anthropic" ? { providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } } } : {}
     }
-  };
-}
-function toOpenAIMessages(turn) {
-  const out = [];
-  if (turn.role === "assistant") {
-    out.push({
-      role: "assistant",
-      content: turn.text ?? null,
-      tool_calls: turn.toolCalls?.map((tc) => ({
-        id: tc.id,
-        type: "function",
-        function: {
-          name: tc.name,
-          arguments: JSON.stringify(sortRecordKeys(tc.input))
+  ];
+  let lastToolMessageIndex = -1;
+  for (const t of turns) {
+    if (t.role === "user") {
+      if (t.text !== void 0 && t.text.length > 0) {
+        const userMsg = { role: "user", content: t.text };
+        if (cacheEnabled && provider === "anthropic" && t.text.startsWith(SCOUTED_USER_MESSAGE_CACHE_SENTINEL)) {
+          userMsg.providerOptions = {
+            anthropic: { cacheControl: { type: "ephemeral" } }
+          };
         }
-      }))
-    });
-  } else {
-    if (turn.text) out.push({ role: "user", content: turn.text });
-    if (turn.toolResults) {
-      for (const tr of turn.toolResults) {
-        out.push({ role: "tool", tool_call_id: tr.toolCallId, content: tr.content });
+        messages.push(userMsg);
+      }
+      if (t.toolResults?.length) {
+        const msg = {
+          role: "tool",
+          content: t.toolResults.map((tr) => ({
+            type: "tool-result",
+            toolCallId: tr.toolCallId,
+            toolName: tr.name,
+            result: tr.content,
+            ...tr.isError ? { isError: true } : {}
+          }))
+        };
+        lastToolMessageIndex = messages.push(msg) - 1;
+      }
+    } else {
+      const parts = [];
+      if (t.text) parts.push({ type: "text", text: t.text });
+      for (const tc of t.toolCalls ?? []) {
+        parts.push({
+          type: "tool-call",
+          toolCallId: tc.id,
+          toolName: tc.name,
+          args: tc.input
+        });
+      }
+      if (parts.length === 0) continue;
+      if (parts.length === 1 && parts[0].type === "text") {
+        messages.push({ role: "assistant", content: parts[0].text });
+      } else {
+        messages.push({ role: "assistant", content: parts });
       }
     }
   }
-  return out;
-}
-function mapStop2(r) {
-  if (r === "tool_calls") return "tool_use";
-  if (r === "length") return "max_tokens";
-  return "end_turn";
-}
-function safeJson(raw) {
-  try {
-    return sortRecordKeys(JSON.parse(raw));
-  } catch {
-    return {};
-  }
-}
-
-// src/planner/providers/google.ts
-var API_BASE = "https://generativelanguage.googleapis.com/v1beta/models";
-var googleProvider = {
-  name: "google",
-  async send(req) {
-    return callGoogle(req);
-  }
-};
-function buildGoogleBody(req) {
-  const base = {
-    system_instruction: { parts: [{ text: req.systemPrompt }] },
-    generationConfig: { maxOutputTokens: req.maxOutputTokens ?? 4096 }
-  };
-  if (req.tools.length) {
-    base.tools = [{ functionDeclarations: req.tools.map(toGoogleTool) }];
-  }
-  if (req.turns.length === 0) {
-    return base;
-  }
-  return { ...base, contents: req.turns.map(toGoogleContent) };
-}
-async function callGoogle(req) {
-  const url = `${API_BASE}/${encodeURIComponent(req.model)}:generateContent?key=${encodeURIComponent(req.apiKey)}`;
-  const built = buildGoogleBody(req);
-  const body = { ...built, contents: built.contents ?? [] };
-  const res = await fetch(url, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(body),
-    signal: req.abort
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    const nf = detectModelNotFound("google", req.model, res.status, text);
-    if (nf) {
-      return {
-        stopReason: "error",
-        rawError: modelNotFoundMessage(nf),
-        errorKind: "model_not_found"
+  if (cacheEnabled && provider === "anthropic" && lastToolMessageIndex >= 0) {
+    const target = messages[lastToolMessageIndex];
+    if (target.role === "tool") {
+      target.providerOptions = {
+        anthropic: { cacheControl: { type: "ephemeral" } }
       };
     }
-    const rl = detectRateLimit("google", res.status, res.headers, text);
-    if (rl) {
-      return {
-        stopReason: "error",
-        rawError: `google 429: ${text.slice(0, 500)}`,
-        errorKind: "rate_limit",
-        retryAfterSec: rl.retryAfterSec
-      };
-    }
-    return { stopReason: "error", rawError: `google ${res.status}: ${text.slice(0, 500)}` };
-  }
-  const json = await res.json();
-  const cand = json.candidates?.[0];
-  if (!cand) return { stopReason: "error", rawError: "google: empty candidates" };
-  const parts = cand.content?.parts ?? [];
-  const textOut = parts.filter((p) => "text" in p && !!p.text).map((p) => p.text).join("");
-  const toolCalls = parts.filter((p) => "functionCall" in p && !!p.functionCall).map((p, i) => ({
-    id: `gcall_${i}_${p.functionCall.name}`,
-    name: p.functionCall.name,
-    input: p.functionCall.args ? sortRecordKeys(p.functionCall.args) : {}
-  }));
-  return {
-    text: textOut || void 0,
-    toolCalls: toolCalls.length ? toolCalls : void 0,
-    stopReason: mapStop3(cand.finishReason),
-    usage: {
-      inputTokens: json.usageMetadata?.promptTokenCount ?? 0,
-      outputTokens: json.usageMetadata?.candidatesTokenCount ?? 0
-    }
-  };
-}
-function toGoogleTool(t) {
-  return { name: t.name, description: t.description, parameters: sortRecordKeys(t.inputSchema) };
-}
-function toGoogleContent(turn) {
-  const role = turn.role === "assistant" ? "model" : "user";
-  const parts = [];
-  if (turn.text) parts.push({ text: turn.text });
-  if (turn.toolCalls) {
-    for (const tc of turn.toolCalls) {
-      parts.push({ functionCall: { name: tc.name, args: sortRecordKeys(tc.input) } });
-    }
   }
-  if (turn.toolResults) {
-    for (const tr of turn.toolResults) {
-      parts.push({
-        functionResponse: { name: nameFromToolCallId(tr.toolCallId), response: { content: tr.content } }
-      });
-    }
-  }
-  return { role, parts };
-}
-function nameFromToolCallId(id) {
-  const m = id.match(/^gcall_\d+_(.+)$/);
-  return m?.[1] ?? "read_file";
-}
-function mapStop3(r) {
-  if (r === "STOP" || r === "END_OF_TURN" || r === "FINISH_REASON_STOP") return "end_turn";
-  if (r === "MAX_TOKENS") return "max_tokens";
-  return "tool_use";
-}
-
-// src/planner/providers/prefix.ts
-function prefixOf(provider, req) {
-  const trimmed = { ...req, turns: req.turns.slice(0, -1) };
-  const s = (() => {
-    switch (provider) {
-      case "anthropic":
-        return JSON.stringify(buildAnthropicBody(trimmed));
-      case "openai":
-        return JSON.stringify(buildOpenAIBody(trimmed));
-      case "google":
-        return JSON.stringify(buildGoogleBody(trimmed));
-    }
-  })();
-  return s.length > 0 ? s.slice(0, -1) : s;
+  return messages;
 }
 
 // src/core/runs.ts
-import fs22 from "fs/promises";
-import path14 from "path";
+import fs25 from "fs/promises";
+import path17 from "path";
 import { randomBytes } from "crypto";
 var RING_SIZE = 20;
 function newRunId() {
@@ -3811,24 +4146,24 @@ function newRunId() {
   return `${ts}-${rnd}`;
 }
 async function appendRun(paths, rec) {
-  const dir = path14.join(paths.squadDir, "runs");
-  await fs22.mkdir(dir, { recursive: true });
-  const file = path14.join(dir, `${rec.runId}.json`);
-  await fs22.writeFile(file, JSON.stringify({ ...rec, version: 1 }, null, 2) + "\n", "utf8");
+  const dir = path17.join(paths.squadDir, "runs");
+  await fs25.mkdir(dir, { recursive: true });
+  const file = path17.join(dir, `${rec.runId}.json`);
+  await fs25.writeFile(file, JSON.stringify({ ...rec, version: 1 }, null, 2) + "\n", "utf8");
   await pruneOldRuns(dir);
 }
 async function pruneOldRuns(dir) {
-  const entries = (await fs22.readdir(dir)).filter((n) => n.endsWith(".json"));
+  const entries = (await fs25.readdir(dir)).filter((n) => n.endsWith(".json"));
   if (entries.length <= RING_SIZE) return;
   entries.sort();
   const drop = entries.slice(0, entries.length - RING_SIZE);
-  await Promise.all(drop.map((n) => fs22.rm(path14.join(dir, n), { force: true })));
+  await Promise.all(drop.map((n) => fs25.rm(path17.join(dir, n), { force: true })));
 }
 async function listRuns(paths) {
-  const dir = path14.join(paths.squadDir, "runs");
+  const dir = path17.join(paths.squadDir, "runs");
   let entries;
   try {
-    entries = await fs22.readdir(dir);
+    entries = await fs25.readdir(dir);
   } catch {
     return [];
   }
@@ -3836,7 +4171,7 @@ async function listRuns(paths) {
   const out = [];
   for (const f of files) {
     try {
-      const raw = await fs22.readFile(path14.join(dir, f), "utf8");
+      const raw = await fs25.readFile(path17.join(dir, f), "utf8");
       const parsed = JSON.parse(raw);
       if (parsed.version === 1) out.push(parsed);
     } catch {
@@ -3866,6 +4201,355 @@ var PlannerEventBus = class {
   }
 };
 
+// src/planner/stages/scout.ts
+import { APICallError, generateObject, NoObjectGeneratedError } from "ai";
+import { z as z4 } from "zod";
+var ScoutOutputSchema = z4.object({
+  selectedFiles: z4.array(z4.string()).min(1).max(25),
+  reasoning: z4.string().min(1),
+  suggestedReadStrategy: z4.enum(["read_full", "read_ranges", "mixed"]),
+  readRanges: z4.array(
+    z4.object({
+      path: z4.string(),
+      offset: z4.number().int().min(1),
+      limit: z4.number().int().min(1).max(400)
+    })
+  ).optional()
+});
+async function runScout(input5) {
+  const maxTokens = input5.maxTokens ?? 2048;
+  let attempt = 0;
+  while (true) {
+    try {
+      const { object, usage, providerMetadata } = await generateObject({
+        model: input5.model,
+        system: input5.systemPrompt,
+        prompt: input5.userPrompt,
+        schema: ScoutOutputSchema,
+        maxTokens,
+        abortSignal: input5.abort
+      });
+      const u = usageFromLanguageModelStep(usage, providerMetadata);
+      input5.budget.recordUsage(u);
+      return {
+        output: object,
+        usage: { inputTokens: u.inputTokens, outputTokens: u.outputTokens }
+      };
+    } catch (e) {
+      if (NoObjectGeneratedError.isInstance(e)) {
+        return null;
+      }
+      if (APICallError.isInstance(e) && attempt === 0) {
+        const status = e.statusCode ?? 0;
+        if (status === 429) {
+          const ra = parseRetryAfterSec(e.responseHeaders ?? {});
+          if (ra !== void 0 && ra <= 90) {
+            await new Promise((r) => setTimeout(r, ra * 1e3));
+            attempt += 1;
+            continue;
+          }
+        }
+      }
+      throw e;
+    }
+  }
+}
+
+// src/planner/validation.ts
+import fs26 from "fs";
+import path18 from "path";
+var CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|md|json|ya?ml|css|html|py|go|rs|cs|java|kt|kts|swift|rb|php|vue|svelte)$/i;
+function summariseIssuesByKind(issues) {
+  const out = {};
+  for (const i of issues) {
+    out[i.kind] = (out[i.kind] ?? 0) + 1;
+  }
+  return out;
+}
+function extractBacktickPaths(planText) {
+  const claims = [];
+  const re = /`([^`\n]+)`/g;
+  let m;
+  while ((m = re.exec(planText)) !== null) {
+    const inner = m[1].trim();
+    if (!inner.includes("/") || inner.startsWith("http")) continue;
+    if (inner.includes("story ") || inner.includes("Story ")) continue;
+    const seg = inner.split(/[\s:]/)[0];
+    if (!seg || !CODE_EXT.test(seg)) continue;
+    claims.push({ path: seg.replace(/^\.\//, ""), isCreate: false, excerpt: m[0] });
+  }
+  return claims;
+}
+function extractFileHeadingPaths(planText) {
+  const claims = [];
+  const fileRe = /\*\*\s*(?:File|Create file)\s*:\s*`([^`\n]+)`\s*\*\*/gi;
+  let m;
+  while ((m = fileRe.exec(planText)) !== null) {
+    const p = m[1].trim().replace(/^\.\//, "");
+    const isCreate = /create file/i.test(m[0]);
+    claims.push({ path: p, isCreate, excerpt: m[0].slice(0, 120) });
+  }
+  return claims;
+}
+function mergePathClaims(planText) {
+  const map = /* @__PURE__ */ new Map();
+  for (const c of [...extractFileHeadingPaths(planText), ...extractBacktickPaths(planText)]) {
+    const key = `${c.isCreate}:${c.path}`;
+    if (!map.has(key)) map.set(key, c);
+  }
+  return [...map.values()];
+}
+var LINE_RANGE_RE = /(?:~?\s*lines?\s*|lines\s+)(\d+)\s*[–-]\s*(\d+)/gi;
+var LINE_SINGLE_WORD_RE = /\bline\s+(\d+)\b|\(L(\d+)\)/gi;
+var PATH_COLON_LINE_RE = /`([^`\n]+\.[a-z0-9]{1,6})`\s*:\s*(\d+)\b/gi;
+function pathNear(planText, idx) {
+  const before = planText.slice(Math.max(0, idx - 200), idx);
+  const pathMatch = before.match(/`([^`\n]+\.[a-z0-9]{1,6})`/i);
+  const filePath = pathMatch?.[1]?.trim().replace(/^\.\//, "");
+  return filePath;
+}
+function trigrams(s) {
+  const x = s.toLowerCase();
+  const g = /* @__PURE__ */ new Set();
+  for (let i = 0; i + 3 <= x.length; i++) {
+    g.add(x.slice(i, i + 3));
+  }
+  return g;
+}
+function trigramSimilarity(a, b) {
+  const A = trigrams(a);
+  const B = trigrams(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const t of A) {
+    if (B.has(t)) inter += 1;
+  }
+  return inter / Math.sqrt(A.size * B.size);
+}
+function suggestPaths(root, missingRel, max = 3) {
+  const targetBase = path18.basename(missingRel).toLowerCase();
+  const ig = buildRepoIgnore(root);
+  const candidates = [];
+  const walk2 = (dir) => {
+    if (candidates.length >= 2e3) return;
+    let ents;
+    try {
+      ents = fs26.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of ents) {
+      if (candidates.length >= 2e3) return;
+      const abs = path18.join(dir, ent.name);
+      const rel = path18.relative(root, abs).split(path18.sep).join("/");
+      if (!rel || ig.ignores(rel) || ent.isDirectory() && ig.ignores(`${rel}/`)) continue;
+      if (ent.isDirectory()) walk2(abs);
+      else if (ent.isFile()) candidates.push(rel);
+    }
+  };
+  walk2(root);
+  const rows = [];
+  for (const rel of candidates) {
+    const base = path18.basename(rel).toLowerCase();
+    let score = 0;
+    if (base === targetBase) score = 1e3;
+    else if (base.startsWith(targetBase) || targetBase.startsWith(base)) score = 500;
+    else if (base.includes(targetBase) || targetBase.includes(base)) score = 200;
+    score += trigramSimilarity(targetBase, base) * 50;
+    if (score > 0) rows.push({ rel, score });
+  }
+  rows.sort((a, b) => b.score - a.score || a.rel.localeCompare(b.rel));
+  const uniq = [];
+  for (const r of rows) {
+    if (r.rel === missingRel.replace(/^\.\//, "")) continue;
+    if (!uniq.includes(r.rel)) uniq.push(r.rel);
+    if (uniq.length >= max) break;
+  }
+  return uniq;
+}
+var SYMBOL_DEF_RE = /(?:^|\n)\s*(?:export\s+)?(?:async\s+)?(?:function|class|interface|type|const|let|var)\s+([A-Za-z_][A-Za-z0-9_]*)/g;
+function collectSymbols(src, maxLines = 200) {
+  const head = src.split(/\r?\n/).slice(0, maxLines).join("\n");
+  const syms = /* @__PURE__ */ new Set();
+  SYMBOL_DEF_RE.lastIndex = 0;
+  let m;
+  while ((m = SYMBOL_DEF_RE.exec(head)) !== null) {
+    syms.add(m[1]);
+  }
+  return [...syms];
+}
+function leadingCharScore(sym, missing) {
+  let i = 0;
+  const a = sym.toLowerCase();
+  const b = missing.toLowerCase();
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i * 10 + trigramSimilarity(sym, missing) * 30;
+}
+function suggestSymbols(fileText, missingSym, max = 3) {
+  const defs = collectSymbols(fileText);
+  const ranked = defs.filter((s) => s !== missingSym).map((s) => ({ s, score: leadingCharScore(s, missingSym) })).filter((r) => r.score > 0).sort((a, b) => b.score - a.score || a.s.localeCompare(b.s));
+  const out = [];
+  for (const r of ranked) {
+    if (!out.includes(r.s)) out.push(r.s);
+    if (out.length >= max) break;
+  }
+  return out;
+}
+function parseMetadataLine(planText) {
+  const lines = planText.split(/\r?\n/);
+  for (let i = 0; i < Math.min(5, lines.length); i++) {
+    const line2 = (lines[i] ?? "").trim();
+    if (!line2.startsWith("<!--") || !line2.includes("squad-kit:")) continue;
+    if (!line2.endsWith("-->")) {
+      return {
+        severity: "warning",
+        kind: "malformed_metadata",
+        detail: "Metadata comment is not a single-line <!-- squad-kit: \u2026 -->",
+        excerpt: line2.slice(0, 120)
+      };
+    }
+    const inner = line2.replace(/^<!--\s*squad-kit:\s*/i, "").replace(/\s*-->$/, "");
+    if (!inner.trim()) {
+      return {
+        severity: "warning",
+        kind: "malformed_metadata",
+        detail: "Empty squad-kit metadata body",
+        excerpt: line2
+      };
+    }
+    return void 0;
+  }
+  return void 0;
+}
+function validatePlan(input5) {
+  const issues = [];
+  const metaIssue = parseMetadataLine(input5.planText);
+  if (metaIssue) issues.push(metaIssue);
+  const cache = /* @__PURE__ */ new Map();
+  const readCached = (rel) => {
+    if (cache.has(rel)) return cache.get(rel);
+    const resolved = path18.resolve(input5.root, rel);
+    const rc = path18.relative(input5.root, resolved);
+    if (rc.startsWith("..") || path18.isAbsolute(rc)) return void 0;
+    if (!fs26.existsSync(resolved) || !fs26.statSync(resolved).isFile()) return void 0;
+    try {
+      const buf = fs26.readFileSync(resolved);
+      const isBinary = buf.includes(0);
+      const text = isBinary ? "" : buf.toString("utf8");
+      const lines = isBinary ? 0 : text.split(/\r?\n/).length;
+      const entry = { text, lines, isBinary };
+      cache.set(rel, entry);
+      return entry;
+    } catch {
+      return void 0;
+    }
+  };
+  const pathClaims = mergePathClaims(input5.planText);
+  for (const c of pathClaims) {
+    if (c.isCreate) continue;
+    const resolved = path18.resolve(input5.root, c.path);
+    const rel = path18.relative(input5.root, resolved);
+    if (rel.startsWith("..") || path18.isAbsolute(rel)) continue;
+    if (!fs26.existsSync(resolved)) {
+      const suggestions = suggestPaths(input5.root, c.path);
+      issues.push({
+        severity: "warning",
+        kind: "missing_path",
+        path: c.path,
+        detail: "Path cited in plan does not exist in the workspace" + (suggestions.length ? ` \u2014 did you mean: ${suggestions.join(", ")}?` : ""),
+        excerpt: c.excerpt
+      });
+    }
+  }
+  const rangeText = input5.planText;
+  LINE_RANGE_RE.lastIndex = 0;
+  let rm2;
+  while ((rm2 = LINE_RANGE_RE.exec(rangeText)) !== null) {
+    const lo = parseInt(rm2[1], 10);
+    const hi = parseInt(rm2[2], 10);
+    if (!Number.isFinite(lo) || !Number.isFinite(hi)) continue;
+    const filePath = pathNear(rangeText, rm2.index);
+    if (!filePath) continue;
+    const cached = readCached(filePath);
+    const lines = cached?.isBinary ? void 0 : cached?.lines;
+    if (lines !== void 0 && hi > lines) {
+      issues.push({
+        severity: "warning",
+        kind: "line_range_too_large",
+        path: filePath,
+        detail: `Range ends at line ${hi} but file has ${lines} lines`,
+        excerpt: rm2[0].slice(0, 80)
+      });
+    }
+  }
+  LINE_SINGLE_WORD_RE.lastIndex = 0;
+  while ((rm2 = LINE_SINGLE_WORD_RE.exec(rangeText)) !== null) {
+    const n = parseInt(rm2[1] || rm2[2] || "", 10);
+    if (!Number.isFinite(n)) continue;
+    const filePath = pathNear(rangeText, rm2.index);
+    if (!filePath) continue;
+    const cached = readCached(filePath);
+    const lines = cached?.isBinary ? void 0 : cached?.lines;
+    if (lines !== void 0 && n > lines) {
+      issues.push({
+        severity: "warning",
+        kind: "line_range_too_large",
+        path: filePath,
+        detail: `Range ends at line ${n} but file has ${lines} lines`,
+        excerpt: rm2[0].slice(0, 80)
+      });
+    }
+  }
+  PATH_COLON_LINE_RE.lastIndex = 0;
+  while ((rm2 = PATH_COLON_LINE_RE.exec(rangeText)) !== null) {
+    const fp = rm2[1].trim().replace(/^\.\//, "");
+    const n = parseInt(rm2[2], 10);
+    if (!Number.isFinite(n)) continue;
+    const cached = readCached(fp);
+    const lines = cached?.isBinary ? void 0 : cached?.lines;
+    if (lines !== void 0 && n > lines) {
+      issues.push({
+        severity: "warning",
+        kind: "line_range_too_large",
+        path: fp,
+        detail: `Range ends at line ${n} but file has ${lines} lines`,
+        excerpt: rm2[0].slice(0, 80)
+      });
+    }
+  }
+  const textByLine = input5.planText.split(/\r?\n/);
+  for (let li = 0; li < textByLine.length; li++) {
+    const line2 = textByLine[li] ?? "";
+    const near = [textByLine[li - 1] ?? "", line2, textByLine[li + 1] ?? ""].join("\n");
+    const pathNearCell = near.match(/`([^`\n/]+\/[^`\n]+?\.[a-z0-9]{1,6})`/i);
+    if (!pathNearCell) continue;
+    const fp = pathNearCell[1].replace(/^\.\//, "");
+    const cached = readCached(fp);
+    if (!cached || cached.isBinary) continue;
+    const symRe = /`([A-Za-z_][A-Za-z0-9_]{2,50})`/g;
+    let sm;
+    while ((sm = symRe.exec(line2)) !== null) {
+      const sym = sm[1];
+      if (["true", "false", "null", "undefined", "string", "number", "boolean", "void", "never"].includes(
+        sym
+      )) {
+        continue;
+      }
+      if (!cached.text.includes(sym)) {
+        const suggestions = suggestSymbols(cached.text, sym);
+        issues.push({
+          severity: "warning",
+          kind: "symbol_not_found",
+          path: fp,
+          detail: `Symbol \`${sym}\` not found as substring in file` + (suggestions.length ? ` \u2014 did you mean: ${suggestions.map((s) => `\`${s}\``).join(", ")}?` : ""),
+          excerpt: sm[0]
+        });
+      }
+    }
+  }
+  return issues;
+}
+
 // src/planner/loop.ts
 var MAX_RATE_LIMIT_RETRY_SEC = 90;
 var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
@@ -3903,8 +4587,147 @@ function buildPlannerRunStats(budget, turns, runStartedAt) {
     durationMs: Date.now() - runStartedAt
   };
 }
-function readBudgetishError(result) {
-  return result.isError && (/budget/i.test(result.content) || /max file reads/i.test(result.content));
+function buildScoutedContextSection(root, budget, selectedFiles, bus, runId, readRanges) {
+  const normalizeRel = (p) => p.replace(/^\.\//, "");
+  const rangeByPath = /* @__PURE__ */ new Map();
+  for (const rr of readRanges ?? []) {
+    rangeByPath.set(normalizeRel(rr.path), rr);
+  }
+  const ordered = [];
+  const seenPath = /* @__PURE__ */ new Set();
+  for (const f of selectedFiles) {
+    const c = normalizeRel(f);
+    if (!seenPath.has(c)) {
+      seenPath.add(c);
+      ordered.push(c);
+    }
+  }
+  for (const p of rangeByPath.keys()) {
+    if (!seenPath.has(p)) {
+      seenPath.add(p);
+      ordered.push(p);
+    }
+  }
+  const blocks = ["\n## Scouted context (already loaded)\n"];
+  for (const cleaned of ordered) {
+    const rr = rangeByPath.get(cleaned);
+    if (rr) {
+      const result = readFileTool(root, budget, { path: cleaned, offset: rr.offset, limit: rr.limit });
+      const hi = rr.offset + rr.limit - 1;
+      if (result.isError) {
+        blocks.push(
+          `
+### \`${cleaned}\` (lines ${rr.offset}\u2013${hi})
+
+_${result.content}_
+`
+        );
+      } else {
+        blocks.push(
+          `
+### \`${cleaned}\` (lines ${rr.offset}\u2013${hi})
+
+\`\`\`
+${result.content}
+\`\`\`
+`
+        );
+      }
+      continue;
+    }
+    const resolved = path19.resolve(root, cleaned);
+    const rc = path19.relative(root, resolved);
+    if (rc.startsWith("..") || path19.isAbsolute(rc)) {
+      bus.emit({
+        kind: "validation_issue",
+        runId,
+        severity: "warning",
+        issueKind: "missing_path",
+        path: cleaned,
+        detail: "Scout-selected path escapes the project root"
+      });
+      continue;
+    }
+    if (!fs27.existsSync(resolved)) {
+      bus.emit({
+        kind: "validation_issue",
+        runId,
+        severity: "warning",
+        issueKind: "missing_path",
+        path: cleaned,
+        detail: "Scout selected this path but it does not exist on disk"
+      });
+      continue;
+    }
+    const st = fs27.statSync(resolved);
+    if (!st.isFile()) continue;
+    const n = Math.min(st.size, MAX_BYTES_PER_FULL_READ);
+    const cap = budget.canRead(n);
+    if (!cap.ok) {
+      blocks.push(`
+### \`${cleaned}\`
+
+_(skipped: ${cap.reason})_
+`);
+      continue;
+    }
+    let buf;
+    try {
+      buf = fs27.readFileSync(resolved);
+    } catch {
+      continue;
+    }
+    if (buf.length > MAX_BYTES_PER_FULL_READ) {
+      const head = buf.subarray(0, MAX_BYTES_PER_FULL_READ);
+      if (looksBinary(head)) {
+        blocks.push(`
+### \`${cleaned}\`
+
+_(binary file skipped)_
+`);
+        continue;
+      }
+      budget.recordRead(head.length);
+      blocks.push(
+        `
+### \`${cleaned}\` (truncated: first ${MAX_BYTES_PER_FULL_READ}-byte head; full size ${buf.length} bytes)
+
+\`\`\`
+${head.toString("utf8")}
+\`\`\`
+`
+      );
+      continue;
+    }
+    if (looksBinary(buf)) {
+      blocks.push(`
+### \`${cleaned}\`
+
+_(binary file skipped)_
+`);
+      continue;
+    }
+    budget.recordRead(buf.length);
+    blocks.push(`
+### \`${cleaned}\`
+
+\`\`\`
+${buf.toString("utf8")}
+\`\`\`
+`);
+  }
+  return blocks.join("");
+}
+function scoutStageStats(usage, durationMs) {
+  return {
+    turns: 0,
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    cacheCreationTokens: 0,
+    cacheReadTokens: 0,
+    cacheHitRatio: 0,
+    durationMs
+  };
 }
 function extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut) {
   input5.budget.extendSession();
@@ -3944,28 +4767,106 @@ function cancelledOutput(input5, bus, runId, accumulatedText, budgetExhausted, i
     userCancelled: true
   };
 }
-async function runPlanner(input5) {
+function asToolInput(args) {
+  if (args && typeof args === "object" && !Array.isArray(args)) return args;
+  if (typeof args === "string") {
+    try {
+      return JSON.parse(args);
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+function normalizeToolExecutionResult(result) {
+  if (typeof result === "string") {
+    try {
+      const j = JSON.parse(result);
+      if (j && typeof j === "object" && !Array.isArray(j) && "content" in j) {
+        const o = j;
+        return {
+          content: typeof o.content === "string" ? o.content : JSON.stringify(o.content ?? ""),
+          isError: o.isError === true
+        };
+      }
+    } catch {
+    }
+    return { content: result, isError: false };
+  }
+  if (result && typeof result === "object" && !Array.isArray(result) && "content" in result) {
+    const o = result;
+    return {
+      content: typeof o.content === "string" ? o.content : JSON.stringify(o.content ?? ""),
+      isError: o.isError === true
+    };
+  }
+  return { content: typeof result === "undefined" ? "" : JSON.stringify(result), isError: false };
+}
+function applyStepToTurns(turns, step2) {
+  const callsById = /* @__PURE__ */ new Map();
+  const toolCalls = step2.toolCalls.map((tc) => {
+    callsById.set(tc.toolCallId, tc.toolName);
+    return { id: tc.toolCallId, name: tc.toolName, input: asToolInput(tc.args) };
+  });
+  turns.push({
+    role: "assistant",
+    ...step2.text ? { text: step2.text } : {},
+    ...toolCalls.length ? { toolCalls } : {}
+  });
+  if (step2.toolResults.length) {
+    const toolResults = step2.toolResults.map((tr) => {
+      const norm = normalizeToolExecutionResult(tr.result);
+      return {
+        toolCallId: tr.toolCallId,
+        name: callsById.get(tr.toolCallId) ?? "read_file",
+        content: norm.content,
+        ...norm.isError ? { isError: true } : {}
+      };
+    });
+    turns.push({ role: "user", toolResults });
+  }
+}
+function providerResponseFromApiError(provider, modelId, err2) {
+  const body = err2.responseBody ?? "";
+  const nf = detectModelNotFound(provider, modelId, err2.statusCode ?? 0, body);
+  if (nf) {
+    return {
+      stopReason: "error",
+      errorKind: "model_not_found",
+      rawError: modelNotFoundMessage(nf)
+    };
+  }
+  const rl = detectRateLimit(provider, err2.statusCode ?? 0, err2.responseHeaders ?? {}, body);
+  if (rl) {
+    return {
+      stopReason: "error",
+      errorKind: "rate_limit",
+      retryAfterSec: rl.retryAfterSec,
+      rawError: `${provider} ${err2.statusCode ?? "error"}: ${body.slice(0, 500)}`
+    };
+  }
+  return {
+    stopReason: "error",
+    rawError: `${provider} ${err2.statusCode ?? "error"}: ${body.slice(0, 500)}`
+  };
+}
+async function runDraftStage(input5) {
   const runStartedAt = Date.now();
   const bus = input5.events ?? new PlannerEventBus();
   const runId = input5.runId ?? newRunId();
   const cacheEnabled = input5.cacheEnabled ?? true;
-  bus.emit({
-    kind: "started",
-    runId,
-    provider: input5.provider.name,
-    model: input5.model,
-    cacheEnabled
-  });
   const baseMaxIter = input5.maxIterations ?? DEFAULT_PLANNER_MAX_ITERATIONS;
   const maxIter = { current: baseMaxIter };
   const baseMaxOut = input5.maxOutputTokens ?? DEFAULT_PLANNER_MAX_OUTPUT_TOKENS;
   const maxOut = { current: baseMaxOut };
   const turns = [{ role: "user", text: input5.userPrompt }];
+  if (input5.scoutedSection?.trim()) {
+    turns.push({ role: "user", text: composeScoutedUserMessage({ scoutedSection: input5.scoutedSection }) });
+  }
   let accumulatedText = "";
   let iterations = 0;
   let budgetExhausted = false;
   let finishedNormally = false;
-  let prevRequestPrefix;
   const decide = input5.decideOnLimit;
   const sleepFn = input5.sleep ?? defaultSleep;
   const limitCtx = (kind) => ({
@@ -4036,112 +4937,160 @@ async function runPlanner(input5) {
         stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
       };
     }
-    if (input5.budget.overCost()) {
-      if (decide) {
-        const d = await decide(limitCtx("cost_cap"));
-        if (d === "cancel") {
-          return {
-            planText: accumulatedText,
-            budgetExhausted,
-            timedOut: false,
-            finishedNormally: false,
-            iterations,
-            stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt),
-            incompleteKind: "cost_cap",
-            userCancelled: true
-          };
-        }
-        extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut);
-        iterations -= 1;
-        continue;
-      }
-      return {
-        planText: accumulatedText,
-        budgetExhausted: true,
-        timedOut: false,
-        finishedNormally: false,
-        iterations,
-        stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
-      };
-    }
     if (iterations >= 2) {
       bus.emit({ kind: "turn_started", runId, turn: iterations });
     }
-    const request = {
-      systemPrompt: input5.systemPrompt,
-      model: input5.model,
-      tools: [READ_FILE_TOOL],
-      turns,
-      apiKey: input5.apiKey,
-      maxOutputTokens: maxOut.current,
+    const tools = buildPlannerTools({
+      root: input5.root,
+      budget: input5.budget,
+      enabled: {
+        grep: input5.toolsEnabled?.grep ?? true,
+        listDir: input5.toolsEnabled?.listDir ?? true,
+        rangedRead: input5.toolsEnabled?.rangedRead ?? true
+      },
+      readHooks: {
+        runId,
+        turn: iterations,
+        bus,
+        onToolCall: input5.onToolCall,
+        decideOnLimit: input5.decideOnLimit,
+        getLimitCtx: () => limitCtx("file_or_context_reads"),
+        extendSessionLimits: () => extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut),
+        getAccumulatedText: () => accumulatedText,
+        setBudgetExhausted: (v) => {
+          budgetExhausted = v;
+        }
+      }
+    });
+    const messages = turnsToCoreMessages(input5.systemPrompt, turns, {
       cacheEnabled,
-      abort: input5.abort
-    };
+      provider: input5.provider
+    });
     bus.emit({ kind: "request_sent", runId, turn: iterations });
-    if (process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test" && prevRequestPrefix !== void 0) {
-      const currentPrefix = prefixOf(input5.provider.name, request);
-      if (!currentPrefix.startsWith(prevRequestPrefix)) {
-        const byte = firstByteDiff(prevRequestPrefix, currentPrefix);
-        warning(
-          `planner: prefix mutation at turn ${iterations}, byte ${byte} \u2014 caching will not hit.`
-        );
-      }
-    }
-    let response;
-    try {
-      response = await input5.provider.send(request);
-    } catch (e) {
-      if (isAbortError(e)) {
-        return cancelledOutput(input5, bus, runId, accumulatedText, budgetExhausted, iterations, runStartedAt);
-      }
-      throw e;
-    }
-    if (response.usage) {
-      recordUsageAndEmit(bus, input5, runId, iterations, response.usage);
-    }
-    let retriedRateLimit = false;
+    let attempt = 0;
+    let stepResult;
     let retrySkippedReason;
-    if (response.stopReason === "error" && response.errorKind === "rate_limit") {
-      const asked = response.retryAfterSec;
-      if (asked !== void 0 && asked > MAX_RATE_LIMIT_RETRY_SEC) {
-        retrySkippedReason = "retry_after_too_long";
-      } else {
-        const waitSec = Math.min(asked ?? 10, MAX_RATE_LIMIT_RETRY_SEC);
-        input5.onRateLimit?.(waitSec);
-        bus.emit({ kind: "rate_limit", runId, turn: iterations, waitSec });
-        try {
-          await sleepWithAbort(waitSec * 1e3, sleepFn, input5.abort);
-        } catch (e) {
-          if (isAbortError(e)) {
-            return cancelledOutput(input5, bus, runId, accumulatedText, budgetExhausted, iterations, runStartedAt);
+    let retriedRateLimit = false;
+    const callStream = async () => {
+      const { streamText } = await import("ai");
+      const stream = streamText({
+        model: input5.model,
+        messages,
+        tools,
+        toolChoice: "auto",
+        maxSteps: 1,
+        maxRetries: 0,
+        maxTokens: maxOut.current,
+        abortSignal: input5.abort,
+        onChunk: ({ chunk }) => {
+          if (chunk.type === "text-delta") {
+            accumulatedText += chunk.textDelta;
+            input5.onAssistantText?.(chunk.textDelta);
+            bus.emit({ kind: "assistant_text", runId, turn: iterations, delta: chunk.textDelta });
           }
-          throw e;
+        },
+        onStepFinish: (step2) => {
+          const u = usageFromLanguageModelStep(step2.usage, step2.providerMetadata);
+          recordUsageAndEmit(bus, input5, runId, iterations, u);
         }
+      });
+      for await (const part of stream.fullStream) {
+        const p = part;
+        if (p.type === "error") {
+          throw p.error;
+        }
+      }
+      const steps = await stream.steps;
+      const last = steps[steps.length - 1];
+      if (!last) throw new Error("planner: empty model step");
+      stepResult = {
+        text: last.text,
+        finishReason: last.finishReason,
+        toolCalls: last.toolCalls.flatMap(
+          (tc) => tc ? [
+            {
+              toolCallId: tc.toolCallId,
+              toolName: tc.toolName,
+              args: tc.args
+            }
+          ] : []
+        ),
+        toolResults: last.toolResults.flatMap(
+          (tr) => tr ? [{ toolCallId: tr.toolCallId, result: tr.result }] : []
+        ),
+        usage: last.usage,
+        providerMetadata: last.providerMetadata
+      };
+    };
+    try {
+      while (true) {
         try {
-          response = await input5.provider.send(request);
+          await callStream();
+          break;
         } catch (e) {
+          if (PlannerUserCancelledError.is(e)) {
+            return {
+              planText: e.planText,
+              budgetExhausted: false,
+              timedOut: false,
+              finishedNormally: false,
+              iterations,
+              stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt),
+              incompleteKind: "budget_reads",
+              userCancelled: true
+            };
+          }
           if (isAbortError(e)) {
             return cancelledOutput(input5, bus, runId, accumulatedText, budgetExhausted, iterations, runStartedAt);
           }
+          if (APICallError2.isInstance(e)) {
+            const synthetic = providerResponseFromApiError(input5.provider, input5.modelId, e);
+            if (synthetic.errorKind === "rate_limit") {
+              const asked = synthetic.retryAfterSec;
+              const emitRateLimit = (phase, waitSec) => {
+                bus.emit({
+                  kind: "rate_limit",
+                  runId,
+                  turn: iterations,
+                  retryAfterSec: synthetic.retryAfterSec,
+                  waitSec,
+                  capSec: MAX_RATE_LIMIT_RETRY_SEC,
+                  phase,
+                  provider: input5.provider,
+                  rawBody: (synthetic.rawError ?? "").slice(0, 200)
+                });
+              };
+              if (asked !== void 0 && asked > MAX_RATE_LIMIT_RETRY_SEC) {
+                emitRateLimit("aborted", asked);
+                retrySkippedReason = "retry_after_too_long";
+                throw composePlannerError(input5.provider, synthetic, false, retrySkippedReason);
+              }
+              if (attempt === 0) {
+                const waitSec = Math.min(asked ?? 10, MAX_RATE_LIMIT_RETRY_SEC);
+                emitRateLimit("retrying", waitSec);
+                input5.onRateLimit?.(waitSec);
+                await sleepWithAbort(waitSec * 1e3, sleepFn, input5.abort);
+                attempt += 1;
+                retriedRateLimit = true;
+                continue;
+              }
+              throw composePlannerError(input5.provider, synthetic, true, retrySkippedReason);
+            }
+            throw composePlannerError(input5.provider, synthetic, retriedRateLimit, retrySkippedReason);
+          }
           throw e;
         }
-        if (response.usage) {
-          recordUsageAndEmit(bus, input5, runId, iterations, response.usage);
-        }
-        retriedRateLimit = true;
       }
+    } catch (e) {
+      if (isAbortError(e)) {
+        return cancelledOutput(input5, bus, runId, accumulatedText, budgetExhausted, iterations, runStartedAt);
+      }
+      throw e;
     }
-    if (response.stopReason === "error") {
-      throw composePlannerError(input5.provider.name, response, retriedRateLimit, retrySkippedReason);
-    }
-    prevRequestPrefix = prefixOf(input5.provider.name, request);
-    if (response.text) {
-      accumulatedText += response.text;
-      input5.onAssistantText?.(response.text);
-      bus.emit({ kind: "assistant_text", runId, turn: iterations, delta: response.text });
-    }
-    if (response.stopReason === "max_tokens" && !response.toolCalls?.length) {
-      bus.emit({ kind: "turn_complete", runId, turn: iterations, stopReason: response.stopReason });
+    const finishReason = stepResult.finishReason;
+    const toolCallsLen = stepResult.toolCalls.length;
+    if (finishReason === "length" && toolCallsLen === 0) {
+      bus.emit({ kind: "turn_complete", runId, turn: iterations, stopReason: "max_tokens" });
       if (decide) {
         const d = await decide(limitCtx("max_output_tokens"));
         if (d === "cancel") {
@@ -4157,7 +5106,7 @@ async function runPlanner(input5) {
           };
         }
         extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut);
-        turns.push({ role: "assistant", text: response.text ?? "" });
+        applyStepToTurns(turns, stepResult);
         turns.push({ role: "user", text: PLANNER_MARKDOWN_CONTINUATION_USER });
         iterations -= 1;
         continue;
@@ -4172,8 +5121,13 @@ async function runPlanner(input5) {
         incompleteKind: "max_output_tokens"
       };
     }
-    if (response.stopReason === "end_turn" || !response.toolCalls?.length) {
-      bus.emit({ kind: "turn_complete", runId, turn: iterations, stopReason: response.stopReason });
+    if (finishReason === "error" || finishReason === "content-filter") {
+      throw new Error(
+        stepResult.text || `planner: model reported ${finishReason}. Run \`squad doctor\` to diagnose, or retry \u2014 most 5xx errors are transient.`
+      );
+    }
+    if ((finishReason === "stop" || finishReason === "unknown") && toolCallsLen === 0) {
+      bus.emit({ kind: "turn_complete", runId, turn: iterations, stopReason: finishReason });
       finishedNormally = true;
       return {
         planText: accumulatedText,
@@ -4184,81 +5138,173 @@ async function runPlanner(input5) {
         stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
       };
     }
-    turns.push({
-      role: "assistant",
-      text: response.text,
-      toolCalls: response.toolCalls
-    });
-    const toolResults = [];
-    const toolCalls = response.toolCalls;
-    for (let i = 0; i < toolCalls.length; i += 1) {
-      const tc = toolCalls[i];
-      if (tc.name !== READ_FILE_TOOL.name) {
-        toolResults.push({ toolCallId: tc.id, content: `unknown tool "${tc.name}"`, isError: true });
-        continue;
-      }
-      const before = input5.budget.snapshot().bytes;
-      let result = readFileTool(input5.root, input5.budget, tc.input);
-      const after = input5.budget.snapshot().bytes;
-      const bytesLoaded = after - before;
-      input5.onToolCall?.(tc, bytesLoaded, after);
-      bus.emit({
-        kind: "tool_call",
-        runId,
-        turn: iterations,
-        toolCall: tc,
-        bytesLoaded,
-        totalBytes: after
+    if (toolCallsLen === 0) {
+      bus.emit({ kind: "turn_complete", runId, turn: iterations, stopReason: finishReason });
+      finishedNormally = true;
+      return {
+        planText: accumulatedText,
+        budgetExhausted,
+        timedOut: false,
+        finishedNormally,
+        iterations,
+        stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
+      };
+    }
+    applyStepToTurns(turns, stepResult);
+    if (budgetExhausted) {
+      turns.push({
+        role: "user",
+        text: "Budget is exhausted. Finalise the plan with the information you already have. Do not call any more tools. Output the complete plan markdown now."
       });
-      if (readBudgetishError(result)) {
-        if (decide) {
-          const d = await decide(limitCtx("file_or_context_reads"));
-          if (d === "cancel") {
-            toolResults.push({ toolCallId: tc.id, content: result.content, isError: true });
-            for (let j = i + 1; j < toolCalls.length; j += 1) {
-              const t2 = toolCalls[j];
-              toolResults.push({
-                toolCallId: t2.id,
-                content: t2.name === READ_FILE_TOOL.name ? "read_file: not executed (planning session stopped after file/context budget)." : `unknown tool "${t2.name}"`,
-                isError: true
-              });
-            }
-            turns.push({ role: "user", toolResults });
-            return {
-              planText: accumulatedText,
-              budgetExhausted: false,
-              timedOut: false,
-              finishedNormally: false,
-              iterations,
-              stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt),
-              incompleteKind: "budget_reads",
-              userCancelled: true
-            };
-          }
-          extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut);
-          result = readFileTool(input5.root, input5.budget, tc.input);
-        } else {
-          budgetExhausted = true;
+    }
+    bus.emit({ kind: "turn_complete", runId, turn: iterations, stopReason: finishReason });
+  }
+}
+async function runPlanner(input5) {
+  const bus = input5.events ?? new PlannerEventBus();
+  const runId = input5.runId ?? newRunId();
+  const cacheEnabled = input5.cacheEnabled ?? true;
+  bus.emit({
+    kind: "started",
+    runId,
+    provider: input5.provider,
+    model: input5.modelId,
+    cacheEnabled
+  });
+  const merged = { ...input5, events: bus, runId };
+  const systemPrompt = input5.systemPrompt;
+  let scoutSummary;
+  let scoutStats;
+  let scoutedSection;
+  const scoutOn = input5.stages?.scout?.enabled !== false;
+  const scoutModel = input5.stages?.scout?.model;
+  const maxScoutFiles = input5.stages?.scout?.maxFiles ?? 12;
+  const scoutMaxOut = input5.stages?.scout?.maxOutputTokens ?? 2048;
+  const scoutModelIdStr = input5.stages?.scout?.modelId ?? "";
+  if (scoutOn && scoutModel) {
+    if (!input5.scoutSystemPrompt?.trim()) {
+      throw new Error(
+        "planner: scout enabled but `scoutSystemPrompt` was not provided. Compose it via composeScoutSystemPrompt() or set stages.scout.enabled = false."
+      );
+    }
+    const t0 = Date.now();
+    bus.emit({ kind: "stage_started", runId, stage: "scout" });
+    try {
+      const scoutRes = await runScout({
+        model: scoutModel,
+        systemPrompt: input5.scoutSystemPrompt,
+        userPrompt: input5.userPrompt,
+        budget: input5.budget,
+        abort: input5.abort,
+        maxTokens: scoutMaxOut
+      });
+      const durationMs = Date.now() - t0;
+      if (scoutRes) {
+        const files = scoutRes.output.selectedFiles.slice(0, maxScoutFiles);
+        const tokensUsed = scoutRes.usage.inputTokens + scoutRes.usage.outputTokens;
+        scoutSummary = {
+          selected: files,
+          reasoning: scoutRes.output.reasoning,
+          durationMs,
+          tokensUsed
+        };
+        scoutStats = scoutStageStats(scoutRes.usage, durationMs);
+        bus.emit({
+          kind: "scout_result",
+          runId,
+          selected: files,
+          reasoning: scoutRes.output.reasoning
+        });
+        scoutedSection = buildScoutedContextSection(
+          input5.root,
+          input5.budget,
+          files,
+          bus,
+          runId,
+          scoutRes.output.readRanges
+        );
+        bus.emit({
+          kind: "stage_complete",
+          runId,
+          stage: "scout",
+          success: true,
+          durationMs,
+          tokensUsed
+        });
+      } else {
+        bus.emit({
+          kind: "stage_complete",
+          runId,
+          stage: "scout",
+          success: false,
+          durationMs
+        });
+      }
+    } catch (err2) {
+      const msg = err2 instanceof Error ? err2.message : String(err2);
+      if (APICallError2.isInstance(err2)) {
+        const status = err2.statusCode ?? 0;
+        if (status === 401 || status === 403) {
+          throw err2;
+        }
+        if (detectModelNotFound(input5.provider, scoutModelIdStr, status, err2.responseBody ?? "")) {
+          throw err2;
         }
       }
-      toolResults.push({ toolCallId: tc.id, content: result.content, isError: result.isError });
-    }
-    turns.push({ role: "user", toolResults });
-    if (budgetExhausted) {
-      turns.push({
-        role: "user",
-        text: "Budget is exhausted. Finalise the plan with the information you already have. Do not call any more tools. Output the complete plan markdown now."
+      bus.emit({
+        kind: "stage_complete",
+        runId,
+        stage: "scout",
+        success: false,
+        durationMs: Date.now() - t0,
+        errorMessage: msg.slice(0, 200)
       });
     }
-    bus.emit({ kind: "turn_complete", runId, turn: iterations, stopReason: response.stopReason });
   }
-}
-function firstByteDiff(a, b) {
-  const n = Math.min(a.length, b.length);
-  for (let i = 0; i < n; i += 1) {
-    if (a.charCodeAt(i) !== b.charCodeAt(i)) return i;
+  const draftStarted = Date.now();
+  bus.emit({ kind: "stage_started", runId, stage: "draft" });
+  const draft = await runDraftStage({ ...merged, systemPrompt, scoutedSection });
+  bus.emit({
+    kind: "stage_complete",
+    runId,
+    stage: "draft",
+    success: draft.finishedNormally && !draft.timedOut && !draft.userCancelled,
+    durationMs: Date.now() - draftStarted
+  });
+  const validationOn = input5.validation?.enabled !== false;
+  let issues = [];
+  let validationDurationMs = 0;
+  if (validationOn && draft.planText.trim()) {
+    const v0 = Date.now();
+    bus.emit({ kind: "stage_started", runId, stage: "validation" });
+    issues = validatePlan({ root: input5.root, planText: draft.planText });
+    for (const iss of issues.slice(0, 100)) {
+      bus.emit({
+        kind: "validation_issue",
+        runId,
+        severity: iss.severity,
+        issueKind: iss.kind,
+        path: iss.path,
+        detail: iss.detail,
+        excerpt: iss.excerpt
+      });
+    }
+    validationDurationMs = Date.now() - v0;
+    bus.emit({
+      kind: "stage_complete",
+      runId,
+      stage: "validation",
+      success: true,
+      durationMs: validationDurationMs
+    });
   }
-  return n;
+  return {
+    ...draft,
+    stats: draft.stats,
+    stagesStats: { scout: scoutStats, draft: draft.stats },
+    scout: scoutSummary,
+    validation: validationOn ? { issues, durationMs: validationDurationMs } : { issues: [], durationMs: 0 }
+  };
 }
 function composePlannerError(providerName, response, retriedRateLimit, retrySkippedReason) {
   if (response.errorKind === "rate_limit") {
@@ -4297,45 +5343,39 @@ function kindTitle(kind) {
       return "Model round limit";
     case "wall_clock":
       return "Wall-clock time limit";
-    case "cost_cap":
-      return "Estimated cost cap";
     case "file_or_context_reads":
       return "File read or context size limit";
   }
 }
-function kindDetail(ctx) {
+function tokenSummary(ctx) {
   const snap = ctx.budgetSnapshot;
-  const cost = snap.usage.costUsd !== void 0 ? `Estimated spend so far: about $${snap.usage.costUsd.toFixed(2)} (provider-reported when available).` : "Estimated spend so far: not reported by the provider for this run.";
+  return `Tokens so far: ${snap.usage.inputTokens} in / ${snap.usage.outputTokens} out for this session.`;
+}
+function kindDetail(ctx) {
   switch (ctx.kind) {
     case "max_output_tokens":
       return [
         `The model hit the per-request output cap (${ctx.maxOutputTokens} completion tokens). Long plans can stop mid-markdown even though the session is otherwise healthy.`,
         "You can continue: squad-kit will ask the model to append the rest of the plan in a follow-up request (extra tokens apply).",
-        cost
+        tokenSummary(ctx)
       ];
     case "max_iterations":
       return [
         `The planner reached its round cap (${ctx.maxIterations} model turns) without a clean stop.`,
         "Continuing raises the round cap and file/time budgets for this run by another full slice from your config.",
-        cost
+        tokenSummary(ctx)
       ];
     case "wall_clock":
       return [
         "The configured wall-clock budget for this planning session elapsed before the model finished.",
         "Continuing adds another slice of time (and read/output/round limits) from your planner budget.",
-        cost
-      ];
-    case "cost_cap":
-      return [
-        "Spending crossed the optional `planner.budget.maxCostUsd` ceiling for this session.",
-        "Continuing raises that ceiling for this run by another slice from config (if a cap is set).",
-        cost
+        tokenSummary(ctx)
       ];
     case "file_or_context_reads":
       return [
         "A `read_file` call could not run because the file-read count or total read-bytes budget was exhausted.",
         "Continuing extends read, context, time, round, and output limits for this session so the model can read again or finish without reads.",
-        cost
+        tokenSummary(ctx)
       ];
   }
 }
@@ -4359,14 +5399,17 @@ function printPlannerLimitNextSteps() {
 }
 
 // src/planner/providers/index.ts
-function providerFor(name) {
-  switch (name) {
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+function resolveModel(provider, modelId, apiKey) {
+  switch (provider) {
     case "anthropic":
-      return anthropicProvider;
+      return { provider, model: createAnthropic({ apiKey })(modelId), modelId };
     case "openai":
-      return openaiProvider;
+      return { provider, model: createOpenAI({ apiKey })(modelId), modelId };
     case "google":
-      return googleProvider;
+      return { provider, model: createGoogleGenerativeAI({ apiKey })(modelId), modelId };
   }
 }
 
@@ -4377,7 +5420,6 @@ var Budget = class {
     this.maxFileReadsAllowed = cfg.maxFileReads;
     this.maxContextBytesAllowed = cfg.maxContextBytes;
     this.maxWallSeconds = cfg.maxDurationSeconds;
-    this.maxCostUsdCeiling = cfg.maxCostUsd;
   }
   cfg;
   reads = 0;
@@ -4387,15 +5429,11 @@ var Budget = class {
   maxFileReadsAllowed;
   maxContextBytesAllowed;
   maxWallSeconds;
-  maxCostUsdCeiling;
   /** Add another slice of the original config limits (used when the user chooses to continue a planner session). */
   extendSession() {
     this.maxFileReadsAllowed += this.cfg.maxFileReads;
     this.maxContextBytesAllowed += this.cfg.maxContextBytes;
     this.maxWallSeconds += this.cfg.maxDurationSeconds;
-    if (this.cfg.maxCostUsd !== void 0) {
-      this.maxCostUsdCeiling = (this.maxCostUsdCeiling ?? 0) + this.cfg.maxCostUsd;
-    }
   }
   canRead(nextFileBytes) {
     if (this.reads >= this.maxFileReadsAllowed) {
@@ -4406,6 +5444,13 @@ var Budget = class {
     }
     return { ok: true };
   }
+  /** Whether another tool invocation is allowed under the read-count budget (bytes checked per tool). */
+  canExecuteTool() {
+    if (this.reads >= this.maxFileReadsAllowed) {
+      return { ok: false, reason: `max file reads (${this.maxFileReadsAllowed}) reached` };
+    }
+    return { ok: true };
+  }
   recordRead(bytes) {
     this.reads += 1;
     this.bytes += bytes;
@@ -4413,17 +5458,12 @@ var Budget = class {
   recordUsage(u) {
     this.totalUsage.inputTokens += u.inputTokens;
     this.totalUsage.outputTokens += u.outputTokens;
-    if (u.costUsd !== void 0) this.totalUsage.costUsd = (this.totalUsage.costUsd ?? 0) + u.costUsd;
     this.totalUsage.cacheCreationTokens = (this.totalUsage.cacheCreationTokens ?? 0) + (u.cacheCreationTokens ?? 0);
     this.totalUsage.cacheReadTokens = (this.totalUsage.cacheReadTokens ?? 0) + (u.cacheReadTokens ?? 0);
   }
   timedOut() {
     return (Date.now() - this.startedAt) / 1e3 > this.maxWallSeconds;
   }
-  overCost() {
-    if (this.maxCostUsdCeiling === void 0) return false;
-    return (this.totalUsage.costUsd ?? 0) > this.maxCostUsdCeiling;
-  }
   snapshot() {
     return {
       reads: this.reads,
@@ -4434,103 +5474,9 @@ var Budget = class {
   }
 };
 
-// src/core/repo-map.ts
-import fs23 from "fs";
-import path16 from "path";
-import ignore from "ignore";
-var DEFAULT_IGNORES = [
-  "node_modules",
-  ".git",
-  "dist",
-  "build",
-  "coverage",
-  ".next",
-  ".turbo",
-  ".cache",
-  ".squad/plans"
-  // don't include existing plans as context; planner will see them separately
-];
-function buildRepoMap(root, opts = {}) {
-  const maxEntries = opts.maxEntries ?? 5e3;
-  const ig = buildIgnore(root);
-  const entries = [];
-  walk2(root, root, ig, entries, maxEntries, !!opts.includeHidden);
-  entries.sort();
-  return entries.join("\n") + "\n";
-}
-function buildIgnore(root) {
-  const ig = ignore().add(DEFAULT_IGNORES);
-  const gitignore = path16.join(root, ".gitignore");
-  if (fs23.existsSync(gitignore)) {
-    try {
-      ig.add(fs23.readFileSync(gitignore, "utf8"));
-    } catch {
-    }
-  }
-  return ig;
-}
-function walk2(root, dir, ig, out, max, includeHidden) {
-  if (out.length >= max) return;
-  let entries;
-  try {
-    entries = fs23.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (out.length >= max) return;
-    if (!includeHidden && entry.name.startsWith(".") && entry.name !== ".squad") continue;
-    const abs = path16.join(dir, entry.name);
-    const rel = path16.relative(root, abs);
-    if (!rel || ig.ignores(rel) || entry.isDirectory() && ig.ignores(rel + "/")) continue;
-    if (entry.isDirectory()) {
-      walk2(root, abs, ig, out, max, includeHidden);
-    } else if (entry.isFile()) {
-      out.push(rel);
-    }
-  }
-}
-
-// src/planner/system-prompt.ts
-function composeSystemPrompt(args) {
-  const base = readBundledPrompt("generate-plan.md").replace(/\{\{projectRoots\}\}/g, args.projectRoots.join(", ")).replace(/\{\{primaryLanguage\}\}/g, args.primaryLanguage).replace(/\{\{trackerType\}\}/g, args.trackerType).replace(
-    /\{\{intakeContent\}\}/g,
-    "_(The intake story is provided in the user message below. Do not ask for it.)_"
-  );
-  const apiPreamble = [
-    "",
-    "---",
-    "",
-    "## Direct-API mode notes",
-    "",
-    "You are being invoked by the squad-kit CLI, not by a human editor. The intake is already inlined below.",
-    "The repository tree is provided. To see the contents of any file, **call the `read_file` tool** with a repo-relative path.",
-    "You have a bounded context budget (file reads, total bytes, wall-clock time). Read files you genuinely need.",
-    "When you have enough information, output the **complete plan markdown** as your final assistant message. No prose around it, no code fences wrapping the whole plan. The CLI will write your final message verbatim to disk.",
-    "",
-    "## Repository tree",
-    "",
-    "```",
-    args.repoMap.trimEnd(),
-    "```",
-    ""
-  ].join("\n");
-  return base + apiPreamble;
-}
-function composeUserPrompt(args) {
-  return [
-    "Produce the implementation plan for the following intake.",
-    "",
-    "---",
-    "",
-    args.intakeContent.trimEnd(),
-    ""
-  ].join("\n");
-}
-
 // src/planner/writer.ts
-import fs24 from "fs";
-import path17 from "path";
+import fs28 from "fs";
+import path20 from "path";
 function planFileSlugParts(config2, story) {
   const baseSlug = slugify(story.id);
   const trackerId = config2.naming.includeTrackerId && config2.tracker.type !== "none" ? trackerIdForFilename(config2.tracker.type, story.id) : "";
@@ -4539,8 +5485,8 @@ function planFileSlugParts(config2, story) {
 }
 function writePlanFile(input5) {
   const { paths, config: config2, story } = input5;
-  const featurePlanDir = path17.join(paths.plansDir, story.feature);
-  fs24.mkdirSync(featurePlanDir, { recursive: true });
+  const featurePlanDir = path20.join(paths.plansDir, story.feature);
+  fs28.mkdirSync(featurePlanDir, { recursive: true });
   if (input5.partial) {
     return writePartialPlanFile(input5, featurePlanDir, paths, config2, story);
   }
@@ -4555,14 +5501,14 @@ function writePlanFile(input5) {
   } else {
     nn = scanPlans(paths.plansDir).nextGlobal;
     const { baseSlug, trackerPart } = planFileSlugParts(config2, story);
-    targetPath = path17.join(featurePlanDir, `${formatSequence(nn)}-story-${baseSlug}${trackerPart}.md`);
+    targetPath = path20.join(featurePlanDir, `${formatSequence(nn)}-story-${baseSlug}${trackerPart}.md`);
   }
   const body = `${input5.metadataHeader.trimEnd()}
 
 ${input5.planBodyMarkdown.trimStart()}
 `;
-  fs24.writeFileSync(targetPath, body, "utf8");
-  upsertOverviewRow(featurePlanDir, story.feature, nn, path17.basename(targetPath), story, false);
+  fs28.writeFileSync(targetPath, body, "utf8");
+  upsertOverviewRow(featurePlanDir, story.feature, nn, path20.basename(targetPath), story, false);
   return { planFile: targetPath, sequenceNumber: nn, overwrote };
 }
 function writePartialPlanFile(input5, featurePlanDir, paths, config2, story) {
@@ -4577,42 +5523,42 @@ function writePartialPlanFile(input5, featurePlanDir, paths, config2, story) {
   } else {
     nn = scanPlans(paths.plansDir).nextGlobal;
     const { baseSlug, trackerPart } = planFileSlugParts(config2, story);
-    targetPath = path17.join(featurePlanDir, `${formatSequence(nn)}-story-${baseSlug}${trackerPart}.partial.md`);
+    targetPath = path20.join(featurePlanDir, `${formatSequence(nn)}-story-${baseSlug}${trackerPart}.partial.md`);
   }
   const body = `${input5.metadataHeader.trimEnd()}
 
 ${input5.planBodyMarkdown.trimStart()}
 `;
-  fs24.writeFileSync(targetPath, body, "utf8");
-  upsertOverviewRow(featurePlanDir, story.feature, nn, path17.basename(targetPath), story, true);
+  fs28.writeFileSync(targetPath, body, "utf8");
+  upsertOverviewRow(featurePlanDir, story.feature, nn, path20.basename(targetPath), story, true);
   return { planFile: targetPath, sequenceNumber: nn, overwrote };
 }
 function findExistingPlan(featureDir, storyId) {
-  if (!fs24.existsSync(featureDir)) return void 0;
+  if (!fs28.existsSync(featureDir)) return void 0;
   const pattern = /^(\d{2,})-story-.+\.md$/;
-  for (const entry of fs24.readdirSync(featureDir)) {
+  for (const entry of fs28.readdirSync(featureDir)) {
     if (entry.endsWith(".partial.md")) continue;
     const m = entry.match(pattern);
     if (!m) continue;
-    if (entry.includes(storyId)) return { absPath: path17.join(featureDir, entry), nn: parseInt(m[1], 10) };
+    if (entry.includes(storyId)) return { absPath: path20.join(featureDir, entry), nn: parseInt(m[1], 10) };
   }
   return void 0;
 }
 function findExistingPartialPlan(featureDir, storyId) {
-  if (!fs24.existsSync(featureDir)) return void 0;
+  if (!fs28.existsSync(featureDir)) return void 0;
   const pattern = /^(\d{2,})-story-.+\.partial\.md$/;
-  for (const entry of fs24.readdirSync(featureDir)) {
+  for (const entry of fs28.readdirSync(featureDir)) {
     const m = entry.match(pattern);
     if (!m) continue;
-    if (entry.includes(storyId)) return { absPath: path17.join(featureDir, entry), nn: parseInt(m[1], 10) };
+    if (entry.includes(storyId)) return { absPath: path20.join(featureDir, entry), nn: parseInt(m[1], 10) };
   }
   return void 0;
 }
 function upsertOverviewRow(featureDir, feature, nn, filename, story, isPartial) {
-  const overviewPath = path17.join(featureDir, "00-overview.md");
+  const overviewPath = path20.join(featureDir, "00-overview.md");
   const titleCell = isPartial ? `${story.titleHint ?? story.id} (partial)` : story.titleHint ?? story.id;
   const row = `| ${formatSequence(nn)} | \`${filename}\` | ${titleCell} | ${story.id} | \u2014 |`;
-  if (!fs24.existsSync(overviewPath)) {
+  if (!fs28.existsSync(overviewPath)) {
     const content = `# ${feature} \u2014 plan overview
 
 Entry point for the **${feature}** feature. Stories execute in order by their \`NN\` prefix.
@@ -4623,10 +5569,10 @@ Entry point for the **${feature}** feature. Stories execute in order by their \`
 |----|------|-------|------------|------------|
 ${row}
 `;
-    fs24.writeFileSync(overviewPath, content, "utf8");
+    fs28.writeFileSync(overviewPath, content, "utf8");
     return;
   }
-  const current = fs24.readFileSync(overviewPath, "utf8");
+  const current = fs28.readFileSync(overviewPath, "utf8");
   const lines = current.split("\n");
   const existingIdx = lines.findIndex((l) => l.includes(`\`${filename}\``) || l.includes(`| ${formatSequence(nn)} |`));
   if (existingIdx >= 0) {
@@ -4635,7 +5581,7 @@ ${row}
     const tableEnd = findTableEnd(lines);
     lines.splice(tableEnd, 0, row);
   }
-  fs24.writeFileSync(overviewPath, lines.join("\n"), "utf8");
+  fs28.writeFileSync(overviewPath, lines.join("\n"), "utf8");
 }
 function findTableEnd(lines) {
   let inTable = false;
@@ -4654,9 +5600,17 @@ function buildMetadataHeader(args) {
     `generated by ${args.provider}/${args.model}`,
     `at ${(/* @__PURE__ */ new Date()).toISOString()}`,
     `${args.reads} reads / ${(args.bytes / 1024).toFixed(1)} KB context`,
-    `${args.inputTokens} in / ${args.outputTokens} out tokens`,
-    args.costUsd !== void 0 ? `~$${args.costUsd.toFixed(2)}` : null
+    `${args.inputTokens} in / ${args.outputTokens} out tokens`
   ].filter(Boolean);
+  if (args.scoutEnabled !== void 0) {
+    parts.push(`scout=${args.scoutEnabled ? "on" : "off"}`);
+  }
+  if (args.validationEnabled !== void 0) {
+    parts.push(`validation=${args.validationEnabled ? "on" : "off"}`);
+  }
+  if (args.validationIssueCount !== void 0) {
+    parts.push(`issues=${args.validationIssueCount}`);
+  }
   const line1 = `<!-- squad-kit: ${parts.join(", ")} -->`;
   if (args.planStatus === "partial") {
     return `${line1}
@@ -4680,16 +5634,16 @@ function buildCopyPlanPromptMarkdown(config2, intakeContent) {
 }
 
 // src/core/last-run.ts
-import fs25 from "fs/promises";
-import path18 from "path";
+import fs29 from "fs/promises";
+import path21 from "path";
 async function writeLastRun(paths, rec) {
-  const file = path18.join(paths.squadDir, ".last-run.json");
-  await fs25.writeFile(file, JSON.stringify({ ...rec, version: 1 }, null, 2) + "\n", "utf8");
+  const file = path21.join(paths.squadDir, ".last-run.json");
+  await fs29.writeFile(file, JSON.stringify({ ...rec, version: 1 }, null, 2) + "\n", "utf8");
 }
 async function readLastRun(paths) {
-  const file = path18.join(paths.squadDir, ".last-run.json");
+  const file = path21.join(paths.squadDir, ".last-run.json");
   try {
-    const raw = await fs25.readFile(file, "utf8");
+    const raw = await fs29.readFile(file, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed.version !== 1) return void 0;
     return parsed;
@@ -4718,6 +5672,59 @@ function formatPlannerCacheLine(opts) {
   return "cache miss 0% \u2014 run `squad doctor` to diagnose";
 }
 
+// src/core/plans-index.ts
+import fs30 from "fs";
+import path22 from "path";
+var MAX_ENTRIES = 30;
+function firstMarkdownH1(src) {
+  const lines = src.split(/\r?\n/);
+  for (const line2 of lines) {
+    const m = /^\s*#\s+(.+?)\s*$/.exec(line2);
+    if (m) return m[1].trim();
+  }
+  return void 0;
+}
+function collectPlanMarkdownFiles(plansDir) {
+  const out = [];
+  const walk2 = (dir) => {
+    let ents;
+    try {
+      ents = fs30.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of ents) {
+      const abs = path22.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        walk2(abs);
+      } else if (ent.isFile() && ent.name.endsWith(".md")) {
+        if (ent.name === "00-index.md" || ent.name === "00-overview.md") continue;
+        out.push(abs);
+      }
+    }
+  };
+  if (fs30.existsSync(plansDir)) walk2(plansDir);
+  out.sort((a, b) => a.localeCompare(b));
+  return out.slice(0, MAX_ENTRIES);
+}
+function buildPlansIndex(paths) {
+  const files = collectPlanMarkdownFiles(paths.plansDir);
+  if (files.length === 0) return "(no prior plans yet)";
+  const bullets = [];
+  for (const abs of files) {
+    const rel = path22.relative(paths.root, abs).split(path22.sep).join("/");
+    let title = "";
+    try {
+      const raw = fs30.readFileSync(abs, "utf8");
+      title = firstMarkdownH1(raw) ?? path22.basename(abs);
+    } catch {
+      title = path22.basename(abs);
+    }
+    bullets.push(`- ${rel} \u2014 "${title}"`);
+  }
+  return bullets.join("\n");
+}
+
 // src/commands/new-plan.ts
 function decideMode(opts, config2) {
   if (opts.api && opts.copy) {
@@ -4749,8 +5756,8 @@ async function runNewPlan(intakePath, opts) {
   }
 }
 function resolveFromPath(intakePath, stories, root) {
-  const resolved = path19.resolve(intakePath.trim());
-  if (!fs26.existsSync(resolved)) {
+  const resolved = path23.resolve(intakePath.trim());
+  if (!fs31.existsSync(resolved)) {
     throw new Error(
       `Intake not found: ${resolved}. Run \`squad list\` to see intakes, or \`squad new-story\` to create one first.`
     );
@@ -4762,7 +5769,7 @@ function resolveFromPath(intakePath, stories, root) {
   );
 }
 function relativeStoriesDir(root) {
-  return path19.relative(root, path19.join(root, ".squad", "stories"));
+  return path23.relative(root, path23.join(root, ".squad", "stories"));
 }
 async function pickStory(stories, opts) {
   const candidates = opts.all ? stories : stories.filter((s) => !s.planFile);
@@ -4793,7 +5800,7 @@ async function pickStory(stories, opts) {
       value: s.intakePath
     }))
   });
-  return candidates.find((s) => path19.resolve(s.intakePath) === path19.resolve(pick));
+  return candidates.find((s) => path23.resolve(s.intakePath) === path23.resolve(pick));
 }
 function formatLabel(s) {
   const head = `${s.feature} / ${s.id}`;
@@ -4839,13 +5846,13 @@ async function emitViaApi(story, paths, config2, opts) {
       `Missing ${providerEnvVar(planner.provider)}. Run \`squad config set planner\` to save a key to secrets, or export the env var, or run \`squad new-plan --copy\` without the API.`
     );
   }
-  const model = modelFor(planner.provider, "plan", planner.modelOverride);
-  const provider = providerFor(planner.provider);
+  const modelId = modelFor(planner.provider, "plan", planner.modelOverride);
+  const { model } = resolveModel(planner.provider, modelId, apiKey);
   const budget = new Budget(planner.budget);
   banner();
   step(`planning   ${story.feature} / ${story.id}`);
   kv("provider", planner.provider);
-  kv("model", model);
+  kv("model", modelId);
   kv(
     "budget",
     `${planner.budget.maxFileReads} reads \xB7 ${(planner.budget.maxContextBytes / 1024).toFixed(0)} KB \xB7 ${planner.budget.maxDurationSeconds}s`
@@ -4856,7 +5863,7 @@ async function emitViaApi(story, paths, config2, opts) {
     printPlannerApiCostNotice();
   }
   const mapSpinner = spinner("building repo map\u2026");
-  const repoMap = buildRepoMap(paths.root);
+  const repoMap = buildRepoMap(paths.root, { format: "tree" });
   mapSpinner.succeed(
     `repo map ready  (${repoMap.split("\n").length - 1} paths \xB7 ${(repoMap.length / 1024).toFixed(1)} KB)`
   );
@@ -4868,6 +5875,29 @@ async function emitViaApi(story, paths, config2, opts) {
     repoMap
   });
   const userPrompt = composeUserPrompt({ intakeContent: readFile(story.intakePath) });
+  const scoutEnabled = !opts.noScout && planner.stages?.scout?.enabled !== false;
+  const validationEnabled = !opts.noValidation && planner.validation?.enabled !== false;
+  const strictValidation = !!opts.strictValidation || planner.validation?.strict === true;
+  const maxScoutFiles = opts.maxScoutFiles ?? planner.stages?.scout?.maxFiles ?? 12;
+  let scoutModelId = "";
+  let scoutModelHandle;
+  let scoutSystemPrompt;
+  if (scoutEnabled) {
+    scoutModelId = modelFor(
+      planner.provider,
+      "scout",
+      planner.modelOverride,
+      opts.scoutModel ?? planner.stages?.scout?.modelOverride
+    );
+    scoutModelHandle = resolveModel(planner.provider, scoutModelId, apiKey).model;
+    scoutSystemPrompt = composeScoutSystemPrompt({
+      projectRoots: config2.project.projectRoots ?? ["."],
+      primaryLanguage: config2.project.primaryLanguage ?? "",
+      trackerType: config2.tracker.type,
+      repoMap,
+      plansIndex: buildPlansIndex(paths)
+    });
+  }
   const sessionSpinner = { current: null };
   const startedAt = Date.now();
   const cacheEnabled = planner.cache?.enabled ?? true;
@@ -4876,11 +5906,43 @@ async function emitViaApi(story, paths, config2, opts) {
   const unsubscribe = bus.subscribe((e) => {
     switch (e.kind) {
       case "tool_call": {
-        const p = e.toolCall.input.path ?? "<unknown>";
+        const name = e.toolCall.name;
+        const inp = e.toolCall.input;
+        let label;
+        if (name === "read_file") {
+          label = `read ${String(inp.path ?? "<unknown>")}`;
+        } else if (name === "grep") {
+          label = `grep ${String(inp.pattern ?? "?").slice(0, 48)}`;
+        } else if (name === "list_dir") {
+          label = `list_dir ${String(inp.path ?? "?")}`;
+        } else {
+          label = name;
+        }
         sessionSpinner.current?.succeed(
-          `read ${p}  (${(e.bytesLoaded / 1024).toFixed(1)} KB \xB7 ${(e.totalBytes / 1024).toFixed(1)} KB / ${(planner.budget.maxContextBytes / 1024).toFixed(0)} KB)`
+          `${label}  (${(e.bytesLoaded / 1024).toFixed(1)} KB \xB7 ${(e.totalBytes / 1024).toFixed(1)} KB / ${(planner.budget.maxContextBytes / 1024).toFixed(0)} KB)`
         );
-        sessionSpinner.current = spinner("reading next file\u2026");
+        sessionSpinner.current = spinner("next tool\u2026");
+        break;
+      }
+      case "stage_started": {
+        sessionSpinner.current?.stop();
+        if (e.stage === "scout") sessionSpinner.current = spinner("scouting\u2026");
+        else if (e.stage === "draft") sessionSpinner.current = spinner("drafting\u2026");
+        else if (e.stage === "validation") sessionSpinner.current = spinner("validating\u2026");
+        break;
+      }
+      case "stage_complete": {
+        if (!e.success && e.errorMessage && e.stage === "scout") {
+          sessionSpinner.current?.stop();
+          warning(`scout stage failed: ${e.errorMessage}`);
+        }
+        break;
+      }
+      case "scout_result": {
+        const preview = e.selected.slice(0, 4).join(", ");
+        const more = e.selected.length > 4 ? "\u2026" : "";
+        sessionSpinner.current?.succeed(`scout picked ${e.selected.length} files: ${preview}${more}`);
+        sessionSpinner.current = spinner("drafting\u2026");
         break;
       }
       case "assistant_text":
@@ -4888,9 +5950,11 @@ async function emitViaApi(story, paths, config2, opts) {
         sessionSpinner.current = spinner("thinking\u2026");
         break;
       case "rate_limit":
-        sessionSpinner.current?.stop();
-        warning(`${planner.provider} rate limit hit \u2014 retrying in ${e.waitSec}s`);
-        sessionSpinner.current = spinner("waiting for rate limit to reset\u2026");
+        if (e.phase === "retrying") {
+          sessionSpinner.current?.stop();
+          warning(`${e.provider} rate limit hit \u2014 retrying in ${e.waitSec}s`);
+          sessionSpinner.current = spinner("waiting for rate limit to reset\u2026");
+        }
         break;
       case "usage":
         break;
@@ -4914,9 +5978,9 @@ async function emitViaApi(story, paths, config2, opts) {
   try {
     result = await runPlanner({
       root: paths.root,
-      provider,
       model,
-      apiKey,
+      provider: planner.provider,
+      modelId,
       systemPrompt,
       userPrompt,
       budget,
@@ -4924,7 +5988,19 @@ async function emitViaApi(story, paths, config2, opts) {
       cacheEnabled,
       decideOnLimit,
       events: bus,
-      runId
+      runId,
+      stages: {
+        scout: {
+          enabled: scoutEnabled,
+          model: scoutModelHandle,
+          modelId: scoutModelId,
+          maxFiles: maxScoutFiles,
+          maxOutputTokens: planner.stages?.scout?.maxOutputTokens ?? 2048
+        }
+      },
+      validation: { enabled: validationEnabled, strict: strictValidation },
+      toolsEnabled: planner.tools,
+      scoutSystemPrompt
     });
   } finally {
     unsubscribe();
@@ -4937,17 +6013,22 @@ async function emitViaApi(story, paths, config2, opts) {
   }
   const snap = budget.snapshot();
   const elapsedMs = Date.now() - startedAt;
-  const success2 = result.finishedNormally && !result.timedOut && !result.userCancelled;
+  const issueCount = result.validation?.issues.length ?? 0;
+  const issuesByKind = summariseIssuesByKind(result.validation?.issues ?? []);
+  const validationBlocks = strictValidation && validationEnabled && issueCount > 0;
+  const success2 = result.finishedNormally && !result.timedOut && !result.userCancelled && !validationBlocks;
   const header = buildMetadataHeader({
     provider: planner.provider,
-    model,
+    model: modelId,
     reads: snap.reads,
     bytes: snap.bytes,
     inputTokens: snap.usage.inputTokens,
     outputTokens: snap.usage.outputTokens,
     durationMs: elapsedMs,
-    costUsd: snap.usage.costUsd,
-    planStatus: success2 ? void 0 : "partial"
+    planStatus: success2 ? void 0 : "partial",
+    scoutEnabled,
+    validationEnabled,
+    validationIssueCount: issueCount
   });
   const { planFile, sequenceNumber, overwrote } = writePlanFile({
     paths,
@@ -4957,18 +6038,18 @@ async function emitViaApi(story, paths, config2, opts) {
     metadataHeader: header,
     partial: !success2
   });
-  const relPlan = path19.relative(paths.root, planFile);
+  const relPlan = path23.relative(paths.root, planFile);
   try {
     await writeLastRun(paths, {
       stats: result.stats,
       completedAt: (/* @__PURE__ */ new Date()).toISOString(),
       provider: planner.provider,
-      model
+      model: modelId
     });
     await appendRun(paths, {
       runId,
       provider: planner.provider,
-      model,
+      model: modelId,
       feature: story.feature,
       storyId: story.id,
       startedAt: new Date(startedAt).toISOString(),
@@ -4978,7 +6059,19 @@ async function emitViaApi(story, paths, config2, opts) {
       planFile: relPlan,
       stats: result.stats,
       cacheEnabled,
-      durationMs: elapsedMs
+      durationMs: elapsedMs,
+      scout: {
+        enabled: scoutEnabled,
+        selectedCount: result.scout?.selected.length,
+        tokensUsed: result.scout?.tokensUsed,
+        durationMs: result.scout?.durationMs
+      },
+      validation: {
+        enabled: validationEnabled,
+        issuesCount: issueCount,
+        issuesByKind,
+        durationMs: result.validation?.durationMs
+      }
     });
   } catch {
   }
@@ -4986,11 +6079,19 @@ async function emitViaApi(story, paths, config2, opts) {
   summaryBox(success2 ? " plan generated " : " plan saved (incomplete) ", [
     { key: "file", value: relPlan },
     { key: "nn", value: String(sequenceNumber).padStart(2, "0") },
-    { key: "model", value: `${planner.provider}/${model}` },
+    { key: "model", value: `${planner.provider}/${modelId}` },
+    {
+      key: "scout",
+      value: scoutEnabled ? `${result.scout?.selected.length ?? 0} files \xB7 ${result.scout?.tokensUsed ?? 0} tok` : "disabled"
+    },
+    {
+      key: "validation",
+      value: validationEnabled ? `${issueCount} issue(s)` : "disabled"
+    },
     { key: "reads", value: `${snap.reads} files \xB7 ${(snap.bytes / 1024).toFixed(1)} KB` },
     {
       key: "tokens",
-      value: `${snap.usage.inputTokens} in \xB7 ${snap.usage.outputTokens} out${snap.usage.costUsd !== void 0 ? `  \u2248 $${snap.usage.costUsd.toFixed(2)}` : ""}`
+      value: `${snap.usage.inputTokens} in \xB7 ${snap.usage.outputTokens} out`
     },
     { key: "cache", value: formatPlannerCacheLine({ cacheEnabled, stats: result.stats }) },
     {
@@ -5000,25 +6101,45 @@ async function emitViaApi(story, paths, config2, opts) {
     { key: "time", value: `${Math.round(elapsedMs / 1e3)}s` },
     {
       key: "action",
-      value: success2 ? overwrote ? "overwrote existing plan" : "new plan" : "partial plan (review limits)"
+      value: success2 ? overwrote ? "overwrote existing plan" : "new plan" : validationBlocks ? "partial plan (validation issues \u2014 review or use --no-validation)" : "partial plan (review limits)"
     }
   ]);
+  if (issueCount > 0 && validationEnabled) {
+    blank();
+    warning(`Validation reported ${issueCount} issue(s) (heuristic; first 10 shown):`);
+    for (const iss of result.validation.issues.slice(0, 10)) {
+      info(
+        `  [${iss.severity}] ${iss.kind}${iss.path ? ` ${iss.path}` : ""} \u2014 ${iss.detail}`
+      );
+    }
+    if (issueCount > 10) {
+      info(`  (+${issueCount - 10} more \u2014 see metadata header issues=\u2026)`);
+    }
+    if (issueCount > 50) {
+      warning("Large issue count may mean the validator is misfiring; try `squad new-plan --no-validation` to compare.");
+    }
+  }
   if (!success2) {
-    printPlannerRunIncompleteSummary(result, relPlan);
+    if (!validationBlocks || !result.finishedNormally) {
+      printPlannerRunIncompleteSummary(result, relPlan);
+    } else {
+      blank();
+      warning("Plan saved as partial because strict validation reported issues.");
+    }
     throw new SquadExit(2);
   }
   if (result.budgetExhausted) {
     info("Note: file-read budget was reached; the model finalised without further reads.");
   }
   blank();
-  info(`next  \u2192  open a new agent chat and attach only ${path19.basename(planFile)}`);
+  info(`next  \u2192  open a new agent chat and attach only ${path23.basename(planFile)}`);
 }
 async function emitCopyPrompt(story, paths, config2, clipboard) {
   const intakeContent = readFile(story.intakePath);
   const composed = buildCopyPlanPromptMarkdown(config2, intakeContent);
-  const promptFile = path19.join(paths.squadDir, ".last-copy-prompt.md");
-  fs26.writeFileSync(promptFile, composed, "utf8");
-  const relPromptFile = path19.relative(paths.root, promptFile);
+  const promptFile = path23.join(paths.squadDir, ".last-copy-prompt.md");
+  fs31.writeFileSync(promptFile, composed, "utf8");
+  const relPromptFile = path23.relative(paths.root, promptFile);
   const bytes = Buffer.byteLength(composed, "utf8");
   const estTokens = Math.round(bytes / 4);
   const clipResult = clipboard ? await copyToClipboard(composed) : { ok: false, reason: "clipboard disabled (--no-clipboard)" };
@@ -5076,17 +6197,17 @@ function printModelBanner(config2) {
 }
 
 // src/commands/status.ts
-import fs27 from "fs";
+import fs32 from "fs";
 var kw = 28;
 function probeTrackerCredential(config2, overlay) {
-  const { client, error: error2 } = clientFor(config2, overlay);
+  const { client, error } = clientFor(config2, overlay);
   if (client) {
     const fromEnv = config2.tracker.type === "jira" && Boolean(process.env.JIRA_API_TOKEN || process.env.SQUAD_TRACKER_API_KEY) || config2.tracker.type === "azure" && Boolean(process.env.AZURE_DEVOPS_PAT || process.env.SQUAD_TRACKER_API_KEY);
     return { state: "present", detail: fromEnv ? "env" : "secrets.yaml" };
   }
   return {
     state: "missing",
-    hint: error2?.detail ?? "Run `squad init` to enter credentials."
+    hint: error?.detail ?? "Run `squad init` to enter credentials."
   };
 }
 function formatCredentialStatus(s) {
@@ -5102,7 +6223,7 @@ async function runStatus() {
   const scan = scanPlans(paths.plansDir);
   const storyCount = listStories(paths).length;
   const planCount = scan.usedNumbers.length;
-  const secrets = fs27.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
+  const secrets = fs32.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
   const overlay = overlayTrackerEnv(secrets);
   banner();
   step("squad-kit status");
@@ -5156,13 +6277,13 @@ function buildTrackerLine(config2, overlay) {
 }
 
 // src/commands/list.ts
-import path20 from "path";
+import path24 from "path";
 async function runList(opts) {
   const root = requireSquadRoot();
   const paths = buildPaths(root);
   const records = listStories(paths, { feature: opts.feature });
   const rows = records.map((r) => {
-    const planAbs = r.planFile ? path20.join(paths.plansDir, r.feature, r.planFile) : void 0;
+    const planAbs = r.planFile ? path24.join(paths.plansDir, r.feature, r.planFile) : void 0;
     const meta = planAbs ? readPlanMetadata(planAbs) : void 0;
     return {
       feature: r.feature,
@@ -5201,8 +6322,8 @@ function stripAnsi(s) {
 }
 
 // src/commands/tracker-link.ts
-import fs28 from "fs";
-import path21 from "path";
+import fs33 from "fs";
+import path25 from "path";
 import { input as input4, select as select7 } from "@inquirer/prompts";
 async function runTrackerLink(storyPath, trackerId, opts = {}) {
   const root = requireSquadRoot();
@@ -5249,17 +6370,17 @@ async function runTrackerLink(storyPath, trackerId, opts = {}) {
       `Invalid tracker id "${resolvedTrackerId}" for tracker type "${config2.tracker.type}". Run \`squad config show\` to review the expected format, or \`squad config set tracker\` if the type is wrong.`
     );
   }
-  const resolved = path21.resolve(resolvedStoryPath);
-  const intakeFile = resolved.endsWith("intake.md") ? resolved : path21.join(resolved, "intake.md");
-  if (!fs28.existsSync(intakeFile)) {
+  const resolved = path25.resolve(resolvedStoryPath);
+  const intakeFile = resolved.endsWith("intake.md") ? resolved : path25.join(resolved, "intake.md");
+  if (!fs33.existsSync(intakeFile)) {
     throw new Error(
       `intake.md not found at ${intakeFile}. Run \`squad list\` to see valid paths, or \`squad new-story\` to create a story first.`
     );
   }
-  const content = fs28.readFileSync(intakeFile, "utf8");
+  const content = fs33.readFileSync(intakeFile, "utf8");
   const updated = upsertTrackerId(content, resolvedTrackerId);
-  fs28.writeFileSync(intakeFile, updated, "utf8");
-  success(`Linked tracker id ${resolvedTrackerId} \u2192 ${path21.relative(root, intakeFile)}`);
+  fs33.writeFileSync(intakeFile, updated, "utf8");
+  success(`Linked tracker id ${resolvedTrackerId} \u2192 ${path25.relative(root, intakeFile)}`);
   blank();
   step("Next:");
   info("1) Review the intake \u2014 the Source block at the top now carries the tracker id.");
@@ -5277,39 +6398,39 @@ function upsertTrackerId(content, id) {
 }
 
 // src/commands/doctor-engine.ts
-import fs29 from "fs";
-import path22 from "path";
+import fs34 from "fs";
+import path26 from "path";
 async function gatherContext(paths) {
   const ctx = { hasLegacyPromptsDir: false };
   try {
     ctx.config = loadConfig(paths.configFile);
-  } catch (err) {
-    ctx.configError = err;
+  } catch (err2) {
+    ctx.configError = err2;
   }
   try {
-    ctx.secrets = fs29.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
-  } catch (err) {
-    ctx.secretsError = err;
+    ctx.secrets = fs34.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
+  } catch (err2) {
+    ctx.secretsError = err2;
   }
-  ctx.hasLegacyPromptsDir = fs29.existsSync(paths.promptsDir);
+  ctx.hasLegacyPromptsDir = fs34.existsSync(paths.promptsDir);
   return ctx;
 }
 function gitignoreHasManagedBlock(repoRoot) {
-  const gitignore = path22.join(repoRoot, ".gitignore");
-  return fs29.existsSync(gitignore) && fs29.readFileSync(gitignore, "utf8").includes(".squad/secrets.yaml");
+  const gitignore = path26.join(repoRoot, ".gitignore");
+  return fs34.existsSync(gitignore) && fs34.readFileSync(gitignore, "utf8").includes(".squad/secrets.yaml");
 }
 function gitignoreHasTrashPattern(repoRoot) {
-  const gitignore = path22.join(repoRoot, ".gitignore");
-  return fs29.existsSync(gitignore) && fs29.readFileSync(gitignore, "utf8").includes(SQUAD_TRASH_PATTERN);
+  const gitignore = path26.join(repoRoot, ".gitignore");
+  return fs34.existsSync(gitignore) && fs34.readFileSync(gitignore, "utf8").includes(SQUAD_TRASH_PATTERN);
 }
 async function checkDirStructure(paths, _ctx, fix) {
-  const need = [paths.squadDir, paths.storiesDir, paths.plansDir].filter((p) => !fs29.existsSync(p));
+  const need = [paths.squadDir, paths.storiesDir, paths.plansDir].filter((p) => !fs34.existsSync(p));
   if (need.length === 0) {
     return { id: "dirs", name: ".squad/ directory structure", status: "ok" };
   }
   if (fix) {
     for (const p of need) {
-      fs29.mkdirSync(p, { recursive: true });
+      fs34.mkdirSync(p, { recursive: true });
     }
     return { id: "dirs", name: ".squad/ directory structure", status: "ok", detail: "repaired" };
   }
@@ -5317,7 +6438,7 @@ async function checkDirStructure(paths, _ctx, fix) {
     id: "dirs",
     name: ".squad/ directory structure",
     status: "warn",
-    detail: `missing: ${need.map((p) => path22.relative(paths.root, p)).join(", ")}`,
+    detail: `missing: ${need.map((p) => path26.relative(paths.root, p)).join(", ")}`,
     fixable: true,
     fixHint: "squad doctor --fix"
   };
@@ -5372,15 +6493,15 @@ async function checkSecretsPermissions(paths, _ctx, fix) {
   if (process.platform === "win32") {
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "skip", detail: "Windows" };
   }
-  if (!fs29.existsSync(paths.secretsFile)) {
+  if (!fs34.existsSync(paths.secretsFile)) {
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "ok", detail: "not present" };
   }
-  const mode = fs29.statSync(paths.secretsFile).mode & 511;
+  const mode = fs34.statSync(paths.secretsFile).mode & 511;
   if (mode === 384) {
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "ok" };
   }
   if (fix) {
-    fs29.chmodSync(paths.secretsFile, 384);
+    fs34.chmodSync(paths.secretsFile, 384);
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "ok", detail: "repaired" };
   }
   return {
@@ -5401,7 +6522,7 @@ async function checkSecretsParseable(_paths, ctx) {
       detail: ctx.secretsError.message
     };
   }
-  if (!fs29.existsSync(_paths.secretsFile)) {
+  if (!fs34.existsSync(_paths.secretsFile)) {
     return { id: "secrets-yaml", name: ".squad/secrets.yaml parseable", status: "ok", detail: "not present" };
   }
   return { id: "secrets-yaml", name: ".squad/secrets.yaml parseable", status: "ok" };
@@ -5461,14 +6582,6 @@ async function checkPlannerConfig(_paths, ctx) {
       detail: "planner budget limits must be > 0"
     };
   }
-  if (p.budget.maxCostUsd !== void 0 && p.budget.maxCostUsd <= 0) {
-    return {
-      id: "planner-config",
-      name: "planner configuration",
-      status: "fail",
-      detail: "planner.budget.maxCostUsd must be > 0 when set"
-    };
-  }
   return { id: "planner-config", name: "planner configuration", status: "ok" };
 }
 async function checkPlannerCredential(_paths, ctx) {
@@ -5543,12 +6656,12 @@ async function checkPlannerModel(_paths, ctx) {
       status: "ok",
       detail: `${model} (${provider})`
     };
-  } catch (err) {
+  } catch (err2) {
     return {
       id: "planner-model",
       name: "planner model resolves at provider",
       status: "warn",
-      detail: err.message
+      detail: err2.message
     };
   }
 }
@@ -5681,8 +6794,8 @@ async function checkTrackerConfig(_paths, ctx) {
   }
   return { id: "tracker-config", name: "tracker configuration", status: "ok" };
 }
-function formatClientError(err) {
-  return `${err.message} ${err.detail}`.trim();
+function formatClientError(err2) {
+  return `${err2.message} ${err2.detail}`.trim();
 }
 async function checkTrackerCredential(_paths, ctx) {
   if (!ctx.config) {
@@ -5693,13 +6806,13 @@ async function checkTrackerCredential(_paths, ctx) {
   }
   const secrets = ctx.secrets ?? {};
   const overlay = overlayTrackerEnv(secrets);
-  const { client, error: error2 } = clientFor(ctx.config, overlay);
-  if (error2) {
+  const { client, error } = clientFor(ctx.config, overlay);
+  if (error) {
     return {
       id: "tracker-cred",
       name: "tracker credential resolves",
       status: "fail",
-      detail: formatClientError(error2)
+      detail: formatClientError(error)
     };
   }
   if (!client) {
@@ -5718,8 +6831,8 @@ async function checkTrackerConnectivity(paths, ctx) {
   }
   const secrets = ctx.secrets ?? {};
   const overlay = overlayTrackerEnv(secrets);
-  const { client, error: error2 } = clientFor(ctx.config, overlay);
-  if (error2 || !client) {
+  const { client, error } = clientFor(ctx.config, overlay);
+  if (error || !client) {
     return { id: "tracker-live", name: "tracker connectivity", status: "skip", detail: "no credential" };
   }
   if (client.name === "jira") {
@@ -5762,12 +6875,12 @@ async function checkTrackerConnectivity(paths, ctx) {
 async function guardCheck(checkName, fn) {
   try {
     return await fn();
-  } catch (err) {
+  } catch (err2) {
     return {
       id: "unexpected",
       name: checkName,
       status: "fail",
-      detail: err.message
+      detail: err2.message
     };
   }
 }
@@ -5895,23 +7008,23 @@ async function runDoctor(opts) {
 }
 
 // src/commands/migrate.ts
-import fs30 from "fs";
-import path23 from "path";
+import fs35 from "fs";
+import path27 from "path";
 import { confirm as confirm7 } from "@inquirer/prompts";
 var LEGACY_PROMPTS_MIGRATION = {
   id: "legacy-prompts",
   name: "Remove legacy .squad/prompts/",
-  isApplied: (paths) => !fs30.existsSync(paths.promptsDir),
-  describe: (paths) => `delete ${path23.relative(paths.root, paths.promptsDir)} (prompts are now bundled in squad-kit)`,
+  isApplied: (paths) => !fs35.existsSync(paths.promptsDir),
+  describe: (paths) => `delete ${path27.relative(paths.root, paths.promptsDir)} (prompts are now bundled in squad-kit)`,
   apply: (paths) => {
     const target = paths.promptsDir;
-    if (!target.includes(path23.sep + ".squad" + path23.sep + "prompts")) {
+    if (!target.includes(path27.sep + ".squad" + path27.sep + "prompts")) {
       throw new Error(
         `Refusing to delete suspicious path: ${target}. This is a safety check \u2014 run \`squad doctor\` if .squad/ paths look wrong.`
       );
     }
-    if (fs30.existsSync(target)) {
-      fs30.rmSync(target, { recursive: true, force: true });
+    if (fs35.existsSync(target)) {
+      fs35.rmSync(target, { recursive: true, force: true });
     }
   }
 };
@@ -5919,8 +7032,8 @@ var GITIGNORE_MIGRATION = {
   id: "gitignore",
   name: "Ensure .gitignore managed block",
   isApplied: (paths) => {
-    const f = path23.join(paths.root, ".gitignore");
-    return fs30.existsSync(f) && fs30.readFileSync(f, "utf8").includes(".squad/secrets.yaml");
+    const f = path27.join(paths.root, ".gitignore");
+    return fs35.existsSync(f) && fs35.readFileSync(f, "utf8").includes(".squad/secrets.yaml");
   },
   describe: () => "add squad-kit managed block to .gitignore",
   apply: (paths) => {
@@ -5932,23 +7045,23 @@ var SECRETS_PERMS_MIGRATION = {
   name: "Tighten .squad/secrets.yaml permissions",
   isApplied: (paths) => {
     if (process.platform === "win32") return true;
-    if (!fs30.existsSync(paths.secretsFile)) return true;
-    const st = fs30.statSync(paths.secretsFile);
+    if (!fs35.existsSync(paths.secretsFile)) return true;
+    const st = fs35.statSync(paths.secretsFile);
     return (st.mode & 511) === 384;
   },
-  describe: (paths) => `chmod 0600 ${path23.relative(paths.root, paths.secretsFile)}`,
+  describe: (paths) => `chmod 0600 ${path27.relative(paths.root, paths.secretsFile)}`,
   apply: (paths) => {
     if (process.platform === "win32") return;
-    if (fs30.existsSync(paths.secretsFile)) fs30.chmodSync(paths.secretsFile, 384);
+    if (fs35.existsSync(paths.secretsFile)) fs35.chmodSync(paths.secretsFile, 384);
   }
 };
 var PLANNER_BUDGET_DEFAULTS_MIGRATION = {
   id: "planner-budget-defaults",
   name: "Backfill planner.budget defaults in config.yaml",
   isApplied: (paths) => {
-    if (!fs30.existsSync(paths.configFile)) return true;
+    if (!fs35.existsSync(paths.configFile)) return true;
     try {
-      const raw = fs30.readFileSync(paths.configFile, "utf8");
+      const raw = fs35.readFileSync(paths.configFile, "utf8");
       if (!/^\s*planner:/m.test(raw)) return true;
       if (/^\s*budget:/m.test(raw)) return true;
       const cfg = loadConfig(paths.configFile);
@@ -5967,9 +7080,9 @@ var CONFIG_NORMALIZE_MIGRATION = {
   id: "config-normalize",
   name: "Normalise .squad/config.yaml formatting",
   isApplied: (paths) => {
-    if (!fs30.existsSync(paths.configFile)) return true;
+    if (!fs35.existsSync(paths.configFile)) return true;
     try {
-      const raw = fs30.readFileSync(paths.configFile, "utf8");
+      const raw = fs35.readFileSync(paths.configFile, "utf8");
       const cfg = loadConfig(paths.configFile);
       return raw.trim() === serializeConfig(cfg).trim();
     } catch {
@@ -5978,7 +7091,7 @@ var CONFIG_NORMALIZE_MIGRATION = {
   },
   describe: () => "rewrite config.yaml with canonical YAML formatting (drops comments)",
   apply: (paths) => {
-    if (!fs30.existsSync(paths.configFile)) return;
+    if (!fs35.existsSync(paths.configFile)) return;
     const cfg = loadConfig(paths.configFile);
     saveConfig(paths.configFile, cfg);
   }
@@ -6039,8 +7152,8 @@ async function runMigrate(opts) {
       await Promise.resolve(m.apply(paths));
       spin.succeed(`${m.name} \u2014 applied`);
       applied++;
-    } catch (err) {
-      spin.fail(`${m.name} \u2014 failed: ${err.message}`);
+    } catch (err2) {
+      spin.fail(`${m.name} \u2014 failed: ${err2.message}`);
       process.exit(1);
     }
   }
@@ -6059,8 +7172,8 @@ import process3 from "process";
 import { confirm as confirm8 } from "@inquirer/prompts";
 
 // src/core/package-info.ts
-import fs31 from "fs";
-import path24 from "path";
+import fs36 from "fs";
+import path28 from "path";
 function changelogBlobUrl(repositoryUrl, version) {
   let base = repositoryUrl;
   if (!base) base = "https://github.com/AzmSquad/squad-kit";
@@ -6071,9 +7184,9 @@ function changelogBlobUrl(repositoryUrl, version) {
 }
 function readInstalledPackage() {
   const root = packageRoot();
-  const pkgFile = path24.join(root, "package.json");
-  const pkg = JSON.parse(fs31.readFileSync(pkgFile, "utf8"));
-  const isDevInstall = fs31.existsSync(path24.join(root, "src"));
+  const pkgFile = path28.join(root, "package.json");
+  const pkg = JSON.parse(fs36.readFileSync(pkgFile, "utf8"));
+  const isDevInstall = fs36.existsSync(path28.join(root, "src"));
   return {
     name: pkg.name,
     version: pkg.version,
@@ -6113,7 +7226,7 @@ function isNewer(a, b) {
 }
 
 // src/core/package-manager.ts
-import path25 from "path";
+import path29 from "path";
 import process2 from "process";
 function detectPackageManager(installRoot) {
   const ua = process2.env.npm_config_user_agent;
@@ -6124,11 +7237,11 @@ function detectPackageManager(installRoot) {
     if (ua.startsWith("npm/")) return { pm: "npm", reason: "npm_config_user_agent" };
   }
   const root = installRoot.toLowerCase();
-  if (root.includes(`${path25.sep}pnpm${path25.sep}`) || root.includes(`${path25.sep}.pnpm${path25.sep}`))
+  if (root.includes(`${path29.sep}pnpm${path29.sep}`) || root.includes(`${path29.sep}.pnpm${path29.sep}`))
     return { pm: "pnpm", reason: `install path contains pnpm` };
-  if (root.includes(`${path25.sep}.yarn${path25.sep}`) || root.includes(`${path25.sep}yarn${path25.sep}`))
+  if (root.includes(`${path29.sep}.yarn${path29.sep}`) || root.includes(`${path29.sep}yarn${path29.sep}`))
     return { pm: "yarn", reason: `install path contains yarn` };
-  if (root.includes(`${path25.sep}.bun${path25.sep}`) || root.includes(`${path25.sep}bun${path25.sep}`))
+  if (root.includes(`${path29.sep}.bun${path29.sep}`) || root.includes(`${path29.sep}bun${path29.sep}`))
     return { pm: "bun", reason: `install path contains bun` };
   return { pm: "npm", reason: "default fallback" };
 }
@@ -6162,9 +7275,9 @@ async function runUpgrade(opts) {
   try {
     const info2 = await fetchLatest(installed.name);
     latest = info2.latest;
-  } catch (err) {
+  } catch (err2) {
     failure(
-      `Could not reach the npm registry: ${err.message}. Check your network, then run \`pnpm add -g squad-kit@latest\` (or \`npm i -g squad-kit@latest\`) manually.`
+      `Could not reach the npm registry: ${err2.message}. Check your network, then run \`pnpm add -g squad-kit@latest\` (or \`npm i -g squad-kit@latest\`) manually.`
     );
     process3.exit(1);
   }
@@ -6224,7 +7337,7 @@ function spawnInherit(cmd, args) {
   return new Promise((resolve2, reject) => {
     const child = spawn2(cmd, args, { stdio: "inherit", shell: process3.platform === "win32" });
     child.on("exit", (code) => resolve2(code ?? 0));
-    child.on("error", (err) => reject(err));
+    child.on("error", (err2) => reject(err2));
   });
 }
 
@@ -6241,25 +7354,25 @@ import { cors } from "hono/cors";
 import { secureHeaders } from "hono/secure-headers";
 
 // src/console/api/stories.ts
-import fs32 from "fs";
-import { z } from "zod";
+import fs37 from "fs";
+import { z as z5 } from "zod";
 
 // src/utils/path-safety.ts
-import path26 from "path";
+import path30 from "path";
 function isInside(abs, parent) {
-  const a = path26.resolve(abs) + path26.sep;
-  const p = path26.resolve(parent) + path26.sep;
+  const a = path30.resolve(abs) + path30.sep;
+  const p = path30.resolve(parent) + path30.sep;
   return a.startsWith(p);
 }
 
 // src/console/api/stories.ts
-var CreateBody = z.object({
-  feature: z.string().min(1).max(80),
-  title: z.string().max(200).optional(),
-  trackerId: z.string().max(80).optional()
+var CreateBody = z5.object({
+  feature: z5.string().min(1).max(80),
+  title: z5.string().max(200).optional(),
+  trackerId: z5.string().max(80).optional()
 });
-var PatchBody = z.object({
-  intakeContent: z.string().min(1).max(1e6)
+var PatchBody = z5.object({
+  intakeContent: z5.string().min(1).max(1e6)
 });
 function safeFeatureParam(feature) {
   return feature.length > 0 && !feature.includes("/") && !feature.includes("..") && slugify(feature) === feature;
@@ -6288,7 +7401,7 @@ function mountStoriesApi(app, opts) {
     if (!isInside(hit.intakePath, opts.paths.storiesDir)) return c.json({ error: "forbidden" }, 403);
     let intakeContent = "";
     try {
-      intakeContent = fs32.readFileSync(hit.intakePath, "utf8");
+      intakeContent = fs37.readFileSync(hit.intakePath, "utf8");
     } catch {
     }
     return c.json({
@@ -6332,7 +7445,7 @@ function mountStoriesApi(app, opts) {
     const hit = stories.find((s) => s.id === id);
     if (!hit) return c.json({ error: "not_found" }, 404);
     if (!isInside(hit.intakePath, opts.paths.storiesDir)) return c.json({ error: "forbidden" }, 403);
-    fs32.writeFileSync(hit.intakePath, body.data.intakeContent, "utf8");
+    fs37.writeFileSync(hit.intakePath, body.data.intakeContent, "utf8");
     return c.json({ ok: true });
   });
   app.delete("/api/stories/:feature/:id", (c) => {
@@ -6349,14 +7462,14 @@ function mountStoriesApi(app, opts) {
 }
 
 // src/console/api/plans.ts
-import fs33 from "fs";
-import path27 from "path";
-import { z as z2 } from "zod";
+import fs38 from "fs";
+import path31 from "path";
+import { z as z6 } from "zod";
 import { diffLines } from "diff";
-var DiffQuery = z2.object({
-  feature: z2.string().min(1).max(80),
-  a: z2.string().min(1).max(200),
-  b: z2.string().min(1).max(200)
+var DiffQuery = z6.object({
+  feature: z6.string().min(1).max(80),
+  a: z6.string().min(1).max(200),
+  b: z6.string().min(1).max(200)
 });
 function safeFeatureParam2(feature) {
   return feature.length > 0 && !feature.includes("/") && !feature.includes("..") && slugify(feature) === feature;
@@ -6365,11 +7478,11 @@ function mountPlansApi(app, opts) {
   app.get("/api/plans", (c) => {
     const out = [];
     for (const feature of listPlanFeatureNames(opts.paths)) {
-      const featureDir = path27.join(opts.paths.plansDir, feature);
-      if (!fs33.existsSync(featureDir)) continue;
-      for (const entry of fs33.readdirSync(featureDir)) {
+      const featureDir = path31.join(opts.paths.plansDir, feature);
+      if (!fs38.existsSync(featureDir)) continue;
+      for (const entry of fs38.readdirSync(featureDir)) {
         if (!entry.endsWith(".md") || entry === "00-index.md") continue;
-        const abs = path27.join(featureDir, entry);
+        const abs = path31.join(featureDir, entry);
         out.push({ feature, planFile: entry, metadata: readPlanMetadata(abs) });
       }
     }
@@ -6378,10 +7491,10 @@ function mountPlansApi(app, opts) {
   app.get("/api/plans/:feature/:planFile", (c) => {
     const { feature, planFile } = c.req.param();
     if (!safeFeatureParam2(feature)) return c.json({ error: "forbidden" }, 403);
-    const abs = path27.resolve(path27.join(opts.paths.plansDir, feature, planFile));
+    const abs = path31.resolve(path31.join(opts.paths.plansDir, feature, planFile));
     if (!isInside(abs, opts.paths.plansDir)) return c.json({ error: "forbidden" }, 403);
-    if (!fs33.existsSync(abs)) return c.json({ error: "not_found" }, 404);
-    const content = fs33.readFileSync(abs, "utf8");
+    if (!fs38.existsSync(abs)) return c.json({ error: "not_found" }, 404);
+    const content = fs38.readFileSync(abs, "utf8");
     return c.json({
       feature,
       planFile,
@@ -6399,15 +7512,15 @@ function mountPlansApi(app, opts) {
     if (!parse.success) return c.json({ error: "invalid_query", issues: parse.error.issues }, 400);
     const { feature, a, b } = parse.data;
     if (!safeFeatureParam2(feature)) return c.json({ error: "forbidden" }, 403);
-    const featureDir = path27.join(opts.paths.plansDir, feature);
-    const aAbs = path27.join(featureDir, a);
-    const bAbs = path27.join(featureDir, b);
+    const featureDir = path31.join(opts.paths.plansDir, feature);
+    const aAbs = path31.join(featureDir, a);
+    const bAbs = path31.join(featureDir, b);
     if (!isInside(aAbs, opts.paths.plansDir) || !isInside(bAbs, opts.paths.plansDir)) {
       return c.json({ error: "forbidden" }, 403);
     }
-    if (!fs33.existsSync(aAbs) || !fs33.existsSync(bAbs)) return c.json({ error: "not_found" }, 404);
-    const aText = fs33.readFileSync(aAbs, "utf8");
-    const bText = fs33.readFileSync(bAbs, "utf8");
+    if (!fs38.existsSync(aAbs) || !fs38.existsSync(bAbs)) return c.json({ error: "not_found" }, 404);
+    const aText = fs38.readFileSync(aAbs, "utf8");
+    const bText = fs38.readFileSync(bAbs, "utf8");
     const changes = diffLines(aText, bText);
     return c.json({ feature, a, b, changes });
   });
@@ -6415,23 +7528,23 @@ function mountPlansApi(app, opts) {
     const trash = c.req.query("trash") === "1";
     const { feature, planFile } = c.req.param();
     if (!safeFeatureParam2(feature)) return c.json({ error: "forbidden" }, 403);
-    const abs = path27.join(opts.paths.plansDir, feature, planFile);
+    const abs = path31.join(opts.paths.plansDir, feature, planFile);
     if (!isInside(abs, opts.paths.plansDir)) return c.json({ error: "forbidden" }, 403);
-    if (!fs33.existsSync(abs)) return c.json({ error: "not_found" }, 404);
+    if (!fs38.existsSync(abs)) return c.json({ error: "not_found" }, 404);
     if (trash) {
       const result = trashOrDelete([abs], opts.paths.trashDir, true);
-      removeOverviewRowForPlanFile(path27.join(opts.paths.plansDir, feature), planFile);
+      removeOverviewRowForPlanFile(path31.join(opts.paths.plansDir, feature), planFile);
       return c.json({ ok: true, trashed: result.trashed });
     }
-    fs33.rmSync(abs);
-    removeOverviewRowForPlanFile(path27.join(opts.paths.plansDir, feature), planFile);
+    fs38.rmSync(abs);
+    removeOverviewRowForPlanFile(path31.join(opts.paths.plansDir, feature), planFile);
     return c.json({ ok: true });
   });
 }
 
 // src/console/api/config.ts
-import { z as z3 } from "zod";
-var ConfigBody = z3.object({}).passthrough();
+import { z as z7 } from "zod";
+var ConfigBody = z7.object({}).passthrough();
 function mountConfigApi(app, opts) {
   app.get("/api/config", (c) => {
     const config2 = loadConfig(opts.paths.configFile);
@@ -6443,8 +7556,8 @@ function mountConfigApi(app, opts) {
     try {
       saveConfig(opts.paths.configFile, body.data);
       return c.json({ ok: true });
-    } catch (err) {
-      return c.json({ error: "invalid_config", detail: err.message }, 400);
+    } catch (err2) {
+      return c.json({ error: "invalid_config", detail: err2.message }, 400);
     }
   });
 }
@@ -6471,14 +7584,14 @@ function mountMetaApi(app, opts) {
 
 // src/console/api/runs.ts
 import { streamSSE } from "hono/streaming";
-import { z as z4 } from "zod";
-import path28 from "path";
-import fs34 from "fs";
+import { z as z8 } from "zod";
+import path32 from "path";
+import fs39 from "fs";
 var active = /* @__PURE__ */ new Map();
 var EVENT_BUF_CAP = 512;
-var StartBody = z4.object({
-  feature: z4.string().min(1),
-  storyId: z4.string().min(1)
+var StartBody = z8.object({
+  feature: z8.string().min(1),
+  storyId: z8.string().min(1)
 });
 function emptyStats(durationMs) {
   return {
@@ -6534,11 +7647,36 @@ function mountRunsApi(app, opts) {
     const done = (async () => {
       const cfgFresh = loadConfig(opts.paths.configFile);
       const planner = cfgFresh.planner;
-      const provider = providerFor(planner.provider);
-      const model = modelFor(planner.provider, "plan", planner.modelOverride);
+      const modelId = modelFor(planner.provider, "plan", planner.modelOverride);
+      const { model } = resolveModel(planner.provider, modelId, apiKey);
       const budget = new Budget(planner.budget);
       const cacheEnabled = planner.cache?.enabled ?? true;
-      const repoMap = buildRepoMap(opts.paths.root);
+      const scoutEnabled = planner.stages?.scout?.enabled !== false;
+      const validationEnabled = planner.validation?.enabled !== false;
+      const strictValidation = planner.validation?.strict === true;
+      const maxScoutFiles = planner.stages?.scout?.maxFiles ?? 12;
+      let scoutModelId = "";
+      let scoutModelHandle;
+      let scoutSystemPrompt;
+      if (scoutEnabled) {
+        scoutModelId = modelFor(
+          planner.provider,
+          "scout",
+          planner.modelOverride,
+          planner.stages?.scout?.modelOverride
+        );
+        scoutModelHandle = resolveModel(planner.provider, scoutModelId, apiKey).model;
+      }
+      const repoMap = buildRepoMap(opts.paths.root, { format: "tree" });
+      if (scoutEnabled) {
+        scoutSystemPrompt = composeScoutSystemPrompt({
+          projectRoots: cfgFresh.project.projectRoots ?? ["."],
+          primaryLanguage: cfgFresh.project.primaryLanguage ?? "",
+          trackerType: cfgFresh.tracker.type,
+          repoMap,
+          plansIndex: buildPlansIndex(opts.paths)
+        });
+      }
       const systemPrompt = composeSystemPrompt({
         projectRoots: cfgFresh.project.projectRoots ?? ["."],
         primaryLanguage: cfgFresh.project.primaryLanguage ?? "",
@@ -6546,15 +7684,15 @@ function mountRunsApi(app, opts) {
         repoMap
       });
       const userPrompt = composeUserPrompt({
-        intakeContent: fs34.readFileSync(story.intakePath, "utf8")
+        intakeContent: fs39.readFileSync(story.intakePath, "utf8")
       });
       let result;
       try {
         result = await runPlanner({
           root: opts.paths.root,
-          provider,
           model,
-          apiKey,
+          provider: planner.provider,
+          modelId,
           systemPrompt,
           userPrompt,
           budget,
@@ -6562,11 +7700,27 @@ function mountRunsApi(app, opts) {
           cacheEnabled,
           events: bus,
           runId,
-          abort: controller.signal
+          abort: controller.signal,
+          stages: {
+            scout: {
+              enabled: scoutEnabled,
+              model: scoutModelHandle,
+              modelId: scoutModelId,
+              maxFiles: maxScoutFiles,
+              maxOutputTokens: planner.stages?.scout?.maxOutputTokens ?? 2048
+            }
+          },
+          validation: { enabled: validationEnabled, strict: strictValidation },
+          toolsEnabled: planner.tools,
+          scoutSystemPrompt
         });
-      } catch (err) {
+      } catch (err2) {
         const durationMs = Date.now() - startedAt;
-        bus.emit({ kind: "error", runId, message: err.message });
+        const last = eventBuffer[eventBuffer.length - 1];
+        const isRateLimitAbort = last?.kind === "rate_limit" && last.phase === "aborted";
+        if (!isRateLimitAbort) {
+          bus.emit({ kind: "error", runId, message: err2.message });
+        }
         bus.emit({
           kind: "done",
           runId,
@@ -6578,20 +7732,25 @@ function mountRunsApi(app, opts) {
         });
         return;
       }
-      const runSuccess = result.finishedNormally && !result.timedOut && !result.userCancelled;
+      const issueCount = result.validation?.issues.length ?? 0;
+      const issuesByKind = summariseIssuesByKind(result.validation?.issues ?? []);
+      const validationBlocks = strictValidation && validationEnabled && issueCount > 0;
+      const runSuccess = result.finishedNormally && !result.timedOut && !result.userCancelled && !validationBlocks;
       let planFile = null;
       if (result.planText.trim()) {
         const snap = budget.snapshot();
         const header = buildMetadataHeader({
           provider: planner.provider,
-          model,
+          model: modelId,
           reads: snap.reads,
           bytes: snap.bytes,
           inputTokens: snap.usage.inputTokens,
           outputTokens: snap.usage.outputTokens,
           durationMs: Date.now() - startedAt,
-          costUsd: snap.usage.costUsd,
-          planStatus: runSuccess ? void 0 : "partial"
+          planStatus: runSuccess ? void 0 : "partial",
+          scoutEnabled,
+          validationEnabled,
+          validationIssueCount: issueCount
         });
         const out = writePlanFile({
           paths: opts.paths,
@@ -6601,19 +7760,19 @@ function mountRunsApi(app, opts) {
           metadataHeader: header,
           partial: !runSuccess
         });
-        planFile = path28.relative(opts.paths.root, out.planFile);
+        planFile = path32.relative(opts.paths.root, out.planFile);
       }
       try {
         await writeLastRun(opts.paths, {
           stats: result.stats,
           completedAt: (/* @__PURE__ */ new Date()).toISOString(),
           provider: planner.provider,
-          model
+          model: modelId
         });
         await appendRun(opts.paths, {
           runId,
           provider: planner.provider,
-          model,
+          model: modelId,
           feature: story.feature,
           storyId: story.id,
           startedAt: new Date(startedAt).toISOString(),
@@ -6623,7 +7782,19 @@ function mountRunsApi(app, opts) {
           planFile,
           stats: result.stats,
           cacheEnabled,
-          durationMs: Date.now() - startedAt
+          durationMs: Date.now() - startedAt,
+          scout: {
+            enabled: scoutEnabled,
+            selectedCount: result.scout?.selected.length,
+            tokensUsed: result.scout?.tokensUsed,
+            durationMs: result.scout?.durationMs
+          },
+          validation: {
+            enabled: validationEnabled,
+            issuesCount: issueCount,
+            issuesByKind,
+            durationMs: result.validation?.durationMs
+          }
         });
       } catch {
       }
@@ -6696,7 +7867,7 @@ function mountRunsApi(app, opts) {
 }
 
 // src/console/api/secrets.ts
-import { z as z5 } from "zod";
+import { z as z9 } from "zod";
 
 // src/core/mask-token.ts
 function maskToken(t) {
@@ -6734,26 +7905,26 @@ function mountSecretsApi(app, opts) {
       }
     });
   });
-  const PutBody = z5.object({
-    planner: z5.object({
-      anthropic: z5.string().optional(),
-      openai: z5.string().optional(),
-      google: z5.string().optional()
+  const PutBody = z9.object({
+    planner: z9.object({
+      anthropic: z9.string().optional(),
+      openai: z9.string().optional(),
+      google: z9.string().optional()
     }).optional(),
-    tracker: z5.object({
-      jira: z5.object({
-        host: z5.string().optional(),
-        email: z5.string().optional(),
-        token: z5.string().optional()
+    tracker: z9.object({
+      jira: z9.object({
+        host: z9.string().optional(),
+        email: z9.string().optional(),
+        token: z9.string().optional()
       }).optional(),
-      azure: z5.object({
-        organization: z5.string().optional(),
-        project: z5.string().optional(),
-        pat: z5.string().optional()
+      azure: z9.object({
+        organization: z9.string().optional(),
+        project: z9.string().optional(),
+        pat: z9.string().optional()
       }).optional(),
-      github: z5.object({
-        host: z5.string().optional(),
-        pat: z5.string().optional()
+      github: z9.object({
+        host: z9.string().optional(),
+        pat: z9.string().optional()
       }).optional()
     }).optional()
   });
@@ -6793,12 +7964,12 @@ function mountSecretsApi(app, opts) {
 }
 
 // src/console/api/tracker.ts
-import { z as z6 } from "zod";
-var SearchQuery = z6.object({ q: z6.string().max(500) });
-var ImportBody = z6.object({
-  issueId: z6.string().min(1),
-  feature: z6.string().min(1).max(80),
-  withAttachments: z6.boolean().optional()
+import { z as z10 } from "zod";
+var SearchQuery = z10.object({ q: z10.string().max(500) });
+var ImportBody = z10.object({
+  issueId: z10.string().min(1),
+  feature: z10.string().min(1).max(80),
+  withAttachments: z10.boolean().optional()
 });
 function mountTrackerApi(app, opts) {
   app.get("/api/tracker/search", async (c) => {
@@ -6806,18 +7977,18 @@ function mountTrackerApi(app, opts) {
     if (!q.success) return c.json({ error: "invalid_query" }, 400);
     const cfg = loadConfig(opts.paths.configFile);
     const secrets = overlayTrackerEnv(loadSecrets(opts.paths.secretsFile));
-    const { client, error: error2 } = clientFor(cfg, secrets);
+    const { client, error } = clientFor(cfg, secrets);
     if (!client) {
-      return c.json({ error: error2?.kind ?? "unsupported", detail: error2?.detail ?? "" }, 400);
+      return c.json({ error: error?.kind ?? "unsupported", detail: error?.detail ?? "" }, 400);
     }
     try {
       const results = await client.searchIssues(q.data.q);
       return c.json({ ok: true, results });
-    } catch (err) {
-      if (err instanceof TrackerError) {
-        return c.json({ ok: false, kind: err.kind, status: err.statusCode, detail: err.message }, 200);
+    } catch (err2) {
+      if (err2 instanceof TrackerError) {
+        return c.json({ ok: false, kind: err2.kind, status: err2.statusCode, detail: err2.message }, 200);
       }
-      return c.json({ ok: false, detail: err.message }, 200);
+      return c.json({ ok: false, detail: err2.message }, 200);
     }
   });
   app.post("/api/tracker/import", async (c) => {
@@ -6825,9 +7996,9 @@ function mountTrackerApi(app, opts) {
     if (!body.success) return c.json({ error: "invalid_body", issues: body.error.issues }, 400);
     const cfg = loadConfig(opts.paths.configFile);
     const secrets = overlayTrackerEnv(loadSecrets(opts.paths.secretsFile));
-    const { client, error: error2 } = clientFor(cfg, secrets);
+    const { client, error } = clientFor(cfg, secrets);
     if (!client) {
-      return c.json({ error: error2?.kind ?? "unsupported", detail: error2?.detail ?? "" }, 400);
+      return c.json({ error: error?.kind ?? "unsupported", detail: error?.detail ?? "" }, 400);
     }
     try {
       const issue = await client.fetchIssue(body.data.issueId);
@@ -6840,9 +8011,9 @@ function mountTrackerApi(app, opts) {
         config: cfg
       });
       return c.json(created, 201);
-    } catch (err) {
-      if (err instanceof TrackerError) return c.json({ error: err.kind, detail: err.message }, 502);
-      return c.json({ error: "fetch_failed", detail: err.message }, 500);
+    } catch (err2) {
+      if (err2 instanceof TrackerError) return c.json({ error: err2.kind, detail: err2.message }, 502);
+      return c.json({ error: "fetch_failed", detail: err2.message }, 500);
     }
   });
 }
@@ -6939,17 +8110,17 @@ function countStories(stories) {
 }
 
 // src/console/api/projects.ts
-import fs35 from "fs/promises";
-import path29 from "path";
+import fs40 from "fs/promises";
+import path33 from "path";
 import os from "os";
 var MAX = 10;
 function recentFilePath() {
-  return path29.join(os.homedir(), ".squad", "recent-projects.json");
+  return path33.join(os.homedir(), ".squad", "recent-projects.json");
 }
 async function loadRecent() {
   const RECENT_FILE = recentFilePath();
   try {
-    const raw = await fs35.readFile(RECENT_FILE, "utf8");
+    const raw = await fs40.readFile(RECENT_FILE, "utf8");
     const parsed = JSON.parse(raw);
     return Array.isArray(parsed) ? parsed.slice(0, MAX) : [];
   } catch {
@@ -6958,8 +8129,8 @@ async function loadRecent() {
 }
 async function saveRecent(list) {
   const RECENT_FILE = recentFilePath();
-  await fs35.mkdir(path29.dirname(RECENT_FILE), { recursive: true });
-  await fs35.writeFile(RECENT_FILE, JSON.stringify(list.slice(0, MAX), null, 2) + "\n", "utf8");
+  await fs40.mkdir(path33.dirname(RECENT_FILE), { recursive: true });
+  await fs40.writeFile(RECENT_FILE, JSON.stringify(list.slice(0, MAX), null, 2) + "\n", "utf8");
 }
 function mountProjectsApi(app, opts) {
   app.get("/api/projects/recent", async (c) => c.json(await loadRecent()));
@@ -6988,8 +8159,8 @@ function mountApi(app, opts) {
 }
 
 // src/console/static-assets.ts
-import fs36 from "fs";
-import path30 from "path";
+import fs41 from "fs";
+import path34 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Readable } from "stream";
 function pathnameForStatic(c) {
@@ -7019,18 +8190,18 @@ function mountStaticAssets(app, _opts) {
     }
     if (c.req.path.startsWith("/api/") || c.req.path.startsWith("/healthz")) return c.notFound();
     if (!distDir) return c.text("UI not built. Run `pnpm -C console-ui build`.", 404);
-    const indexHtml = path30.join(distDir, "index.html");
-    if (!fs36.existsSync(indexHtml)) return c.text("UI not built", 404);
-    return c.html(fs36.readFileSync(indexHtml, "utf8"), 200, { "cache-control": "no-store" });
+    const indexHtml = path34.join(distDir, "index.html");
+    if (!fs41.existsSync(indexHtml)) return c.text("UI not built", 404);
+    return c.html(fs41.readFileSync(indexHtml, "utf8"), 200, { "cache-control": "no-store" });
   });
 }
 function assetResponse(c, distDir, pathname) {
   if (!distDir) return c.text("UI not built", 404);
   const rel = pathname.replace(/^\//, "");
-  const abs = path30.normalize(path30.join(distDir, rel));
+  const abs = path34.normalize(path34.join(distDir, rel));
   if (!isInside2(abs, distDir)) return c.text("forbidden", 403);
-  if (!fs36.existsSync(abs) || !fs36.statSync(abs).isFile()) return c.text("not found", 404);
-  const body = Readable.toWeb(fs36.createReadStream(abs));
+  if (!fs41.existsSync(abs) || !fs41.statSync(abs).isFile()) return c.text("not found", 404);
+  const body = Readable.toWeb(fs41.createReadStream(abs));
   return new Response(body, {
     headers: {
       "content-type": contentTypeFor(abs),
@@ -7040,9 +8211,9 @@ function assetResponse(c, distDir, pathname) {
 }
 function serveFile(c, distDir, name, ct) {
   if (!distDir) return c.text("UI not built", 404);
-  const abs = path30.join(distDir, name);
-  if (!fs36.existsSync(abs)) return c.text("not found", 404);
-  return new Response(fs36.readFileSync(abs), {
+  const abs = path34.join(distDir, name);
+  if (!fs41.existsSync(abs)) return c.text("not found", 404);
+  return new Response(fs41.readFileSync(abs), {
     headers: { "content-type": ct, "cache-control": "public, max-age=86400" }
   });
 }
@@ -7057,13 +8228,13 @@ function contentTypeFor(p) {
   return "application/octet-stream";
 }
 function isInside2(abs, parent) {
-  const a = path30.resolve(abs) + path30.sep;
-  const p = path30.resolve(parent) + path30.sep;
+  const a = path34.resolve(abs) + path34.sep;
+  const p = path34.resolve(parent) + path34.sep;
   return a.startsWith(p);
 }
 function resolveConsoleUiDist() {
   const fromEnv = process.env.SQUAD_CONSOLE_UI_DIST;
-  if (fromEnv && fs36.existsSync(path30.join(fromEnv, "index.html"))) return fromEnv;
+  if (fromEnv && fs41.existsSync(path34.join(fromEnv, "index.html"))) return fromEnv;
   const candidates = [
     fileURLToPath2(new URL("./console-ui/", import.meta.url)),
     // dist/cli.js → dist/console-ui/
@@ -7075,7 +8246,7 @@ function resolveConsoleUiDist() {
     // src/console/*.ts → project/console-ui/dist
   ];
   for (const c of candidates) {
-    if (fs36.existsSync(path30.join(c, "index.html"))) return c;
+    if (fs41.existsSync(path34.join(c, "index.html"))) return c;
   }
   return null;
 }
@@ -7151,13 +8322,13 @@ async function startConsoleServer(opts) {
     return bindPort;
   })();
   const shutdown = (onClose) => {
-    nodeServer.close((err) => {
-      onClose(err);
+    nodeServer.close((err2) => {
+      onClose(err2);
     });
   };
   const stop = () => {
-    shutdown((err) => {
-      if (err) warning(`server close: ${err.message}`);
+    shutdown((err2) => {
+      if (err2) warning(`server close: ${err2.message}`);
       resolveDone();
     });
   };
@@ -7167,9 +8338,9 @@ async function startConsoleServer(opts) {
     port: actualPort,
     done,
     close: () => new Promise((resolve2, reject) => {
-      shutdown((err) => {
-        if (err) {
-          reject(err);
+      shutdown((err2) => {
+        if (err2) {
+          reject(err2);
           return;
         }
         resolve2();
@@ -7257,18 +8428,18 @@ async function runConsole(opts) {
 }
 
 // src/commands/rm/story.ts
-import fs38 from "fs";
-import path32 from "path";
+import fs43 from "fs";
+import path36 from "path";
 import { confirm as confirm10 } from "@inquirer/prompts";
 
 // src/commands/rm/feature.ts
-import fs37 from "fs";
-import path31 from "path";
+import fs42 from "fs";
+import path35 from "path";
 import { confirm as confirm9 } from "@inquirer/prompts";
 function countStoryDirs(storiesDir, feature) {
-  const d = path31.join(storiesDir, feature);
-  if (!fs37.existsSync(d)) return 0;
-  return fs37.readdirSync(d, { withFileTypes: true }).filter((x) => x.isDirectory()).length;
+  const d = path35.join(storiesDir, feature);
+  if (!fs42.existsSync(d)) return 0;
+  return fs42.readdirSync(d, { withFileTypes: true }).filter((x) => x.isDirectory()).length;
 }
 async function runRmFeature(featureSlug, opts = {}) {
   const root = requireSquadRoot();
@@ -7302,17 +8473,17 @@ async function runRmFeature(featureSlug, opts = {}) {
       feature = await pickFeatureInteractive(paths);
     }
   }
-  const storyDir = path31.join(paths.storiesDir, feature);
-  const planDir = path31.join(paths.plansDir, feature);
+  const storyDir = path35.join(paths.storiesDir, feature);
+  const planDir = path35.join(paths.plansDir, feature);
   const nStories = countStoryDirs(paths.storiesDir, feature);
   const nPlans = listAllPlanListEntries(paths, feature).length;
-  const hasOverview = fs37.existsSync(path31.join(planDir, "00-overview.md")) ? 1 : 0;
+  const hasOverview = fs42.existsSync(path35.join(planDir, "00-overview.md")) ? 1 : 0;
   const targets = [];
-  if (fs37.existsSync(storyDir)) {
-    targets.push({ label: path31.relative(root, storyDir), absPath: storyDir, kind: "dir" });
+  if (fs42.existsSync(storyDir)) {
+    targets.push({ label: path35.relative(root, storyDir), absPath: storyDir, kind: "dir" });
   }
-  if (fs37.existsSync(planDir)) {
-    targets.push({ label: path31.relative(root, planDir), absPath: planDir, kind: "dir" });
+  if (fs42.existsSync(planDir)) {
+    targets.push({ label: path35.relative(root, planDir), absPath: planDir, kind: "dir" });
   }
   divider("squad rm feature");
   info(`Feature:  ${feature}`);
@@ -7327,7 +8498,7 @@ async function runRmFeature(featureSlug, opts = {}) {
     kv(t.kind, t.label, 6);
   }
   if (useTrash) {
-    info(`Items will move to ${path31.relative(process.cwd(), paths.trashDir)}/<timestamp>/`);
+    info(`Items will move to ${path35.relative(process.cwd(), paths.trashDir)}/<timestamp>/`);
   } else if (!dryRun) {
     warning("This is a permanent delete. Pass --trash to move to .squad/.trash/ instead.");
   }
@@ -7360,7 +8531,7 @@ async function runRmFeature(featureSlug, opts = {}) {
     useTrash
   );
   if (result.trashed) {
-    success(`Feature removed. Items moved to ${path31.relative(root, result.trashed)}.`);
+    success(`Feature removed. Items moved to ${path35.relative(root, result.trashed)}.`);
   } else {
     success("Feature removed (stories and plans directories).");
   }
@@ -7401,11 +8572,11 @@ async function runRmStory(storyPathOrId, opts = {}) {
     }
   }
   const targets = [
-    { label: path32.relative(root, story.storyDir), absPath: story.storyDir, kind: "dir" }
+    { label: path36.relative(root, story.storyDir), absPath: story.storyDir, kind: "dir" }
   ];
   if (story.planFile) {
-    const planAbs = path32.join(paths.plansDir, story.feature, story.planFile);
-    targets.push({ label: path32.relative(root, planAbs), absPath: planAbs, kind: "file" });
+    const planAbs = path36.join(paths.plansDir, story.feature, story.planFile);
+    targets.push({ label: path36.relative(root, planAbs), absPath: planAbs, kind: "file" });
   }
   renderPreview("story", targets, {
     dryRun,
@@ -7430,14 +8601,14 @@ async function runRmStory(storyPathOrId, opts = {}) {
   }
   const result = deleteStoryRecord({ paths, story, trash: useTrash });
   if (result.trashed) {
-    success(`Removed (moved to ${path32.relative(root, result.trashed)}).`);
+    success(`Removed (moved to ${path36.relative(root, result.trashed)}).`);
   } else {
     success("Removed story folder, plan file (if any), and overview row.");
   }
-  const featurePlanDir = path32.join(paths.plansDir, story.feature);
-  const overviewPath = path32.join(featurePlanDir, "00-overview.md");
-  if (fs38.existsSync(overviewPath)) {
-    const body = fs38.readFileSync(overviewPath, "utf8");
+  const featurePlanDir = path36.join(paths.plansDir, story.feature);
+  const overviewPath = path36.join(featurePlanDir, "00-overview.md");
+  if (fs43.existsSync(overviewPath)) {
+    const body = fs43.readFileSync(overviewPath, "utf8");
     const onlyShell = countOverviewDataRows(body) === 0;
     if (onlyShell && featureStoriesDirEmpty(paths, story.feature)) {
       if (canPrompt) {
@@ -7457,7 +8628,7 @@ async function runRmStory(storyPathOrId, opts = {}) {
 }
 
 // src/commands/rm/plan.ts
-import path33 from "path";
+import path37 from "path";
 import { confirm as confirm11 } from "@inquirer/prompts";
 async function runRmPlan(planPathOrSequence, opts = {}) {
   const root = requireSquadRoot();
@@ -7493,7 +8664,7 @@ async function runRmPlan(planPathOrSequence, opts = {}) {
   }
   const storyRows = listStories(paths, { feature: plan.feature });
   const linked = storyRows.find((s) => s.planFile === plan.file);
-  const targets = [{ label: path33.relative(root, plan.abs), absPath: plan.abs, kind: "file" }];
+  const targets = [{ label: path37.relative(root, plan.abs), absPath: plan.abs, kind: "file" }];
   renderPreview("plan", targets, {
     dryRun,
     trash: useTrash,
@@ -7516,8 +8687,8 @@ async function runRmPlan(planPathOrSequence, opts = {}) {
     }
   }
   trashOrDelete([plan.abs], paths.trashDir, useTrash);
-  removeOverviewRowForPlanFile(path33.join(paths.plansDir, plan.feature), plan.file);
-  const intakeHint = linked ? path33.relative(root, linked.intakePath) : `under .squad/stories/${plan.feature}/`;
+  removeOverviewRowForPlanFile(path37.join(paths.plansDir, plan.feature), plan.file);
+  const intakeHint = linked ? path37.relative(root, linked.intakePath) : `under .squad/stories/${plan.feature}/`;
   success(`Plan removed. Run \`squad new-plan ${intakeHint}\` to regenerate.`);
 }
 
@@ -7551,7 +8722,11 @@ program.command("new-story [feature-slug]").description("Scaffold a new story in
   "--no-tracker",
   "Skip tracker fetch AND drop the tracker-id requirement for this story"
 ).action(wrapArgs(runNewStory));
-program.command("new-plan [intake-path]").description("Generate a plan (via direct API when configured, otherwise copy-paste)").option("--no-clipboard", "Do not copy the composed prompt to clipboard (copy-paste mode only)").option("--feature <slug>", "Filter picker by feature slug").option("--all", "Include already-planned intakes in the picker", false).option("-y, --yes", "Skip confirmation prompts", false).option("--api", "Force direct planner API (fails if not configured)", false).option("--copy", "Force copy-paste mode even when planner API is configured", false).action(wrapArgs(runNewPlan));
+program.command("new-plan [intake-path]").description("Generate a plan (via direct API when configured, otherwise copy-paste)").option("--no-clipboard", "Do not copy the composed prompt to clipboard (copy-paste mode only)").option("--feature <slug>", "Filter picker by feature slug").option("--all", "Include already-planned intakes in the picker", false).option("-y, --yes", "Skip confirmation prompts", false).option("--api", "Force direct planner API (fails if not configured)", false).option("--copy", "Force copy-paste mode even when planner API is configured", false).option("--no-scout", "Disable the scout stage (draft only)", false).option("--scout-model <id>", "Override scout model id (cheap tier default from PLANNER_MODEL_MAP)").option(
+  "--max-scout-files <n>",
+  "Maximum files the scout can pre-select (default from config or 12)",
+  (v) => parseInt(v, 10)
+).option("--no-validation", "Disable post-write validation", false).option("--strict-validation", "Write partial plan when validation finds issues", false).action(wrapArgs(runNewPlan));
 program.command("status").description("Show squad-kit workspace status").action(wrap(runStatus));
 program.command("doctor").description("Run a health check on the local .squad/ workspace and its external integrations").option("--fix", "Apply non-destructive repairs (gitignore, permissions, missing dirs)", false).option("--json", "Emit results as JSON to stdout (for scripting)", false).action(wrap(runDoctor));
 program.command("migrate").description("Apply one-shot structural migrations to bring .squad/ to the latest version").option("--dry-run", "Show what would change without touching the filesystem", false).option("-y, --yes", "Skip the confirmation prompt", false).action(wrap(runMigrate));
@@ -7581,24 +8756,24 @@ config.command("remove-credential <section>").description('Delete credentials fo
     (section, opts) => runConfigRemoveCredential(section, { yes: opts.yes })
   )
 );
-program.parseAsync(process.argv).catch((err) => {
-  if (isSquadExit(err)) {
-    if (err.message.trim()) info(err.message);
-    process.exit(err.exitCode);
+program.parseAsync(process.argv).catch((err2) => {
+  if (isSquadExit(err2)) {
+    if (err2.message.trim()) info(err2.message);
+    process.exit(err2.exitCode);
   }
-  renderError(err);
+  renderError(err2);
   process.exit(1);
 });
 function wrap(fn) {
   return async (opts) => {
     try {
       await fn(opts);
-    } catch (err) {
-      if (isSquadExit(err)) {
-        if (err.message.trim()) info(err.message);
-        process.exit(err.exitCode);
+    } catch (err2) {
+      if (isSquadExit(err2)) {
+        if (err2.message.trim()) info(err2.message);
+        process.exit(err2.exitCode);
       }
-      renderError(err);
+      renderError(err2);
       process.exit(1);
     }
   };
@@ -7607,12 +8782,12 @@ function wrapArgs(fn) {
   return async (...args) => {
     try {
       await fn(...args);
-    } catch (err) {
-      if (isSquadExit(err)) {
-        if (err.message.trim()) info(err.message);
-        process.exit(err.exitCode);
+    } catch (err2) {
+      if (isSquadExit(err2)) {
+        if (err2.message.trim()) info(err2.message);
+        process.exit(err2.exitCode);
       }
-      renderError(err);
+      renderError(err2);
       process.exit(1);
     }
   };