squad-kit 0.2.2 → 0.4.0

package/dist/cli.js

@@ -169,10 +169,23 @@ function renderError(err) {
 `);
 }
 
+// src/core/cli-exit.ts
+var SquadExit = class extends Error {
+  constructor(exitCode, message) {
+    super(message ?? "");
+    this.exitCode = exitCode;
+  }
+  exitCode;
+  name = "SquadExit";
+};
+function isSquadExit(err) {
+  return err instanceof SquadExit;
+}
+
 // src/commands/init.ts
 import fs14 from "fs";
 import path6 from "path";
-import { input as input3, select as select3, checkbox, confirm as confirm5, password as password3 } from "@inquirer/prompts";
+import { input as input2, select as select3, checkbox, confirm as confirm5, password as password3 } from "@inquirer/prompts";
 
 // src/core/paths.ts
 import path from "path";
@@ -212,8 +225,8 @@ function requireSquadRoot(startDir = process.cwd()) {
   }
   return root;
 }
-function slugify(input6) {
-  return input6.toLowerCase().trim().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+function slugify(input5) {
+  return input5.toLowerCase().trim().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "").slice(0, 80);
 }
 
 // src/core/gitignore.ts
@@ -222,42 +235,38 @@ import path2 from "path";
 var SQUAD_SECRETS_PATTERN = ".squad/secrets.yaml";
 var SQUAD_ATTACHMENTS_PATTERN = ".squad/stories/**/attachments/";
 var SQUAD_TRASH_PATTERN = ".squad/.trash/";
+var SQUAD_LAST_RUN_PATTERN = ".squad/.last-run.json";
+var SQUAD_LAST_COPY_PROMPT_PATTERN = ".squad/.last-copy-prompt.md";
 var MANAGED_BLOCK_HEADER = "# Managed by squad-kit \u2014 do not edit this block";
 var MANAGED_BLOCK_FOOTER = "# End squad-kit block";
 function ensureGitignore(repoRoot) {
   const file = path2.join(repoRoot, ".gitignore");
   const text = fs2.existsSync(file) ? fs2.readFileSync(file, "utf8") : "";
-  if (text.includes(SQUAD_SECRETS_PATTERN) && text.includes(SQUAD_TRASH_PATTERN)) {
-    return false;
-  }
-  if (text.includes(SQUAD_SECRETS_PATTERN) && !text.includes(SQUAD_TRASH_PATTERN)) {
-    let next = text;
-    if (next.includes(SQUAD_ATTACHMENTS_PATTERN + "\n")) {
-      next = next.replace(
-        SQUAD_ATTACHMENTS_PATTERN + "\n",
-        SQUAD_ATTACHMENTS_PATTERN + "\n" + SQUAD_TRASH_PATTERN + "\n"
-      );
-    } else if (next.includes(MANAGED_BLOCK_FOOTER)) {
-      next = next.replace(MANAGED_BLOCK_FOOTER, SQUAD_TRASH_PATTERN + "\n" + MANAGED_BLOCK_FOOTER);
+  const requiredPatterns = [
+    SQUAD_SECRETS_PATTERN,
+    SQUAD_ATTACHMENTS_PATTERN,
+    SQUAD_TRASH_PATTERN,
+    SQUAD_LAST_RUN_PATTERN,
+    SQUAD_LAST_COPY_PROMPT_PATTERN
+  ];
+  const allPresent = requiredPatterns.every((p) => text.includes(p));
+  if (allPresent) return false;
+  if (!text.includes(SQUAD_SECRETS_PATTERN)) {
+    const block = ["", MANAGED_BLOCK_HEADER, ...requiredPatterns, MANAGED_BLOCK_FOOTER, ""].join("\n");
+    const next2 = text.length === 0 ? block.trimStart() : text.endsWith("\n") ? text + block : text + "\n" + block;
+    fs2.writeFileSync(file, next2, "utf8");
+    return true;
+  }
+  let next = text;
+  for (const pattern of requiredPatterns) {
+    if (next.includes(pattern)) continue;
+    if (next.includes(MANAGED_BLOCK_FOOTER)) {
+      next = next.replace(MANAGED_BLOCK_FOOTER, pattern + "\n" + MANAGED_BLOCK_FOOTER);
     } else {
-      next = next.replace(/\n?$/, (m) => m + SQUAD_TRASH_PATTERN + "\n");
-    }
-    if (next !== text) {
-      fs2.writeFileSync(file, next, "utf8");
-      return true;
+      next = next.replace(/\n?$/, (m) => m + pattern + "\n");
     }
   }
-  if (!text.includes(SQUAD_SECRETS_PATTERN)) {
-    const block = [
-      "",
-      MANAGED_BLOCK_HEADER,
-      SQUAD_SECRETS_PATTERN,
-      SQUAD_ATTACHMENTS_PATTERN,
-      SQUAD_TRASH_PATTERN,
-      MANAGED_BLOCK_FOOTER,
-      ""
-    ].join("\n");
-    const next = text.length === 0 ? block.trimStart() : text.endsWith("\n") ? text + block : text + "\n" + block;
+  if (next !== text) {
     fs2.writeFileSync(file, next, "utf8");
     return true;
   }
@@ -280,15 +289,27 @@ var DEFAULT_CONFIG = {
   planner: void 0
 };
 var FORBIDDEN_KEYS = ["apikey", "api_key", "token", "secret", "credential", "credentials"];
-function rejectSecretsInYaml(node, configFile, path25 = []) {
+var DEFAULT_PLANNER_MAX_OUTPUT_TOKENS = 16384;
+var MIN_PLANNER_MAX_OUTPUT_TOKENS = 1024;
+var MAX_PLANNER_MAX_OUTPUT_TOKENS = 128e3;
+function clampPlannerMaxOut(raw) {
+  if (raw === void 0 || raw === null) return DEFAULT_PLANNER_MAX_OUTPUT_TOKENS;
+  const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number.parseInt(raw, 10) : NaN;
+  if (!Number.isFinite(n) || n < 1) return DEFAULT_PLANNER_MAX_OUTPUT_TOKENS;
+  return Math.min(
+    MAX_PLANNER_MAX_OUTPUT_TOKENS,
+    Math.max(MIN_PLANNER_MAX_OUTPUT_TOKENS, Math.round(n))
+  );
+}
+function rejectSecretsInYaml(node, configFile, path26 = []) {
   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 "${[...path25, 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 "${[...path26, 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, [...path25, key]);
+    if (typeof value === "object") rejectSecretsInYaml(value, configFile, [...path26, key]);
   }
 }
 function mergePlanner(base, override) {
@@ -306,7 +327,11 @@ function mergePlanner(base, override) {
     modelOverride: {
       ...base?.modelOverride ?? {},
       ...override.modelOverride ?? {}
-    }
+    },
+    cache: {
+      enabled: override.cache?.enabled ?? base?.cache?.enabled ?? true
+    },
+    maxOutputTokens: clampPlannerMaxOut(override.maxOutputTokens ?? base?.maxOutputTokens)
   };
   if (merged.modelOverride) {
     const pruned = Object.fromEntries(
@@ -350,6 +375,20 @@ function loadConfig(configFile) {
   rejectSecretsInYaml(parsed, configFile);
   const merged = mergeConfig(DEFAULT_CONFIG, parsed);
   validateModelOverride(merged.planner?.modelOverride, configFile);
+  if (merged.planner?.cache !== void 0) {
+    const c = merged.planner.cache;
+    if (typeof c !== "object" || c === null || Array.isArray(c)) {
+      throw new Error(
+        `planner.cache in ${configFile} must be an object with \`enabled: true\` or \`false\`. Run \`squad config set planner\` to set prompt caching.`
+      );
+    }
+    const ce = c.enabled;
+    if (typeof ce !== "boolean") {
+      throw new Error(
+        `planner.cache.enabled in ${configFile} must be a boolean (not a quoted string). Run \`squad config set planner\` to set prompt caching, or use \`true\` or \`false\` unquoted in YAML.`
+      );
+    }
+  }
   if (merged.planner?.enabled) {
     if (!["anthropic", "openai", "google"].includes(merged.planner.provider)) {
       throw new Error(
@@ -571,6 +610,9 @@ function render(template, vars) {
     return value === void 0 || value === null ? "" : String(value);
   });
 }
+function escapeTemplateValue(s) {
+  return s.replace(/\{\{/g, "{ {");
+}
 
 // src/commands/config/show.ts
 import fs7 from "fs";
@@ -696,7 +738,7 @@ async function runConfigShow(opts) {
 
 // src/commands/config/set-planner.ts
 import fs9 from "fs";
-import { confirm as confirm2, input as input2, password as password2, select } from "@inquirer/prompts";
+import { confirm as confirm2, password as password2, select } from "@inquirer/prompts";
 
 // src/tracker/env-overlay.ts
 function overlayTrackerEnv(base) {
@@ -842,7 +884,9 @@ function newPlannerBlock(provider) {
       maxFileReads: 25,
       maxContextBytes: 5e4,
       maxDurationSeconds: 180
-    }
+    },
+    cache: { enabled: true },
+    maxOutputTokens: DEFAULT_PLANNER_MAX_OUTPUT_TOKENS
   };
 }
 function mergePlannerKeyIntoSecrets(base, provider, key) {
@@ -993,22 +1037,11 @@ async function runConfigSetPlanner(opts = {}) {
       success("Planner key saved to .squad/secrets.yaml");
       info(".squad/secrets.yaml updated (chmod 0600 on POSIX)");
     }
-    const wantOverride = await confirm2({
-      message: "Set a custom plan-phase model id (planner.modelOverride)?",
-      default: false
+    const cacheEnabled = await confirm2({
+      message: "Enable prompt caching? (Recommended \u2014 reduces billed tokens by ~70% on most providers.)",
+      default: nextPlanner.cache?.enabled ?? true
     });
-    if (wantOverride) {
-      const modelId = await input2({
-        message: "Plan model id (leave empty to use the default for this provider):",
-        default: ""
-      });
-      if (modelId.trim().length > 0 && nextPlanner) {
-        nextPlanner = {
-          ...nextPlanner,
-          modelOverride: { ...nextPlanner.modelOverride ?? {}, [provider]: modelId.trim() }
-        };
-      }
-    }
+    nextPlanner = { ...nextPlanner, cache: { enabled: cacheEnabled } };
   }
   const next = { ...config2, planner: nextPlanner };
   saveConfig(paths.configFile, next);
@@ -1029,6 +1062,7 @@ async function runConfigSetPlanner(opts = {}) {
     kv("credential", `${cred.source} (${sourceText})`, 10);
   }
   if (process.env.CI === "true" || !cred) {
+    printPlannerNextSteps(Boolean(cred));
     return;
   }
   const listed = await fetchProviderModelIds(provider, cred.value);
@@ -1042,6 +1076,23 @@ async function runConfigSetPlanner(opts = {}) {
   } else {
     info("Credential check: models API responded OK for this key.");
   }
+  printPlannerNextSteps(true);
+}
+function printPlannerNextSteps(credentialReady) {
+  blank();
+  step("Next:");
+  if (!credentialReady) {
+    info("1) Save a planner key: re-run `squad config set planner` and paste the key when prompted.");
+    info("2) Verify with `squad doctor` \u2014 all planner checks should turn green.");
+    info("3) Then run `squad new-story <slug>` and `squad new-plan --api` to generate your first plan.");
+    return;
+  }
+  info("1) Verify with `squad doctor` \u2014 every planner check should be green.");
+  info("2) Create a story:  squad new-story <feature-slug>  (or --no-tracker for a manual story).");
+  info("3) Fill the generated intake.md, then run `squad new-plan --api` to generate the plan.");
+  info(
+    "4) To change provider, key, or disable caching later: re-run `squad config set planner`. Model overrides are edited directly in .squad/config.yaml (planner.modelOverride)."
+  );
 }
 
 // src/commands/config/set-tracker.ts
@@ -1196,6 +1247,7 @@ var AzureDevOpsClient = class {
       id: String(body.id ?? id),
       title: fields["System.Title"] ?? "(no title)",
       description: stripHtml(fields["System.Description"] ?? ""),
+      acceptanceCriteria: stripHtml(fields["Microsoft.VSTS.Common.AcceptanceCriteria"] ?? ""),
       url: `${this.webBase}/${body.id ?? id}`,
       labels: parseTags(fields["System.Tags"]),
       type: fields["System.WorkItemType"],
@@ -1319,6 +1371,7 @@ var JiraClient = class {
       id: body.key ?? id,
       title: fields.summary ?? "(no title)",
       description,
+      acceptanceCriteria: "",
       url: `${this.baseUrl}/browse/${body.key ?? id}`,
       labels: Array.isArray(fields.labels) ? fields.labels : [],
       type: fields.issuetype?.name,
@@ -1526,6 +1579,7 @@ async function runConfigSetTracker(opts = {}) {
     kv("project", next.tracker.project, 10);
   }
   if (process.env.CI === "true") {
+    printTrackerNextSteps(next.tracker.type);
     return;
   }
   const reloaded = loadConfig(paths.configFile);
@@ -1549,6 +1603,20 @@ async function runConfigSetTracker(opts = {}) {
       );
     }
   }
+  printTrackerNextSteps(next.tracker.type);
+}
+function printTrackerNextSteps(type) {
+  blank();
+  step("Next:");
+  if (type === "none") {
+    info("1) Tracker is off. Create stories manually with `squad new-story <slug> --no-tracker`.");
+    info("2) Re-enable any time with `squad config set tracker`.");
+    return;
+  }
+  info("1) Verify with `squad doctor` \u2014 tracker checks should be green.");
+  info(`2) Create a story: squad new-story <feature-slug> --id <${type === "jira" ? "JIRA-123" : "azure-work-item-id"}>`);
+  info("   squad-kit auto-fetches the title, description, and attachments into the intake.");
+  info("3) Review the generated intake.md, then run `squad new-plan --api` to generate the plan.");
 }
 
 // src/commands/config/unset-tracker.ts
@@ -1671,8 +1739,8 @@ async function runInit(opts) {
     agents: parseAgentsFlag(opts.agents)
   };
   const answers = opts.yes ? defaults : {
-    name: await input3({ message: "Project name", default: defaults.name }),
-    language: await input3({ message: "Primary language", default: defaults.language }),
+    name: await input2({ message: "Project name", default: defaults.name }),
+    language: await input2({ message: "Primary language", default: defaults.language }),
     tracker: await select3({
       message: "Issue tracker",
       choices: [
@@ -1736,7 +1804,9 @@ async function runInit(opts) {
           maxFileReads: 25,
           maxContextBytes: 5e4,
           maxDurationSeconds: 180
-        }
+        },
+        cache: { enabled: true },
+        maxOutputTokens: DEFAULT_PLANNER_MAX_OUTPUT_TOKENS
       };
     }
   } else {
@@ -1762,7 +1832,9 @@ async function runInit(opts) {
           maxFileReads: 25,
           maxContextBytes: 5e4,
           maxDurationSeconds: 180
-        }
+        },
+        cache: { enabled: true },
+        maxOutputTokens: DEFAULT_PLANNER_MAX_OUTPUT_TOKENS
       };
     }
   }
@@ -1893,7 +1965,7 @@ Plan meta-prompts (\`generate-plan.md\`, \`story-skeleton.md\`) ship inside the
 // src/commands/new-story.ts
 import fs16 from "fs";
 import path8 from "path";
-import { input as input4, select as select4 } from "@inquirer/prompts";
+import { input as input3, select as select4 } from "@inquirer/prompts";
 
 // src/core/stories.ts
 import fs15 from "fs";
@@ -1933,11 +2005,14 @@ function listStories(paths, opts = {}) {
 function findPlanFor(plansDir, feature, storyId) {
   const featureDir = path7.join(plansDir, feature);
   if (!fs15.existsSync(featureDir)) return void 0;
+  const candidates = [];
   for (const entry of fs15.readdirSync(featureDir)) {
     if (!STORY_FILE.test(entry)) continue;
-    if (entry.includes(storyId)) return entry;
+    if (entry.includes(storyId)) candidates.push(entry);
   }
-  return void 0;
+  if (candidates.length === 0) return void 0;
+  const complete = candidates.find((e) => !e.endsWith(".partial.md"));
+  return complete ?? candidates[0];
 }
 function findStoryByIntake(records, intakePath) {
   const target = normalizeIntakePath(intakePath.trim());
@@ -1953,21 +2028,53 @@ function normalizeIntakePath(p) {
 }
 function readTitleHint(intakePath) {
   try {
-    const head = fs15.readFileSync(intakePath, "utf8").split("\n").slice(0, 3).join("\n");
-    const m = head.match(/>\s*\*\*Title hint \(from CLI\):\*\*\s*(.+?)\s*$/m);
-    return m?.[1]?.trim() || void 0;
+    const raw = fs15.readFileSync(intakePath, "utf8");
+    const head = raw.split("\n").slice(0, 30).join("\n");
+    const hintLine = head.match(/>\s*\*\*Title hint \(from CLI\):\*\*\s*(.+?)\s*$/m);
+    const fromHint = hintLine?.[1]?.trim();
+    if (fromHint) return fromHint;
+    const titleFence = raw.match(/(?:^|\n)## Title\b[\s\S]*?\n```(?:[\w-]*)?\s*\n([\s\S]*?)\n```/);
+    const fromFence = titleFence?.[1]?.trim();
+    if (fromFence) return fromFence;
+    return void 0;
   } catch {
     return void 0;
   }
 }
-function readPlanMetadata(planFileAbsPath) {
-  try {
-    const first = fs15.readFileSync(planFileAbsPath, "utf8").split("\n", 1)[0] ?? "";
-    const m = first.match(/^<!--\s*squad-kit:\s*generated by\s+([^\s,]+)/);
-    if (!m) return {};
-    const generatedBy = m[1];
+var PLAN_GENERATED_BY = /^<!--\s*squad-kit:\s*generated by\s+([^\s,]+)/;
+var PLAN_ANY_SQUAD = /^<!--\s*squad-kit:\s*(.+?)\s*-->$/;
+var MAX_FREEFORM_META_LEN = 96;
+function parsePlanMetadataLine(line2) {
+  const strict = line2.match(PLAN_GENERATED_BY);
+  if (strict) {
+    const generatedBy = strict[1];
+    const [provider, model] = generatedBy.split("/");
+    return { provider, model, generatedBy };
+  }
+  const any = line2.match(PLAN_ANY_SQUAD);
+  if (!any) return null;
+  const inner = any[1].trim();
+  const flex = inner.match(/^generated\s+by\s+([^\s,]+)/i);
+  if (flex) {
+    const generatedBy = flex[1];
     const [provider, model] = generatedBy.split("/");
     return { provider, model, generatedBy };
+  }
+  const short = inner.length > MAX_FREEFORM_META_LEN ? `${inner.slice(0, MAX_FREEFORM_META_LEN - 1)}\u2026` : inner;
+  return { generatedBy: short };
+}
+function readPlanMetadata(planFileAbsPath) {
+  try {
+    const raw = fs15.readFileSync(planFileAbsPath, "utf8").replace(/^\uFEFF/, "");
+    const lines = raw.split(/\n/);
+    const scan = Math.min(lines.length, 40);
+    for (let i = 0; i < scan; i++) {
+      const line2 = (lines[i] ?? "").replace(/\r$/, "").trim();
+      if (!line2) continue;
+      const parsed = parsePlanMetadataLine(line2);
+      if (parsed) return parsed;
+    }
+    return {};
   } catch {
     return {};
   }
@@ -2024,7 +2131,7 @@ async function runNewStory(featureSlug, opts) {
       }
     }
     if (!featureSlugInput) {
-      featureSlugInput = (await input4({
+      featureSlugInput = (await input3({
         message: "New feature slug (kebab-case):",
         validate: validateFeatureSlugForPrompt
       })).trim();
@@ -2063,7 +2170,7 @@ async function runNewStory(featureSlug, opts) {
       noTracker = true;
       trackerNeedsId = false;
     } else {
-      id = (await input4({
+      id = (await input3({
         message: `${config2.tracker.type} work-item id:`,
         validate: (v) => validateTrackerId(config2.tracker.type, v.trim()) ? true : `Invalid ${config2.tracker.type} id format.`
       })).trim();
@@ -2082,12 +2189,12 @@ async function runNewStory(featureSlug, opts) {
         );
       }
     } else {
-      title = (await input4({ message: "Short story title:" })).trim();
+      title = (await input3({ message: "Short story title:" })).trim();
       if (!title) throw new Error("Title cannot be empty. Run `squad new-story` again and enter a short title, or add `--yes` to fail fast in scripts.");
     }
   }
   if (interactive && !title) {
-    const maybe = (await input4({ message: "Short title (optional, press Enter to skip):", default: "" })).trim();
+    const maybe = (await input3({ message: "Short title (optional, press Enter to skip):", default: "" })).trim();
     if (maybe) title = maybe;
   }
   const storyFolderName = id ? trackerIdForFilename(config2.tracker.type, id) : slugify(title ?? "");
@@ -2107,10 +2214,12 @@ async function runNewStory(featureSlug, opts) {
   fs16.mkdirSync(attachmentsDir, { recursive: true });
   let sourceBlock = "";
   let fetchedSummary;
+  let fetchedIssue;
   const shouldFetch = !noTracker && opts.fetch !== false && Boolean(id) && config2.tracker.type !== "none";
   if (shouldFetch) {
     const outcome = await tryFetchIssue(config2, id, opts, paths, attachmentsDir);
     if (outcome.outcome === "ok") {
+      fetchedIssue = outcome.issue;
       sourceBlock = buildSourcePreamble(outcome.issue, outcome.downloads, config2.tracker.type);
       if (!title) title = outcome.issue.title;
       const written = outcome.downloads.filter((d) => d.outcome === "written").length;
@@ -2122,18 +2231,19 @@ async function runNewStory(featureSlug, opts) {
     }
   }
   const template = readBundledPrompt("intake.md");
-  const rendered = render(template, {
-    featureSlug: slug,
-    storyId: storyFolderName,
-    trackerType: config2.tracker.type,
-    projectRoots: (config2.project.projectRoots ?? ["."]).join(", "),
-    primaryLanguage: config2.project.primaryLanguage ?? ""
-  });
+  const rendered = render(
+    template,
+    buildIntakeTemplateVars({
+      config: config2,
+      featureSlug: slug,
+      storyFolderName,
+      trackerId: id,
+      title,
+      fetchedIssue
+    })
+  );
   const skippedPreamble = noTracker && config2.tracker.type !== "none" && !sourceBlock ? buildSkippedTrackerPreamble(config2.tracker.type) : "";
-  const titleHint = title ? `> **Title hint (from CLI):** ${title}
-
-` : "";
-  writeFileSafe(intakeFile, skippedPreamble + sourceBlock + titleHint + rendered, false);
+  writeFileSafe(intakeFile, skippedPreamble + sourceBlock + rendered, false);
   ensureFeatureOverview(path8.join(paths.plansDir, slug), slug);
   const relativePath = path8.relative(root, intakeFile);
   const relAttachDir = path8.relative(root, attachmentsDir);
@@ -2206,6 +2316,25 @@ function explainTrackerErrorHint(err) {
 function truncate(s, n) {
   return s.length <= n ? s : s.slice(0, n - 1) + "\u2026";
 }
+function buildIntakeTemplateVars(args) {
+  const e = escapeTemplateValue;
+  const { config: config2, featureSlug, storyFolderName, trackerId, title, fetchedIssue } = args;
+  return {
+    featureSlug,
+    storyId: storyFolderName,
+    trackerType: config2.tracker.type,
+    trackerWorkItemId: e((fetchedIssue?.id ?? trackerId ?? "").trim()),
+    trackerWorkItemType: e((fetchedIssue?.type ?? "").trim()),
+    trackerStatus: e((fetchedIssue?.status ?? "").trim()),
+    trackerAssignee: e((fetchedIssue?.assignee ?? "").trim()),
+    trackerLabels: e((fetchedIssue?.labels ?? []).join(", ").trim()),
+    trackerTitle: e((title ?? "").trim()),
+    trackerDescription: e((fetchedIssue?.description ?? "").trim()),
+    trackerAcceptanceCriteria: e((fetchedIssue?.acceptanceCriteria ?? "").trim()),
+    projectRoots: (config2.project.projectRoots ?? ["."]).join(", "),
+    primaryLanguage: config2.project.primaryLanguage ?? ""
+  };
+}
 function buildSourcePreamble(issue, downloads, trackerType) {
   const header = `> **Fetched from ${trackerType}:** [${issue.id}](${issue.url})  
 > *Fetched ${issue.fetchedAt}. Edit the sections below as needed; the planner reads this file verbatim.*
@@ -2279,29 +2408,96 @@ function ensureFeatureOverview(featurePlanDir, slug) {
 }
 
 // src/commands/new-plan.ts
-import fs21 from "fs";
-import path14 from "path";
+import fs22 from "fs";
+import path15 from "path";
 import { confirm as confirm6, select as select5 } from "@inquirer/prompts";
 
 // src/utils/clipboard.ts
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 async function copyToClipboard(text) {
-  const cmd = clipboardCommand();
-  if (!cmd) return false;
+  const candidates = clipboardCandidates();
+  if (candidates.length === 0) {
+    return { ok: false, reason: noCandidateReason() };
+  }
+  let lastReason;
+  for (const cmd of candidates) {
+    const reason = cmd.unavailableReason?.();
+    if (reason) {
+      lastReason = reason;
+      continue;
+    }
+    const res = await tryCopy(cmd, text);
+    if (res.ok) return res;
+    lastReason = res.reason;
+  }
+  return { ok: false, reason: lastReason ?? "no working clipboard tool found" };
+}
+function tryCopy(cmd, text) {
   return new Promise((resolve) => {
-    const child = spawn(cmd.command, cmd.args, { stdio: ["pipe", "ignore", "ignore"] });
-    child.on("error", () => resolve(false));
-    child.on("close", (code) => resolve(code === 0));
-    child.stdin.write(text);
-    child.stdin.end();
+    let child;
+    try {
+      child = spawn(cmd.command, cmd.args, { stdio: ["pipe", "ignore", "pipe"] });
+    } catch (err) {
+      resolve({ ok: false, reason: `${cmd.command} failed to spawn: ${err.message}` });
+      return;
+    }
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (err) => {
+      resolve({ ok: false, reason: `${cmd.command} spawn error: ${err.message}` });
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ ok: true, tool: cmd.command });
+      } else {
+        resolve({
+          ok: false,
+          reason: `${cmd.command} exited with code ${code}${stderr ? `: ${stderr.trim().slice(0, 200)}` : ""}`
+        });
+      }
+    });
+    child.stdin?.write(text);
+    child.stdin?.end();
   });
 }
-function clipboardCommand() {
-  if (process.platform === "darwin") return { command: "pbcopy", args: [] };
-  if (process.platform === "win32") return { command: "clip", args: [] };
-  if (process.env.WAYLAND_DISPLAY) return { command: "wl-copy", args: [] };
-  if (process.env.DISPLAY) return { command: "xclip", args: ["-selection", "clipboard"] };
-  return null;
+function clipboardCandidates() {
+  if (process.platform === "darwin") {
+    return [{ command: "pbcopy", args: [] }];
+  }
+  if (process.platform === "win32") {
+    return [{ command: "clip", args: [] }];
+  }
+  const out = [];
+  if (process.env.WAYLAND_DISPLAY) {
+    out.push({ command: "wl-copy", args: [], unavailableReason: hasBinary("wl-copy") });
+  }
+  if (process.env.DISPLAY) {
+    out.push({ command: "xclip", args: ["-selection", "clipboard"], unavailableReason: hasBinary("xclip") });
+    out.push({ command: "xsel", args: ["--clipboard", "--input"], unavailableReason: hasBinary("xsel") });
+  }
+  if (process.env.TERMUX_VERSION) {
+    out.push({ command: "termux-clipboard-set", args: [], unavailableReason: hasBinary("termux-clipboard-set") });
+  }
+  return out;
+}
+function hasBinary(bin) {
+  return () => {
+    const which = process.platform === "win32" ? "where" : "which";
+    const res = spawnSync(which, [bin], { stdio: "ignore" });
+    if (res.status === 0) return void 0;
+    return `${bin} not found on PATH`;
+  };
+}
+function noCandidateReason() {
+  if (process.platform === "linux") {
+    if (!process.env.DISPLAY && !process.env.WAYLAND_DISPLAY && !process.env.TERMUX_VERSION) {
+      return "no display server detected (headless / SSH) \u2014 install xclip or xsel, or use the saved file";
+    }
+    return "no clipboard tool detected \u2014 install xclip, xsel, or wl-copy";
+  }
+  return `no clipboard tool detected on ${process.platform}`;
 }
 
 // src/planner/loop.ts
@@ -2323,8 +2519,8 @@ var READ_FILE_TOOL = {
   }
 };
 var MAX_BYTES_PER_READ = 32e3;
-function readFileTool(root, budget, input6) {
-  const raw = input6?.path;
+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.');
   }
@@ -2455,117 +2651,16 @@ function rateLimitMessage(err) {
   ].join("\n");
 }
 
-// src/planner/loop.ts
-var MAX_RATE_LIMIT_RETRY_SEC = 90;
-var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-async function runPlanner(input6) {
-  const maxIter = input6.maxIterations ?? 40;
-  const turns = [{ role: "user", text: input6.userPrompt }];
-  let accumulatedText = "";
-  let iterations = 0;
-  let budgetExhausted = false;
-  let finishedNormally = false;
-  while (iterations < maxIter) {
-    iterations += 1;
-    if (input6.budget.timedOut()) {
-      return { planText: accumulatedText, budgetExhausted, timedOut: true, finishedNormally: false, iterations };
-    }
-    if (input6.budget.overCost()) {
-      return { planText: accumulatedText, budgetExhausted: true, timedOut: false, finishedNormally: false, iterations };
-    }
-    const request = {
-      systemPrompt: input6.systemPrompt,
-      model: input6.model,
-      tools: [READ_FILE_TOOL],
-      turns,
-      apiKey: input6.apiKey,
-      maxOutputTokens: 8192
-    };
-    let response = await input6.provider.send(request);
-    if (response.usage) {
-      input6.budget.recordUsage(response.usage);
-      input6.onUsage?.(response.usage);
-    }
-    let retriedRateLimit = false;
-    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);
-        input6.onRateLimit?.(waitSec);
-        await (input6.sleep ?? defaultSleep)(waitSec * 1e3);
-        response = await input6.provider.send(request);
-        if (response.usage) {
-          input6.budget.recordUsage(response.usage);
-          input6.onUsage?.(response.usage);
-        }
-        retriedRateLimit = true;
-      }
-    }
-    if (response.stopReason === "error") {
-      throw composePlannerError(input6.provider.name, response, retriedRateLimit, retrySkippedReason);
-    }
-    if (response.text) {
-      accumulatedText += response.text;
-      input6.onAssistantText?.(response.text);
-    }
-    if (response.stopReason === "max_tokens" && !response.toolCalls?.length) {
-      return { planText: accumulatedText, budgetExhausted, timedOut: false, finishedNormally: false, iterations };
-    }
-    if (response.stopReason === "end_turn" || !response.toolCalls?.length) {
-      finishedNormally = true;
-      return { planText: accumulatedText, budgetExhausted, timedOut: false, finishedNormally, iterations };
-    }
-    turns.push({
-      role: "assistant",
-      text: response.text,
-      toolCalls: response.toolCalls
-    });
-    const toolResults = [];
-    for (const tc of response.toolCalls) {
-      if (tc.name !== READ_FILE_TOOL.name) {
-        toolResults.push({ toolCallId: tc.id, content: `unknown tool "${tc.name}"`, isError: true });
-        continue;
-      }
-      const before = input6.budget.snapshot().bytes;
-      const result = readFileTool(input6.root, input6.budget, tc.input);
-      const after = input6.budget.snapshot().bytes;
-      input6.onToolCall?.(tc, after - before, after);
-      if (result.isError && (/budget/i.test(result.content) || /max file reads/i.test(result.content))) {
-        budgetExhausted = true;
-      }
-      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."
-      });
-    }
-  }
-  return { planText: accumulatedText, budgetExhausted, timedOut: false, finishedNormally: false, iterations };
-}
-function composePlannerError(providerName, response, retriedRateLimit, retrySkippedReason) {
-  if (response.errorKind === "rate_limit") {
-    return new Error(
-      rateLimitMessage({
-        provider: providerName,
-        retryAfterSec: response.retryAfterSec,
-        rawBody: response.rawError ?? "",
-        retryAlreadyAttempted: retriedRateLimit,
-        retrySkippedReason,
-        maxRetrySec: MAX_RATE_LIMIT_RETRY_SEC
-      })
-    );
-  }
-  if (response.errorKind === "model_not_found") {
-    return new Error(response.rawError ?? "planner: model not found");
+// 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]);
   }
-  const base = response.rawError ?? "planner: provider error";
-  return new Error(`${base} Run \`squad doctor\` to diagnose, or retry \u2014 most 5xx errors are transient.`);
+  return out;
 }
 
 // src/planner/providers/anthropic.ts
@@ -2577,14 +2672,39 @@ var anthropicProvider = {
     return callAnthropic(req);
   }
 };
-async function callAnthropic(req) {
-  const body = {
+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: req.systemPrompt,
-    tools: req.tools.map(toAnthropicTool),
-    messages: req.turns.map(toAnthropicMessage)
+    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: {
@@ -2624,26 +2744,73 @@ async function callAnthropic(req) {
     stopReason: mapStop(json.stop_reason),
     usage: {
       inputTokens: json.usage?.input_tokens ?? 0,
-      outputTokens: json.usage?.output_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 };
+}
 function toAnthropicTool(t) {
-  return { name: t.name, description: t.description, input_schema: t.inputSchema };
+  return {
+    name: t.name,
+    description: t.description,
+    input_schema: sortRecordKeys(t.inputSchema)
+  };
 }
 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: tc.input });
-  if (turn.toolResults)
-    for (const tr of turn.toolResults)
+  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 };
 }
 function mapStop(r) {
@@ -2660,15 +2827,23 @@ var openaiProvider = {
     return callOpenAI(req);
   }
 };
-async function callOpenAI(req) {
-  const messages = [{ role: "system", content: req.systemPrompt }];
-  for (const turn of req.turns) messages.push(...toOpenAIMessages(turn));
-  const body = {
+function buildOpenAIBody(req) {
+  const base = {
     model: req.model,
-    messages,
-    tools: req.tools.map(toOpenAITool),
-    max_completion_tokens: req.maxOutputTokens ?? 4096
+    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: {
@@ -2718,7 +2893,14 @@ async function callOpenAI(req) {
   };
 }
 function toOpenAITool(t) {
-  return { type: "function", function: { name: t.name, description: t.description, parameters: t.inputSchema } };
+  return {
+    type: "function",
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: sortRecordKeys(t.inputSchema)
+    }
+  };
 }
 function toOpenAIMessages(turn) {
   const out = [];
@@ -2729,7 +2911,10 @@ function toOpenAIMessages(turn) {
       tool_calls: turn.toolCalls?.map((tc) => ({
         id: tc.id,
         type: "function",
-        function: { name: tc.name, arguments: JSON.stringify(tc.input) }
+        function: {
+          name: tc.name,
+          arguments: JSON.stringify(sortRecordKeys(tc.input))
+        }
       }))
     });
   } else {
@@ -2749,7 +2934,7 @@ function mapStop2(r) {
 }
 function safeJson(raw) {
   try {
-    return JSON.parse(raw);
+    return sortRecordKeys(JSON.parse(raw));
   } catch {
     return {};
   }
@@ -2763,14 +2948,23 @@ var googleProvider = {
     return callGoogle(req);
   }
 };
-async function callGoogle(req) {
-  const url = `${API_BASE}/${encodeURIComponent(req.model)}:generateContent?key=${encodeURIComponent(req.apiKey)}`;
-  const body = {
+function buildGoogleBody(req) {
+  const base = {
     system_instruction: { parts: [{ text: req.systemPrompt }] },
-    contents: req.turns.map(toGoogleContent),
-    tools: req.tools.length ? [{ functionDeclarations: req.tools.map(toGoogleTool) }] : void 0,
     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" },
@@ -2805,7 +2999,7 @@ async function callGoogle(req) {
   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 ?? {}
+    input: p.functionCall.args ? sortRecordKeys(p.functionCall.args) : {}
   }));
   return {
     text: textOut || void 0,
@@ -2818,14 +3012,17 @@ async function callGoogle(req) {
   };
 }
 function toGoogleTool(t) {
-  return { name: t.name, description: t.description, parameters: t.inputSchema };
+  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: tc.input } });
+  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({
@@ -2845,6 +3042,416 @@ function mapStop3(r) {
   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;
+}
+
+// src/planner/session-limits.ts
+var DEFAULT_PLANNER_MAX_ITERATIONS = 40;
+var PLANNER_MARKDOWN_CONTINUATION_USER = "Your previous reply was cut off because it hit the per-response output token limit for this request. Continue the Markdown plan from the exact cut-off only: write the remainder, do not repeat headings or paragraphs already sent. When the plan is complete, use end_turn without unnecessary tool calls.";
+
+// src/planner/loop.ts
+var MAX_RATE_LIMIT_RETRY_SEC = 90;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function buildPlannerRunStats(budget, turns, runStartedAt) {
+  const u = budget.snapshot().usage;
+  const cacheRead = u.cacheReadTokens ?? 0;
+  const cacheCreate = u.cacheCreationTokens ?? 0;
+  const inTok = u.inputTokens;
+  const outTok = u.outputTokens;
+  const totalInput = inTok + cacheRead;
+  const cacheHitRatio = totalInput === 0 ? 0 : Math.round(cacheRead / totalInput * 100) / 100;
+  return {
+    turns,
+    inputTokens: inTok,
+    outputTokens: outTok,
+    cacheCreationTokens: cacheCreate,
+    cacheReadTokens: cacheRead,
+    cacheHitRatio,
+    durationMs: Date.now() - runStartedAt
+  };
+}
+function readBudgetishError(result) {
+  return result.isError && (/budget/i.test(result.content) || /max file reads/i.test(result.content));
+}
+function extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut) {
+  input5.budget.extendSession();
+  maxIter.current += baseMaxIter;
+  maxOut.current += baseMaxOut;
+}
+async function runPlanner(input5) {
+  const runStartedAt = Date.now();
+  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 }];
+  let accumulatedText = "";
+  let iterations = 0;
+  let budgetExhausted = false;
+  let finishedNormally = false;
+  let prevRequestPrefix;
+  const decide = input5.decideOnLimit;
+  const limitCtx = (kind) => ({
+    kind,
+    budgetSnapshot: input5.budget.snapshot(),
+    iterations,
+    maxIterations: maxIter.current,
+    maxOutputTokens: maxOut.current
+  });
+  for (; ; ) {
+    if (iterations >= maxIter.current) {
+      if (decide) {
+        const d = await decide(limitCtx("max_iterations"));
+        if (d === "cancel") {
+          return {
+            planText: accumulatedText,
+            budgetExhausted,
+            timedOut: false,
+            finishedNormally: false,
+            iterations,
+            stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt),
+            incompleteKind: "max_iterations",
+            userCancelled: true
+          };
+        }
+        extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut);
+        continue;
+      }
+      return {
+        planText: accumulatedText,
+        budgetExhausted,
+        timedOut: false,
+        finishedNormally: false,
+        iterations,
+        stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt),
+        incompleteKind: "max_iterations"
+      };
+    }
+    iterations += 1;
+    if (input5.budget.timedOut()) {
+      if (decide) {
+        const d = await decide(limitCtx("wall_clock"));
+        if (d === "cancel") {
+          return {
+            planText: accumulatedText,
+            budgetExhausted,
+            timedOut: true,
+            finishedNormally: false,
+            iterations,
+            stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt),
+            incompleteKind: "wall_clock",
+            userCancelled: true
+          };
+        }
+        extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut);
+        iterations -= 1;
+        continue;
+      }
+      return {
+        planText: accumulatedText,
+        budgetExhausted,
+        timedOut: true,
+        finishedNormally: false,
+        iterations,
+        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)
+      };
+    }
+    const request = {
+      systemPrompt: input5.systemPrompt,
+      model: input5.model,
+      tools: [READ_FILE_TOOL],
+      turns,
+      apiKey: input5.apiKey,
+      maxOutputTokens: maxOut.current,
+      cacheEnabled: input5.cacheEnabled ?? true
+    };
+    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 = await input5.provider.send(request);
+    if (response.usage) {
+      input5.budget.recordUsage(response.usage);
+      input5.onUsage?.(response.usage);
+    }
+    let retriedRateLimit = false;
+    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);
+        await (input5.sleep ?? defaultSleep)(waitSec * 1e3);
+        response = await input5.provider.send(request);
+        if (response.usage) {
+          input5.budget.recordUsage(response.usage);
+          input5.onUsage?.(response.usage);
+        }
+        retriedRateLimit = true;
+      }
+    }
+    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);
+    }
+    if (response.stopReason === "max_tokens" && !response.toolCalls?.length) {
+      if (decide) {
+        const d = await decide(limitCtx("max_output_tokens"));
+        if (d === "cancel") {
+          return {
+            planText: accumulatedText,
+            budgetExhausted,
+            timedOut: false,
+            finishedNormally: false,
+            iterations,
+            stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt),
+            incompleteKind: "max_output_tokens",
+            userCancelled: true
+          };
+        }
+        extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut);
+        turns.push({ role: "assistant", text: response.text ?? "" });
+        turns.push({ role: "user", text: PLANNER_MARKDOWN_CONTINUATION_USER });
+        iterations -= 1;
+        continue;
+      }
+      return {
+        planText: accumulatedText,
+        budgetExhausted,
+        timedOut: false,
+        finishedNormally: false,
+        iterations,
+        stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt),
+        incompleteKind: "max_output_tokens"
+      };
+    }
+    if (response.stopReason === "end_turn" || !response.toolCalls?.length) {
+      finishedNormally = true;
+      return {
+        planText: accumulatedText,
+        budgetExhausted,
+        timedOut: false,
+        finishedNormally,
+        iterations,
+        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;
+      input5.onToolCall?.(tc, after - before, after);
+      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;
+        }
+      }
+      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."
+      });
+    }
+  }
+}
+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;
+  }
+  return n;
+}
+function composePlannerError(providerName, response, retriedRateLimit, retrySkippedReason) {
+  if (response.errorKind === "rate_limit") {
+    return new Error(
+      rateLimitMessage({
+        provider: providerName,
+        retryAfterSec: response.retryAfterSec,
+        rawBody: response.rawError ?? "",
+        retryAlreadyAttempted: retriedRateLimit,
+        retrySkippedReason,
+        maxRetrySec: MAX_RATE_LIMIT_RETRY_SEC
+      })
+    );
+  }
+  if (response.errorKind === "model_not_found") {
+    return new Error(response.rawError ?? "planner: model not found");
+  }
+  const base = response.rawError ?? "planner: provider error";
+  return new Error(`${base} Run \`squad doctor\` to diagnose, or retry \u2014 most 5xx errors are transient.`);
+}
+
+// src/planner/planner-limit-messages.ts
+function printPlannerApiCostNotice() {
+  blank();
+  step("Billing");
+  info(
+    "`squad new-plan --api` sends your intake and repo context to the configured provider. Each model round is billed like any other API usage (input tokens, output tokens, and cache-related tokens when applicable). Choosing \u201CContinue\u201D after a limit runs more rounds and usually increases cost."
+  );
+  blank();
+}
+function kindTitle(kind) {
+  switch (kind) {
+    case "max_output_tokens":
+      return "Output length limit (single response)";
+    case "max_iterations":
+      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) {
+  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.";
+  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
+      ];
+    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
+      ];
+    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
+      ];
+    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
+      ];
+  }
+}
+function printPlannerLimitExplanation(ctx) {
+  warning(kindTitle(ctx.kind));
+  for (const line2 of kindDetail(ctx)) {
+    info(line2);
+  }
+  kv("session so far", `${snapSummary(ctx)}`, 18);
+}
+function snapSummary(ctx) {
+  const s = ctx.budgetSnapshot;
+  return `${s.reads} reads \xB7 ${(s.bytes / 1024).toFixed(1)} KB read context \xB7 ${s.usage.inputTokens} in / ${s.usage.outputTokens} out tokens`;
+}
+function printPlannerLimitNextSteps() {
+  blank();
+  step("If you stop here");
+  info("An incomplete plan is saved as `*.partial.md` with front matter `squad-kit-plan-status: partial`.");
+  info("Fix limits in `.squad/config.yaml` (`planner.budget`, `planner.maxOutputTokens`) or run again when ready.");
+  blank();
+}
+
 // src/planner/providers/index.ts
 function providerFor(name) {
   switch (name) {
@@ -2861,18 +3468,35 @@ function providerFor(name) {
 var Budget = class {
   constructor(cfg) {
     this.cfg = cfg;
+    this.maxFileReadsAllowed = cfg.maxFileReads;
+    this.maxContextBytesAllowed = cfg.maxContextBytes;
+    this.maxWallSeconds = cfg.maxDurationSeconds;
+    this.maxCostUsdCeiling = cfg.maxCostUsd;
   }
   cfg;
   reads = 0;
   bytes = 0;
   startedAt = Date.now();
-  totalUsage = { inputTokens: 0, outputTokens: 0 };
+  totalUsage = { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+  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.cfg.maxFileReads) {
-      return { ok: false, reason: `max file reads (${this.cfg.maxFileReads}) reached` };
+    if (this.reads >= this.maxFileReadsAllowed) {
+      return { ok: false, reason: `max file reads (${this.maxFileReadsAllowed}) reached` };
     }
-    if (this.bytes + nextFileBytes > this.cfg.maxContextBytes) {
-      return { ok: false, reason: `context budget (${this.cfg.maxContextBytes} bytes) would be exceeded` };
+    if (this.bytes + nextFileBytes > this.maxContextBytesAllowed) {
+      return { ok: false, reason: `context budget (${this.maxContextBytesAllowed} bytes) would be exceeded` };
     }
     return { ok: true };
   }
@@ -2884,13 +3508,15 @@ var Budget = class {
     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.cfg.maxDurationSeconds;
+    return (Date.now() - this.startedAt) / 1e3 > this.maxWallSeconds;
   }
   overCost() {
-    if (this.cfg.maxCostUsd === void 0) return false;
-    return (this.totalUsage.costUsd ?? 0) > this.cfg.maxCostUsd;
+    if (this.maxCostUsdCeiling === void 0) return false;
+    return (this.totalUsage.costUsd ?? 0) > this.maxCostUsdCeiling;
   }
   snapshot() {
     return {
@@ -3029,10 +3655,19 @@ function formatSequence(n) {
 }
 
 // src/planner/writer.ts
-function writePlanFile(input6) {
-  const { paths, config: config2, story } = input6;
+function planFileSlugParts(config2, story) {
+  const baseSlug = slugify(story.id);
+  const trackerId = config2.naming.includeTrackerId && config2.tracker.type !== "none" ? trackerIdForFilename(config2.tracker.type, story.id) : "";
+  const trackerPart = trackerId && trackerId.toLowerCase() !== baseSlug ? `-${trackerId}` : "";
+  return { baseSlug, trackerPart };
+}
+function writePlanFile(input5) {
+  const { paths, config: config2, story } = input5;
   const featurePlanDir = path13.join(paths.plansDir, story.feature);
   fs20.mkdirSync(featurePlanDir, { recursive: true });
+  if (input5.partial) {
+    return writePartialPlanFile(input5, featurePlanDir, paths, config2, story);
+  }
   const existing = findExistingPlan(featurePlanDir, story.id);
   let targetPath;
   let nn;
@@ -3043,23 +3678,53 @@ function writePlanFile(input6) {
     overwrote = true;
   } else {
     nn = scanPlans(paths.plansDir).nextGlobal;
-    const titleHintSlug = story.titleHint ? slugify(story.titleHint) : "";
-    const baseSlug = titleHintSlug || slugify(story.id);
-    const trackerId = config2.naming.includeTrackerId && config2.tracker.type !== "none" ? trackerIdForFilename(config2.tracker.type, story.id) : "";
-    const trackerPart = trackerId && trackerId !== baseSlug ? `-${trackerId}` : "";
+    const { baseSlug, trackerPart } = planFileSlugParts(config2, story);
     targetPath = path13.join(featurePlanDir, `${formatSequence(nn)}-story-${baseSlug}${trackerPart}.md`);
   }
-  const body = `${input6.metadataHeader.trimEnd()}
+  const body = `${input5.metadataHeader.trimEnd()}
+
+${input5.planBodyMarkdown.trimStart()}
+`;
+  fs20.writeFileSync(targetPath, body, "utf8");
+  upsertOverviewRow(featurePlanDir, story.feature, nn, path13.basename(targetPath), story, false);
+  return { planFile: targetPath, sequenceNumber: nn, overwrote };
+}
+function writePartialPlanFile(input5, featurePlanDir, paths, config2, story) {
+  const existingPartial = findExistingPartialPlan(featurePlanDir, story.id);
+  let targetPath;
+  let nn;
+  let overwrote = false;
+  if (existingPartial) {
+    targetPath = existingPartial.absPath;
+    nn = existingPartial.nn;
+    overwrote = true;
+  } else {
+    nn = scanPlans(paths.plansDir).nextGlobal;
+    const { baseSlug, trackerPart } = planFileSlugParts(config2, story);
+    targetPath = path13.join(featurePlanDir, `${formatSequence(nn)}-story-${baseSlug}${trackerPart}.partial.md`);
+  }
+  const body = `${input5.metadataHeader.trimEnd()}
 
-${input6.planBodyMarkdown.trimStart()}
+${input5.planBodyMarkdown.trimStart()}
 `;
   fs20.writeFileSync(targetPath, body, "utf8");
-  upsertOverviewRow(featurePlanDir, story.feature, nn, path13.basename(targetPath), story);
+  upsertOverviewRow(featurePlanDir, story.feature, nn, path13.basename(targetPath), story, true);
   return { planFile: targetPath, sequenceNumber: nn, overwrote };
 }
 function findExistingPlan(featureDir, storyId) {
   if (!fs20.existsSync(featureDir)) return void 0;
   const pattern = /^(\d{2,})-story-.+\.md$/;
+  for (const entry of fs20.readdirSync(featureDir)) {
+    if (entry.endsWith(".partial.md")) continue;
+    const m = entry.match(pattern);
+    if (!m) continue;
+    if (entry.includes(storyId)) return { absPath: path13.join(featureDir, entry), nn: parseInt(m[1], 10) };
+  }
+  return void 0;
+}
+function findExistingPartialPlan(featureDir, storyId) {
+  if (!fs20.existsSync(featureDir)) return void 0;
+  const pattern = /^(\d{2,})-story-.+\.partial\.md$/;
   for (const entry of fs20.readdirSync(featureDir)) {
     const m = entry.match(pattern);
     if (!m) continue;
@@ -3067,9 +3732,10 @@ function findExistingPlan(featureDir, storyId) {
   }
   return void 0;
 }
-function upsertOverviewRow(featureDir, feature, nn, filename, story) {
+function upsertOverviewRow(featureDir, feature, nn, filename, story, isPartial) {
   const overviewPath = path13.join(featureDir, "00-overview.md");
-  const row = `| ${formatSequence(nn)} | \`${filename}\` | ${story.titleHint ?? story.id} | ${story.id} | \u2014 |`;
+  const titleCell = isPartial ? `${story.titleHint ?? story.id} (partial)` : story.titleHint ?? story.id;
+  const row = `| ${formatSequence(nn)} | \`${filename}\` | ${titleCell} | ${story.id} | \u2014 |`;
   if (!fs20.existsSync(overviewPath)) {
     const content = `# ${feature} \u2014 plan overview
 
@@ -3115,7 +3781,54 @@ function buildMetadataHeader(args) {
     `${args.inputTokens} in / ${args.outputTokens} out tokens`,
     args.costUsd !== void 0 ? `~$${args.costUsd.toFixed(2)}` : null
   ].filter(Boolean);
-  return `<!-- squad-kit: ${parts.join(", ")} -->`;
+  const line1 = `<!-- squad-kit: ${parts.join(", ")} -->`;
+  if (args.planStatus === "partial") {
+    return `${line1}
+
+---
+squad-kit-plan-status: partial
+---`;
+  }
+  return line1;
+}
+
+// src/core/last-run.ts
+import fs21 from "fs/promises";
+import path14 from "path";
+async function writeLastRun(paths, rec) {
+  const file = path14.join(paths.squadDir, ".last-run.json");
+  await fs21.writeFile(file, JSON.stringify({ ...rec, version: 1 }, null, 2) + "\n", "utf8");
+}
+async function readLastRun(paths) {
+  const file = path14.join(paths.squadDir, ".last-run.json");
+  try {
+    const raw = await fs21.readFile(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/ui/planner-cache-summary.ts
+function formatTokenK(n) {
+  return `${(n / 1e3).toFixed(1)}k`;
+}
+function formatPlannerCacheLine(opts) {
+  if (!opts.cacheEnabled) {
+    return "cache disabled";
+  }
+  const { stats } = opts;
+  if (stats.cacheReadTokens > 0) {
+    const pct = Math.round(stats.cacheHitRatio * 100);
+    const total = stats.inputTokens + stats.cacheReadTokens;
+    const read = formatTokenK(stats.cacheReadTokens);
+    const tot = formatTokenK(total);
+    const written = stats.cacheCreationTokens > 0 ? ` \xB7 ${formatTokenK(stats.cacheCreationTokens)} written` : "";
+    return `cache hit ${pct}% (${read} read / ${tot} total${written})`;
+  }
+  return "cache miss 0% \u2014 run `squad doctor` to diagnose";
 }
 
 // src/commands/new-plan.ts
@@ -3149,8 +3862,8 @@ async function runNewPlan(intakePath, opts) {
   }
 }
 function resolveFromPath(intakePath, stories, root) {
-  const resolved = path14.resolve(intakePath.trim());
-  if (!fs21.existsSync(resolved)) {
+  const resolved = path15.resolve(intakePath.trim());
+  if (!fs22.existsSync(resolved)) {
     throw new Error(
       `Intake not found: ${resolved}. Run \`squad list\` to see intakes, or \`squad new-story\` to create one first.`
     );
@@ -3162,7 +3875,7 @@ function resolveFromPath(intakePath, stories, root) {
   );
 }
 function relativeStoriesDir(root) {
-  return path14.relative(root, path14.join(root, ".squad", "stories"));
+  return path15.relative(root, path15.join(root, ".squad", "stories"));
 }
 async function pickStory(stories, opts) {
   const candidates = opts.all ? stories : stories.filter((s) => !s.planFile);
@@ -3193,7 +3906,7 @@ async function pickStory(stories, opts) {
       value: s.intakePath
     }))
   });
-  return candidates.find((s) => path14.resolve(s.intakePath) === path14.resolve(pick));
+  return candidates.find((s) => path15.resolve(s.intakePath) === path15.resolve(pick));
 }
 function formatLabel(s) {
   const head = `${s.feature} / ${s.id}`;
@@ -3214,7 +3927,19 @@ async function confirmOverwrite(story, interactive, yes) {
   const go = await confirm6({ message: "Proceed and regenerate?", default: false });
   return go;
 }
-async function emitViaApi(story, paths, config2, _opts) {
+function printPlannerRunIncompleteSummary(result, relPlanFile) {
+  blank();
+  warning("Planning stopped before the model reported a clean completion.");
+  kv("saved", relPlanFile, 8);
+  if (result.userCancelled) kv("stopped", "you chose not to continue after a limit", 8);
+  if (result.timedOut) kv("timed out", "yes", 8);
+  if (result.budgetExhausted) kv("read budget", "exhausted (model was asked to finalise)", 8);
+  if (result.incompleteKind) kv("detail", result.incompleteKind, 8);
+  blank();
+  info("The file uses the `.partial.md` suffix and YAML `squad-kit-plan-status: partial`.");
+  info("Raise limits in `.squad/config.yaml` (`planner.budget`, `planner.maxOutputTokens`) or re-run when ready.");
+}
+async function emitViaApi(story, paths, config2, opts) {
   const planner = config2.planner;
   if (!planner?.enabled) {
     throw new Error(
@@ -3239,6 +3964,10 @@ async function emitViaApi(story, paths, config2, _opts) {
     `${planner.budget.maxFileReads} reads \xB7 ${(planner.budget.maxContextBytes / 1024).toFixed(0)} KB \xB7 ${planner.budget.maxDurationSeconds}s`
   );
   blank();
+  const interactive = !opts.yes && Boolean(process.stdin.isTTY);
+  if (interactive) {
+    printPlannerApiCostNotice();
+  }
   const mapSpinner = spinner("building repo map\u2026");
   const repoMap = buildRepoMap(paths.root);
   mapSpinner.succeed(
@@ -3254,6 +3983,19 @@ async function emitViaApi(story, paths, config2, _opts) {
   const userPrompt = composeUserPrompt({ intakeContent: readFile(story.intakePath) });
   const sessionSpinner = { current: null };
   const startedAt = Date.now();
+  const cacheEnabled = planner.cache?.enabled ?? true;
+  const decideOnLimit = interactive ? async (ctx) => {
+    printPlannerLimitExplanation(ctx);
+    const ans = await select5({
+      message: "Continue this planning session? (Continuing sends more API requests and is billed.)",
+      choices: [
+        { name: "Continue \u2014 extend limits for this run", value: "continue" },
+        { name: "Stop \u2014 save partial plan and exit", value: "cancel" }
+      ]
+    });
+    if (ans === "cancel") printPlannerLimitNextSteps();
+    return ans;
+  } : void 0;
   const result = await runPlanner({
     root: paths.root,
     provider,
@@ -3262,6 +4004,9 @@ async function emitViaApi(story, paths, config2, _opts) {
     systemPrompt,
     userPrompt,
     budget,
+    maxOutputTokens: planner.maxOutputTokens,
+    cacheEnabled,
+    decideOnLimit,
     onToolCall: (tc, bytes, total) => {
       const p = tc.input.path ?? "<unknown>";
       sessionSpinner.current?.succeed(
@@ -3287,6 +4032,7 @@ 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 header = buildMetadataHeader({
     provider: planner.provider,
     model,
@@ -3295,18 +4041,30 @@ async function emitViaApi(story, paths, config2, _opts) {
     inputTokens: snap.usage.inputTokens,
     outputTokens: snap.usage.outputTokens,
     durationMs: elapsedMs,
-    costUsd: snap.usage.costUsd
+    costUsd: snap.usage.costUsd,
+    planStatus: success2 ? void 0 : "partial"
   });
   const { planFile, sequenceNumber, overwrote } = writePlanFile({
     paths,
     config: config2,
     story,
     planBodyMarkdown: result.planText,
-    metadataHeader: header
+    metadataHeader: header,
+    partial: !success2
   });
+  try {
+    await writeLastRun(paths, {
+      stats: result.stats,
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      provider: planner.provider,
+      model
+    });
+  } catch {
+  }
+  const relPlan = path15.relative(paths.root, planFile);
   blank();
-  summaryBox(" plan generated ", [
-    { key: "file", value: path14.relative(paths.root, planFile) },
+  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: "reads", value: `${snap.reads} files \xB7 ${(snap.bytes / 1024).toFixed(1)} KB` },
@@ -3314,18 +4072,28 @@ async function emitViaApi(story, paths, config2, _opts) {
       key: "tokens",
       value: `${snap.usage.inputTokens} in \xB7 ${snap.usage.outputTokens} out${snap.usage.costUsd !== void 0 ? `  \u2248 $${snap.usage.costUsd.toFixed(2)}` : ""}`
     },
+    { key: "cache", value: formatPlannerCacheLine({ cacheEnabled, stats: result.stats }) },
+    {
+      key: "max out",
+      value: `${planner.maxOutputTokens ?? DEFAULT_PLANNER_MAX_OUTPUT_TOKENS} tok/req`
+    },
     { key: "time", value: `${Math.round(elapsedMs / 1e3)}s` },
-    { key: "action", value: overwrote ? "overwrote existing plan" : "new plan" }
+    {
+      key: "action",
+      value: success2 ? overwrote ? "overwrote existing plan" : "new plan" : "partial plan (review limits)"
+    }
   ]);
-  if (result.budgetExhausted) warning("Budget exhausted mid-plan. Review and, if needed, re-run with a larger budget.");
-  if (result.timedOut) warning("Planner timed out; plan may be incomplete.");
-  if (!result.finishedNormally && !result.budgetExhausted && !result.timedOut) {
-    warning("Planner did not reach end_turn. Inspect the plan carefully.");
+  if (!success2) {
+    printPlannerRunIncompleteSummary(result, relPlan);
+    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 ${path14.basename(planFile)}`);
+  info(`next  \u2192  open a new agent chat and attach only ${path15.basename(planFile)}`);
 }
-async function emitCopyPrompt(story, _paths, config2, clipboard) {
+async function emitCopyPrompt(story, paths, config2, clipboard) {
   const intakeContent = readFile(story.intakePath);
   const metaPromptTemplate = readBundledPrompt("generate-plan.md");
   const composed = render(metaPromptTemplate, {
@@ -3334,13 +4102,44 @@ async function emitCopyPrompt(story, _paths, config2, clipboard) {
     trackerType: config2.tracker.type,
     intakeContent
   });
+  const promptFile = path15.join(paths.squadDir, ".last-copy-prompt.md");
+  fs22.writeFileSync(promptFile, composed, "utf8");
+  const relPromptFile = path15.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)" };
+  blank();
+  divider("planner prompt ready");
+  kv("mode", "copy-paste", 10);
+  kv("story", `${story.feature} / ${story.id}`, 10);
+  kv("prompt", relPromptFile, 10);
+  kv("size", `${formatKB(bytes)} \xB7 ~${formatCount(estTokens)} tokens (est)`, 10);
+  if (clipResult.ok) {
+    kv("clipboard", `\u2713 copied via ${clipResult.tool}`, 10);
+  } else {
+    kv("clipboard", `! ${clipResult.reason}`, 10);
+  }
   printModelBanner(config2);
-  process.stdout.write(composed);
-  if (!composed.endsWith("\n")) process.stdout.write("\n");
-  if (clipboard) {
-    const ok = await copyToClipboard(composed);
-    if (ok) info("copied to clipboard");
+  blank();
+  step("Next:");
+  info("1) Open your agent chat (Cursor / Claude Code / Copilot / Gemini).");
+  info("2) Switch to a strong plan model (Opus 4.x / GPT-5.3 Codex thinking / Gemini deep-think).");
+  if (clipResult.ok) {
+    info("3) Paste from clipboard and let the agent work. It will read files and write the plan itself.");
+  } else {
+    info(`3) Open ${relPromptFile}, paste its contents into the agent chat, and let it work.`);
   }
+  info(
+    `4) The agent writes the plan to .squad/plans/${story.feature}/<nn>-story-${story.id}.md. Review it, then open a fresh chat to implement (attach only the plan file).`
+  );
+}
+function formatKB(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+function formatCount(n) {
+  if (n < 1e3) return String(n);
+  return `${(n / 1e3).toFixed(1)}k`;
 }
 function printModelBanner(config2) {
   if (!isInteractive()) return;
@@ -3363,7 +4162,7 @@ function printModelBanner(config2) {
 }
 
 // src/commands/status.ts
-import fs22 from "fs";
+import fs23 from "fs";
 var kw = 28;
 function probeTrackerCredential(config2, overlay) {
   const { client, error: error2 } = clientFor(config2, overlay);
@@ -3389,7 +4188,7 @@ async function runStatus() {
   const scan = scanPlans(paths.plansDir);
   const storyCount = listStories(paths).length;
   const planCount = scan.usedNumbers.length;
-  const secrets = fs22.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
+  const secrets = fs23.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
   const overlay = overlayTrackerEnv(secrets);
   banner();
   step("squad-kit status");
@@ -3443,13 +4242,13 @@ function buildTrackerLine(config2, overlay) {
 }
 
 // src/commands/list.ts
-import path15 from "path";
+import path16 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 ? path15.join(paths.plansDir, r.feature, r.planFile) : void 0;
+    const planAbs = r.planFile ? path16.join(paths.plansDir, r.feature, r.planFile) : void 0;
     const meta = planAbs ? readPlanMetadata(planAbs) : void 0;
     return {
       feature: r.feature,
@@ -3469,7 +4268,7 @@ async function runList(opts) {
     r.id,
     r.hasIntake ? "yes" : "\u2014",
     r.planFile ?? theme_exports.dim("\u2014"),
-    r.meta?.generatedBy ?? (r.planFile ? "copy-paste" : theme_exports.dim("\u2014"))
+    r.meta?.generatedBy ?? (r.planFile ? theme_exports.dim("not recorded") : theme_exports.dim("\u2014"))
   ]);
   printTable([header, ...table]);
 }
@@ -3488,9 +4287,9 @@ function stripAnsi(s) {
 }
 
 // src/commands/tracker-link.ts
-import fs23 from "fs";
-import path16 from "path";
-import { input as input5, select as select6 } from "@inquirer/prompts";
+import fs24 from "fs";
+import path17 from "path";
+import { input as input4, select as select6 } from "@inquirer/prompts";
 async function runTrackerLink(storyPath, trackerId, opts = {}) {
   const root = requireSquadRoot();
   const paths = buildPaths(root);
@@ -3522,7 +4321,7 @@ async function runTrackerLink(storyPath, trackerId, opts = {}) {
         "Usage: squad tracker link [story-path] [tracker-id]. Run `squad tracker link` without arguments in a TTY to pick from a list, or pass `--yes` to opt out of prompts."
       );
     }
-    resolvedTrackerId = (await input5({
+    resolvedTrackerId = (await input4({
       message: `${config2.tracker.type} work-item id:`,
       validate: (v) => {
         const trimmed = v.trim();
@@ -3536,17 +4335,21 @@ 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 = path16.resolve(resolvedStoryPath);
-  const intakeFile = resolved.endsWith("intake.md") ? resolved : path16.join(resolved, "intake.md");
-  if (!fs23.existsSync(intakeFile)) {
+  const resolved = path17.resolve(resolvedStoryPath);
+  const intakeFile = resolved.endsWith("intake.md") ? resolved : path17.join(resolved, "intake.md");
+  if (!fs24.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 = fs23.readFileSync(intakeFile, "utf8");
+  const content = fs24.readFileSync(intakeFile, "utf8");
   const updated = upsertTrackerId(content, resolvedTrackerId);
-  fs23.writeFileSync(intakeFile, updated, "utf8");
-  success(`Linked tracker id ${resolvedTrackerId} \u2192 ${path16.relative(root, intakeFile)}`);
+  fs24.writeFileSync(intakeFile, updated, "utf8");
+  success(`Linked tracker id ${resolvedTrackerId} \u2192 ${path17.relative(root, intakeFile)}`);
+  blank();
+  step("Next:");
+  info("1) Review the intake \u2014 the Source block at the top now carries the tracker id.");
+  info("2) Run `squad new-plan --api` (or `--copy`) to generate the plan for this story.");
 }
 function upsertTrackerId(content, id) {
   const pattern = /(-\s*\*\*Work item id:\*\*)[^\n]*/;
@@ -3560,8 +4363,8 @@ function upsertTrackerId(content, id) {
 }
 
 // src/commands/doctor.ts
-import fs24 from "fs";
-import path17 from "path";
+import fs25 from "fs";
+import path18 from "path";
 async function gatherContext(paths) {
   const ctx = { hasLegacyPromptsDir: false };
   try {
@@ -3570,29 +4373,29 @@ async function gatherContext(paths) {
     ctx.configError = err;
   }
   try {
-    ctx.secrets = fs24.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
+    ctx.secrets = fs25.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
   } catch (err) {
     ctx.secretsError = err;
   }
-  ctx.hasLegacyPromptsDir = fs24.existsSync(paths.promptsDir);
+  ctx.hasLegacyPromptsDir = fs25.existsSync(paths.promptsDir);
   return ctx;
 }
 function gitignoreHasManagedBlock(repoRoot) {
-  const gitignore = path17.join(repoRoot, ".gitignore");
-  return fs24.existsSync(gitignore) && fs24.readFileSync(gitignore, "utf8").includes(".squad/secrets.yaml");
+  const gitignore = path18.join(repoRoot, ".gitignore");
+  return fs25.existsSync(gitignore) && fs25.readFileSync(gitignore, "utf8").includes(".squad/secrets.yaml");
 }
 function gitignoreHasTrashPattern(repoRoot) {
-  const gitignore = path17.join(repoRoot, ".gitignore");
-  return fs24.existsSync(gitignore) && fs24.readFileSync(gitignore, "utf8").includes(SQUAD_TRASH_PATTERN);
+  const gitignore = path18.join(repoRoot, ".gitignore");
+  return fs25.existsSync(gitignore) && fs25.readFileSync(gitignore, "utf8").includes(SQUAD_TRASH_PATTERN);
 }
 async function checkDirStructure(paths, _ctx, fix) {
-  const need = [paths.squadDir, paths.storiesDir, paths.plansDir].filter((p) => !fs24.existsSync(p));
+  const need = [paths.squadDir, paths.storiesDir, paths.plansDir].filter((p) => !fs25.existsSync(p));
   if (need.length === 0) {
     return { id: "dirs", name: ".squad/ directory structure", status: "ok" };
   }
   if (fix) {
     for (const p of need) {
-      fs24.mkdirSync(p, { recursive: true });
+      fs25.mkdirSync(p, { recursive: true });
     }
     return { id: "dirs", name: ".squad/ directory structure", status: "ok", detail: "repaired" };
   }
@@ -3600,7 +4403,7 @@ async function checkDirStructure(paths, _ctx, fix) {
     id: "dirs",
     name: ".squad/ directory structure",
     status: "warn",
-    detail: `missing: ${need.map((p) => path17.relative(paths.root, p)).join(", ")}`,
+    detail: `missing: ${need.map((p) => path18.relative(paths.root, p)).join(", ")}`,
     fixable: true,
     fixHint: "squad doctor --fix"
   };
@@ -3655,15 +4458,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 (!fs24.existsSync(paths.secretsFile)) {
+  if (!fs25.existsSync(paths.secretsFile)) {
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "ok", detail: "not present" };
   }
-  const mode = fs24.statSync(paths.secretsFile).mode & 511;
+  const mode = fs25.statSync(paths.secretsFile).mode & 511;
   if (mode === 384) {
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "ok" };
   }
   if (fix) {
-    fs24.chmodSync(paths.secretsFile, 384);
+    fs25.chmodSync(paths.secretsFile, 384);
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "ok", detail: "repaired" };
   }
   return {
@@ -3684,7 +4487,7 @@ async function checkSecretsParseable(_paths, ctx) {
       detail: ctx.secretsError.message
     };
   }
-  if (!fs24.existsSync(_paths.secretsFile)) {
+  if (!fs25.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" };
@@ -3849,6 +4652,19 @@ async function checkPlannerTierAwareness(_paths, ctx) {
   if (!/opus/i.test(planModel)) {
     return { id, name, status: "ok", detail: `${planModel} is comfortably under Tier 1` };
   }
+  const cacheOn = ctx.config.planner?.cache?.enabled !== false;
+  if (cacheOn) {
+    return {
+      id,
+      name,
+      status: "warn",
+      detail: "Anthropic Tier 1 with Opus \u2014 tight but viable with prompt caching on",
+      fixHint: [
+        "Caching saves ~70% on billed input tokens. Keep `planner.cache.enabled: true` in config.",
+        "If you still hit 429s on long runs, reduce `planner.budget.maxContextBytes` or use Haiku for plan phase."
+      ].join("\n")
+    };
+  }
   return {
     id,
     name,
@@ -3857,6 +4673,66 @@ async function checkPlannerTierAwareness(_paths, ctx) {
     fixHint: "Run `squad config set planner` and pick a Sonnet or Haiku id for planner.modelOverride.anthropic, or upgrade tier at https://console.anthropic.com/settings/limits. squad-kit will auto-retry a 429 once (waiting up to 90s), but repeated throttling means the plan model is simply too big for your quota."
   };
 }
+async function checkPlannerCache(paths, ctx) {
+  const id = "planner-cache";
+  const name = "planner cache effectiveness";
+  const config2 = ctx.config;
+  const cacheCfg = config2?.planner?.cache;
+  if (config2?.planner?.enabled !== true) {
+    return { id, name, status: "skip", detail: "planner disabled \u2014 cache check not applicable" };
+  }
+  if (cacheCfg?.enabled === false) {
+    return {
+      id,
+      name,
+      status: "warn",
+      detail: "prompt caching is disabled in .squad/config.yaml",
+      fixHint: "Cache saves ~70% on billed tokens. Re-enable with `squad config set planner`."
+    };
+  }
+  const lastRun = await readLastRun(paths);
+  if (!lastRun) {
+    return {
+      id,
+      name,
+      status: "skip",
+      detail: "no planner runs logged yet",
+      fixHint: "Run `squad new-plan --api` once, then re-run `squad doctor` to see cache telemetry."
+    };
+  }
+  const { stats } = lastRun;
+  const hitPct = Math.round(stats.cacheHitRatio * 100);
+  if (stats.cacheReadTokens === 0 && stats.turns > 1) {
+    return {
+      id,
+      name,
+      status: "fail",
+      detail: `caching configured but last run saw 0% hits across ${stats.turns} turns`,
+      fixHint: [
+        "Possible causes:",
+        "  \u2022 Planner provider is not Anthropic and the prefix is below 1024 tokens (OpenAI / Google need larger prefixes).",
+        "  \u2022 System prompt is mutating between turns \u2014 check recent changes.",
+        "  \u2022 Using an older model that doesn't support caching.",
+        `Provider: ${lastRun.provider}/${lastRun.model}. Run \`NODE_ENV=development squad new-plan --api\` to surface prefix-mismatch warnings.`
+      ].join("\n")
+    };
+  }
+  if (hitPct < 30 && stats.turns > 3) {
+    return {
+      id,
+      name,
+      status: "warn",
+      detail: `low cache hit rate: ${hitPct}% (last run, ${stats.turns} turns)`,
+      fixHint: "Expected \u226560% for Anthropic, \u226540% for OpenAI, \u226550% for Google after 3+ turns. Prefix may be unstable."
+    };
+  }
+  return {
+    id,
+    name,
+    status: "ok",
+    detail: `caching active \u2014 last run ${hitPct}% hit (${formatTokenK(stats.cacheReadTokens)} read, ${lastRun.provider}/${lastRun.model})`
+  };
+}
 async function checkTrackerConfig(_paths, ctx) {
   if (!ctx.config) {
     return { id: "tracker-config", name: "tracker configuration", status: "skip", detail: "config unavailable" };
@@ -3979,6 +4855,7 @@ async function runAllChecks(paths, ctx, fix) {
   await add("planner credential resolves", () => checkPlannerCredential(paths, ctx));
   await add("planner model resolves at provider", () => checkPlannerModel(paths, ctx));
   await add("planner tier vs. model", () => checkPlannerTierAwareness(paths, ctx));
+  await add("planner cache effectiveness", () => checkPlannerCache(paths, ctx));
   await add("tracker configuration", () => checkTrackerConfig(paths, ctx));
   await add("tracker credential resolves", () => checkTrackerCredential(paths, ctx));
   await add("tracker connectivity", () => checkTrackerConnectivity(paths, ctx));
@@ -4084,23 +4961,23 @@ async function runDoctor(opts) {
 }
 
 // src/commands/migrate.ts
-import fs25 from "fs";
-import path18 from "path";
+import fs26 from "fs";
+import path19 from "path";
 import { confirm as confirm7 } from "@inquirer/prompts";
 var LEGACY_PROMPTS_MIGRATION = {
   id: "legacy-prompts",
   name: "Remove legacy .squad/prompts/",
-  isApplied: (paths) => !fs25.existsSync(paths.promptsDir),
-  describe: (paths) => `delete ${path18.relative(paths.root, paths.promptsDir)} (prompts are now bundled in squad-kit)`,
+  isApplied: (paths) => !fs26.existsSync(paths.promptsDir),
+  describe: (paths) => `delete ${path19.relative(paths.root, paths.promptsDir)} (prompts are now bundled in squad-kit)`,
   apply: (paths) => {
     const target = paths.promptsDir;
-    if (!target.includes(path18.sep + ".squad" + path18.sep + "prompts")) {
+    if (!target.includes(path19.sep + ".squad" + path19.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 (fs25.existsSync(target)) {
-      fs25.rmSync(target, { recursive: true, force: true });
+    if (fs26.existsSync(target)) {
+      fs26.rmSync(target, { recursive: true, force: true });
     }
   }
 };
@@ -4108,8 +4985,8 @@ var GITIGNORE_MIGRATION = {
   id: "gitignore",
   name: "Ensure .gitignore managed block",
   isApplied: (paths) => {
-    const f = path18.join(paths.root, ".gitignore");
-    return fs25.existsSync(f) && fs25.readFileSync(f, "utf8").includes(".squad/secrets.yaml");
+    const f = path19.join(paths.root, ".gitignore");
+    return fs26.existsSync(f) && fs26.readFileSync(f, "utf8").includes(".squad/secrets.yaml");
   },
   describe: () => "add squad-kit managed block to .gitignore",
   apply: (paths) => {
@@ -4121,23 +4998,23 @@ var SECRETS_PERMS_MIGRATION = {
   name: "Tighten .squad/secrets.yaml permissions",
   isApplied: (paths) => {
     if (process.platform === "win32") return true;
-    if (!fs25.existsSync(paths.secretsFile)) return true;
-    const st = fs25.statSync(paths.secretsFile);
+    if (!fs26.existsSync(paths.secretsFile)) return true;
+    const st = fs26.statSync(paths.secretsFile);
     return (st.mode & 511) === 384;
   },
-  describe: (paths) => `chmod 0600 ${path18.relative(paths.root, paths.secretsFile)}`,
+  describe: (paths) => `chmod 0600 ${path19.relative(paths.root, paths.secretsFile)}`,
   apply: (paths) => {
     if (process.platform === "win32") return;
-    if (fs25.existsSync(paths.secretsFile)) fs25.chmodSync(paths.secretsFile, 384);
+    if (fs26.existsSync(paths.secretsFile)) fs26.chmodSync(paths.secretsFile, 384);
   }
 };
 var PLANNER_BUDGET_DEFAULTS_MIGRATION = {
   id: "planner-budget-defaults",
   name: "Backfill planner.budget defaults in config.yaml",
   isApplied: (paths) => {
-    if (!fs25.existsSync(paths.configFile)) return true;
+    if (!fs26.existsSync(paths.configFile)) return true;
     try {
-      const raw = fs25.readFileSync(paths.configFile, "utf8");
+      const raw = fs26.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);
@@ -4156,9 +5033,9 @@ var CONFIG_NORMALIZE_MIGRATION = {
   id: "config-normalize",
   name: "Normalise .squad/config.yaml formatting",
   isApplied: (paths) => {
-    if (!fs25.existsSync(paths.configFile)) return true;
+    if (!fs26.existsSync(paths.configFile)) return true;
     try {
-      const raw = fs25.readFileSync(paths.configFile, "utf8");
+      const raw = fs26.readFileSync(paths.configFile, "utf8");
       const cfg = loadConfig(paths.configFile);
       return raw.trim() === serializeConfig(cfg).trim();
     } catch {
@@ -4167,7 +5044,7 @@ var CONFIG_NORMALIZE_MIGRATION = {
   },
   describe: () => "rewrite config.yaml with canonical YAML formatting (drops comments)",
   apply: (paths) => {
-    if (!fs25.existsSync(paths.configFile)) return;
+    if (!fs26.existsSync(paths.configFile)) return;
     const cfg = loadConfig(paths.configFile);
     saveConfig(paths.configFile, cfg);
   }
@@ -4235,7 +5112,11 @@ async function runMigrate(opts) {
   }
   info("");
   success(`Applied ${applied}/${pending.length} migration(s).`);
-  info("Run `squad doctor` to verify.");
+  blank();
+  step("Next:");
+  info("1) Run `squad doctor` to verify every check is green.");
+  info("2) If you were upgrading from 0.1.x, review .squad/config.yaml \u2014 new defaults (planner, cache) may have been added.");
+  info("3) Continue your usual workflow: `squad new-story` \u2192 fill intake \u2192 `squad new-plan`.");
 }
 
 // src/commands/upgrade.ts
@@ -4244,8 +5125,8 @@ import process3 from "process";
 import { confirm as confirm8 } from "@inquirer/prompts";
 
 // src/core/package-info.ts
-import fs26 from "fs";
-import path19 from "path";
+import fs27 from "fs";
+import path20 from "path";
 function changelogBlobUrl(repositoryUrl, version) {
   let base = repositoryUrl;
   if (!base) base = "https://github.com/AzmSquad/squad-kit";
@@ -4256,9 +5137,9 @@ function changelogBlobUrl(repositoryUrl, version) {
 }
 function readInstalledPackage() {
   const root = packageRoot();
-  const pkgFile = path19.join(root, "package.json");
-  const pkg = JSON.parse(fs26.readFileSync(pkgFile, "utf8"));
-  const isDevInstall = fs26.existsSync(path19.join(root, "src"));
+  const pkgFile = path20.join(root, "package.json");
+  const pkg = JSON.parse(fs27.readFileSync(pkgFile, "utf8"));
+  const isDevInstall = fs27.existsSync(path20.join(root, "src"));
   return {
     name: pkg.name,
     version: pkg.version,
@@ -4298,7 +5179,7 @@ function isNewer(a, b) {
 }
 
 // src/core/package-manager.ts
-import path20 from "path";
+import path21 from "path";
 import process2 from "process";
 function detectPackageManager(installRoot) {
   const ua = process2.env.npm_config_user_agent;
@@ -4309,11 +5190,11 @@ function detectPackageManager(installRoot) {
     if (ua.startsWith("npm/")) return { pm: "npm", reason: "npm_config_user_agent" };
   }
   const root = installRoot.toLowerCase();
-  if (root.includes(`${path20.sep}pnpm${path20.sep}`) || root.includes(`${path20.sep}.pnpm${path20.sep}`))
+  if (root.includes(`${path21.sep}pnpm${path21.sep}`) || root.includes(`${path21.sep}.pnpm${path21.sep}`))
     return { pm: "pnpm", reason: `install path contains pnpm` };
-  if (root.includes(`${path20.sep}.yarn${path20.sep}`) || root.includes(`${path20.sep}yarn${path20.sep}`))
+  if (root.includes(`${path21.sep}.yarn${path21.sep}`) || root.includes(`${path21.sep}yarn${path21.sep}`))
     return { pm: "yarn", reason: `install path contains yarn` };
-  if (root.includes(`${path20.sep}.bun${path20.sep}`) || root.includes(`${path20.sep}bun${path20.sep}`))
+  if (root.includes(`${path21.sep}.bun${path21.sep}`) || root.includes(`${path21.sep}bun${path21.sep}`))
     return { pm: "bun", reason: `install path contains bun` };
   return { pm: "npm", reason: "default fallback" };
 }
@@ -4414,8 +5295,8 @@ function spawnInherit(cmd, args) {
 }
 
 // src/commands/rm/shared.ts
-import fs27 from "fs";
-import path21 from "path";
+import fs28 from "fs";
+import path22 from "path";
 import { select as select7 } from "@inquirer/prompts";
 var STORY_PLAN = /^(\d{2,})-story-.+\.md$/;
 function canPromptForRm(opts) {
@@ -4423,9 +5304,9 @@ function canPromptForRm(opts) {
   return isInteractive() && Boolean(process.stdin.isTTY);
 }
 function removeOverviewRow(featurePlanDir, storyId) {
-  const overview = path21.join(featurePlanDir, "00-overview.md");
-  if (!fs27.existsSync(overview)) return;
-  const src = fs27.readFileSync(overview, "utf8");
+  const overview = path22.join(featurePlanDir, "00-overview.md");
+  if (!fs28.existsSync(overview)) return;
+  const src = fs28.readFileSync(overview, "utf8");
   const lines = src.split("\n");
   const filtered = lines.filter((line2) => {
     if (!line2.startsWith("|")) return true;
@@ -4433,12 +5314,12 @@ function removeOverviewRow(featurePlanDir, storyId) {
     if (/^\|\s*-+/.test(line2)) return true;
     return !line2.includes(storyId);
   });
-  fs27.writeFileSync(overview, filtered.join("\n"), "utf8");
+  fs28.writeFileSync(overview, filtered.join("\n"), "utf8");
 }
 function removeOverviewRowForPlanFile(featurePlanDir, planBasename) {
-  const overview = path21.join(featurePlanDir, "00-overview.md");
-  if (!fs27.existsSync(overview)) return;
-  const src = fs27.readFileSync(overview, "utf8");
+  const overview = path22.join(featurePlanDir, "00-overview.md");
+  if (!fs28.existsSync(overview)) return;
+  const src = fs28.readFileSync(overview, "utf8");
   const token = `\`${planBasename}\``;
   const lines = src.split("\n");
   const filtered = lines.filter((line2) => {
@@ -4447,25 +5328,25 @@ function removeOverviewRowForPlanFile(featurePlanDir, planBasename) {
     if (/^\|\s*-+/.test(line2)) return true;
     return !line2.includes(token);
   });
-  fs27.writeFileSync(overview, filtered.join("\n"), "utf8");
+  fs28.writeFileSync(overview, filtered.join("\n"), "utf8");
 }
 function trashOrDelete(absPaths, trashRoot, useTrash) {
   if (!useTrash) {
-    for (const p of absPaths) fs27.rmSync(p, { recursive: true, force: true });
+    for (const p of absPaths) fs28.rmSync(p, { recursive: true, force: true });
     return { removed: absPaths };
   }
   const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const bucket = path21.join(trashRoot, ts);
-  fs27.mkdirSync(bucket, { recursive: true });
+  const bucket = path22.join(trashRoot, ts);
+  fs28.mkdirSync(bucket, { recursive: true });
   for (const src of absPaths) {
-    const rel = path21.basename(src);
-    let dst = path21.join(bucket, rel);
+    const rel = path22.basename(src);
+    let dst = path22.join(bucket, rel);
     let n = 0;
-    while (fs27.existsSync(dst)) {
+    while (fs28.existsSync(dst)) {
       n += 1;
-      dst = path21.join(bucket, `${n}_${rel}`);
+      dst = path22.join(bucket, `${n}_${rel}`);
     }
-    fs27.renameSync(src, dst);
+    fs28.renameSync(src, dst);
   }
   return { removed: absPaths, trashed: bucket };
 }
@@ -4476,21 +5357,21 @@ function renderPreview(kind, targets, opts) {
     kv(t.kind, t.label, 6);
   }
   if (opts.trash) {
-    info(`Items will move to ${path21.relative(process.cwd(), opts.trashRoot)}/<timestamp>/`);
+    info(`Items will move to ${path22.relative(process.cwd(), opts.trashRoot)}/<timestamp>/`);
   } else if (!opts.dryRun) {
     warning("This is a permanent delete. Pass --trash to move to .squad/.trash/ instead.");
   }
 }
 function listAllPlanListEntries(paths, featureFilter) {
-  if (!fs27.existsSync(paths.plansDir)) return [];
+  if (!fs28.existsSync(paths.plansDir)) return [];
   const out = [];
-  for (const ent of fs27.readdirSync(paths.plansDir, { withFileTypes: true })) {
+  for (const ent of fs28.readdirSync(paths.plansDir, { withFileTypes: true })) {
     if (!ent.isDirectory()) continue;
     if (featureFilter && ent.name !== featureFilter) continue;
-    const featureDir = path21.join(paths.plansDir, ent.name);
-    for (const name of fs27.readdirSync(featureDir)) {
+    const featureDir = path22.join(paths.plansDir, ent.name);
+    for (const name of fs28.readdirSync(featureDir)) {
       if (!STORY_PLAN.test(name)) continue;
-      out.push({ feature: ent.name, file: name, abs: path21.join(featureDir, name) });
+      out.push({ feature: ent.name, file: name, abs: path22.join(featureDir, name) });
     }
   }
   return out.sort((a, b) => (a.feature + a.file).localeCompare(b.feature + b.file));
@@ -4541,34 +5422,34 @@ function resolveStoryFromArg(arg, stories, root) {
     if (s.id === t) return s;
     if (`${s.feature}/${s.id}` === t) return s;
   }
-  const abs = path21.isAbsolute(t) ? t : path21.resolve(root, t);
-  const withIntake = t.endsWith("intake.md") ? abs : path21.join(abs, "intake.md");
+  const abs = path22.isAbsolute(t) ? t : path22.resolve(root, t);
+  const withIntake = t.endsWith("intake.md") ? abs : path22.join(abs, "intake.md");
   return findStoryByIntake(stories, withIntake) ?? findStoryByIntake(stories, abs);
 }
 function isSequenceToken(s) {
   return /^\d{1,4}$/.test(s) && s.length > 0;
 }
 function tryParsePlanFilePath(absPath, paths, featureFilter) {
-  if (!fs27.existsSync(absPath) || !STORY_PLAN.test(path21.basename(absPath))) return void 0;
-  const planRoot = fs27.realpathSync(path21.resolve(paths.plansDir));
-  const fileReal = fs27.realpathSync(path21.resolve(absPath));
-  const rel = path21.relative(planRoot, fileReal);
-  if (rel.startsWith("..") || path21.isAbsolute(rel)) return void 0;
-  const segs = rel.split(path21.sep);
+  if (!fs28.existsSync(absPath) || !STORY_PLAN.test(path22.basename(absPath))) return void 0;
+  const planRoot = fs28.realpathSync(path22.resolve(paths.plansDir));
+  const fileReal = fs28.realpathSync(path22.resolve(absPath));
+  const rel = path22.relative(planRoot, fileReal);
+  if (rel.startsWith("..") || path22.isAbsolute(rel)) return void 0;
+  const segs = rel.split(path22.sep);
   if (segs.length < 2) return void 0;
   const feature = segs[0];
-  const file = segs.slice(1).join(path21.sep);
+  const file = segs.slice(1).join(path22.sep);
   if (featureFilter && feature !== featureFilter) return void 0;
-  return { feature, file, abs: path21.resolve(absPath) };
+  return { feature, file, abs: path22.resolve(absPath) };
 }
 function resolvePlanFromArg(arg, paths, featureFilter) {
   const t = arg.trim();
   if (!t) return void 0;
-  const asPath = path21.isAbsolute(t) ? t : path21.resolve(process.cwd(), t);
+  const asPath = path22.isAbsolute(t) ? t : path22.resolve(process.cwd(), t);
   const a = tryParsePlanFilePath(asPath, paths, featureFilter);
   if (a) return a;
-  if (!path21.isAbsolute(t)) {
-    const under = tryParsePlanFilePath(path21.join(paths.plansDir, t), paths, featureFilter);
+  if (!path22.isAbsolute(t)) {
+    const under = tryParsePlanFilePath(path22.join(paths.plansDir, t), paths, featureFilter);
     if (under) return under;
   }
   if (isSequenceToken(t)) {
@@ -4598,24 +5479,24 @@ function countOverviewDataRows(overviewContent) {
   return n;
 }
 function featureStoriesDirEmpty(paths, feature) {
-  const d = path21.join(paths.storiesDir, feature);
-  if (!fs27.existsSync(d)) return true;
-  return fs27.readdirSync(d).length === 0;
+  const d = path22.join(paths.storiesDir, feature);
+  if (!fs28.existsSync(d)) return true;
+  return fs28.readdirSync(d).length === 0;
 }
 
 // src/commands/rm/story.ts
-import fs29 from "fs";
-import path23 from "path";
+import fs30 from "fs";
+import path24 from "path";
 import { confirm as confirm10 } from "@inquirer/prompts";
 
 // src/commands/rm/feature.ts
-import fs28 from "fs";
-import path22 from "path";
+import fs29 from "fs";
+import path23 from "path";
 import { confirm as confirm9 } from "@inquirer/prompts";
 function countStoryDirs(storiesDir, feature) {
-  const d = path22.join(storiesDir, feature);
-  if (!fs28.existsSync(d)) return 0;
-  return fs28.readdirSync(d, { withFileTypes: true }).filter((x) => x.isDirectory()).length;
+  const d = path23.join(storiesDir, feature);
+  if (!fs29.existsSync(d)) return 0;
+  return fs29.readdirSync(d, { withFileTypes: true }).filter((x) => x.isDirectory()).length;
 }
 async function runRmFeature(featureSlug, opts = {}) {
   const root = requireSquadRoot();
@@ -4649,17 +5530,17 @@ async function runRmFeature(featureSlug, opts = {}) {
       feature = await pickFeatureInteractive(paths);
     }
   }
-  const storyDir = path22.join(paths.storiesDir, feature);
-  const planDir = path22.join(paths.plansDir, feature);
+  const storyDir = path23.join(paths.storiesDir, feature);
+  const planDir = path23.join(paths.plansDir, feature);
   const nStories = countStoryDirs(paths.storiesDir, feature);
   const nPlans = listAllPlanListEntries(paths, feature).length;
-  const hasOverview = fs28.existsSync(path22.join(planDir, "00-overview.md")) ? 1 : 0;
+  const hasOverview = fs29.existsSync(path23.join(planDir, "00-overview.md")) ? 1 : 0;
   const targets = [];
-  if (fs28.existsSync(storyDir)) {
-    targets.push({ label: path22.relative(root, storyDir), absPath: storyDir, kind: "dir" });
+  if (fs29.existsSync(storyDir)) {
+    targets.push({ label: path23.relative(root, storyDir), absPath: storyDir, kind: "dir" });
   }
-  if (fs28.existsSync(planDir)) {
-    targets.push({ label: path22.relative(root, planDir), absPath: planDir, kind: "dir" });
+  if (fs29.existsSync(planDir)) {
+    targets.push({ label: path23.relative(root, planDir), absPath: planDir, kind: "dir" });
   }
   divider("squad rm feature");
   info(`Feature:  ${feature}`);
@@ -4674,7 +5555,7 @@ async function runRmFeature(featureSlug, opts = {}) {
     kv(t.kind, t.label, 6);
   }
   if (useTrash) {
-    info(`Items will move to ${path22.relative(process.cwd(), paths.trashDir)}/<timestamp>/`);
+    info(`Items will move to ${path23.relative(process.cwd(), paths.trashDir)}/<timestamp>/`);
   } else if (!dryRun) {
     warning("This is a permanent delete. Pass --trash to move to .squad/.trash/ instead.");
   }
@@ -4707,7 +5588,7 @@ async function runRmFeature(featureSlug, opts = {}) {
     useTrash
   );
   if (result.trashed) {
-    success(`Feature removed. Items moved to ${path22.relative(root, result.trashed)}.`);
+    success(`Feature removed. Items moved to ${path23.relative(root, result.trashed)}.`);
   } else {
     success("Feature removed (stories and plans directories).");
   }
@@ -4748,11 +5629,11 @@ async function runRmStory(storyPathOrId, opts = {}) {
     }
   }
   const targets = [
-    { label: path23.relative(root, story.storyDir), absPath: story.storyDir, kind: "dir" }
+    { label: path24.relative(root, story.storyDir), absPath: story.storyDir, kind: "dir" }
   ];
   if (story.planFile) {
-    const planAbs = path23.join(paths.plansDir, story.feature, story.planFile);
-    targets.push({ label: path23.relative(root, planAbs), absPath: planAbs, kind: "file" });
+    const planAbs = path24.join(paths.plansDir, story.feature, story.planFile);
+    targets.push({ label: path24.relative(root, planAbs), absPath: planAbs, kind: "file" });
   }
   renderPreview("story", targets, {
     dryRun,
@@ -4777,16 +5658,16 @@ async function runRmStory(storyPathOrId, opts = {}) {
   }
   const absPaths = targets.map((t) => t.absPath);
   const result = trashOrDelete(absPaths, paths.trashDir, useTrash);
-  removeOverviewRow(path23.join(paths.plansDir, story.feature), story.id);
+  removeOverviewRow(path24.join(paths.plansDir, story.feature), story.id);
   if (result.trashed) {
-    success(`Removed (moved to ${path23.relative(root, result.trashed)}).`);
+    success(`Removed (moved to ${path24.relative(root, result.trashed)}).`);
   } else {
     success("Removed story folder, plan file (if any), and overview row.");
   }
-  const featurePlanDir = path23.join(paths.plansDir, story.feature);
-  const overviewPath = path23.join(featurePlanDir, "00-overview.md");
-  if (fs29.existsSync(overviewPath)) {
-    const body = fs29.readFileSync(overviewPath, "utf8");
+  const featurePlanDir = path24.join(paths.plansDir, story.feature);
+  const overviewPath = path24.join(featurePlanDir, "00-overview.md");
+  if (fs30.existsSync(overviewPath)) {
+    const body = fs30.readFileSync(overviewPath, "utf8");
     const onlyShell = countOverviewDataRows(body) === 0;
     if (onlyShell && featureStoriesDirEmpty(paths, story.feature)) {
       if (canPrompt) {
@@ -4806,7 +5687,7 @@ async function runRmStory(storyPathOrId, opts = {}) {
 }
 
 // src/commands/rm/plan.ts
-import path24 from "path";
+import path25 from "path";
 import { confirm as confirm11 } from "@inquirer/prompts";
 async function runRmPlan(planPathOrSequence, opts = {}) {
   const root = requireSquadRoot();
@@ -4842,7 +5723,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: path24.relative(root, plan.abs), absPath: plan.abs, kind: "file" }];
+  const targets = [{ label: path25.relative(root, plan.abs), absPath: plan.abs, kind: "file" }];
   renderPreview("plan", targets, {
     dryRun,
     trash: useTrash,
@@ -4865,14 +5746,14 @@ async function runRmPlan(planPathOrSequence, opts = {}) {
     }
   }
   trashOrDelete([plan.abs], paths.trashDir, useTrash);
-  removeOverviewRowForPlanFile(path24.join(paths.plansDir, plan.feature), plan.file);
-  const intakeHint = linked ? path24.relative(root, linked.intakePath) : `under .squad/stories/${plan.feature}/`;
+  removeOverviewRowForPlanFile(path25.join(paths.plansDir, plan.feature), plan.file);
+  const intakeHint = linked ? path25.relative(root, linked.intakePath) : `under .squad/stories/${plan.feature}/`;
   success(`Plan removed. Run \`squad new-plan ${intakeHint}\` to regenerate.`);
 }
 
 // src/cli.ts
 var program = new Command();
-program.name("squad").description("Plan once, execute cheap. A 3-step SDD workflow CLI.").version("0.2.2");
+program.name("squad").description("Plan once, execute cheap. A 3-step SDD workflow CLI.").version("0.4.0");
 program.command("init").description("Bootstrap .squad/ in the current directory").option("--agents <list>", "Comma-separated agent list: claude-code,cursor,copilot,gemini").option("--tracker <type>", "Tracker type: none|github|linear|jira|azure").option(
   "--tracker-workspace <hostOrOrg>",
   "Jira host or Azure org (non-interactive default; also written to config for jira/azure)"
@@ -4926,6 +5807,10 @@ config.command("remove-credential <section>").description('Delete credentials fo
   )
 );
 program.parseAsync(process.argv).catch((err) => {
+  if (isSquadExit(err)) {
+    if (err.message.trim()) info(err.message);
+    process.exit(err.exitCode);
+  }
   renderError(err);
   process.exit(1);
 });
@@ -4934,6 +5819,10 @@ function wrap(fn) {
     try {
       await fn(opts);
     } catch (err) {
+      if (isSquadExit(err)) {
+        if (err.message.trim()) info(err.message);
+        process.exit(err.exitCode);
+      }
       renderError(err);
       process.exit(1);
     }
@@ -4944,6 +5833,10 @@ function wrapArgs(fn) {
     try {
       await fn(...args);
     } catch (err) {
+      if (isSquadExit(err)) {
+        if (err.message.trim()) info(err.message);
+        process.exit(err.exitCode);
+      }
       renderError(err);
       process.exit(1);
     }