squad-kit 0.3.0 → 0.4.0

package/dist/cli.js

@@ -169,6 +169,19 @@ 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";
@@ -276,6 +289,18 @@ var DEFAULT_CONFIG = {
   planner: void 0
 };
 var FORBIDDEN_KEYS = ["apikey", "api_key", "token", "secret", "credential", "credentials"];
+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)) {
@@ -305,7 +330,8 @@ function mergePlanner(base, override) {
     },
     cache: {
       enabled: override.cache?.enabled ?? base?.cache?.enabled ?? true
-    }
+    },
+    maxOutputTokens: clampPlannerMaxOut(override.maxOutputTokens ?? base?.maxOutputTokens)
   };
   if (merged.modelOverride) {
     const pruned = Object.fromEntries(
@@ -584,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";
@@ -856,7 +885,8 @@ function newPlannerBlock(provider) {
       maxContextBytes: 5e4,
       maxDurationSeconds: 180
     },
-    cache: { enabled: true }
+    cache: { enabled: true },
+    maxOutputTokens: DEFAULT_PLANNER_MAX_OUTPUT_TOKENS
   };
 }
 function mergePlannerKeyIntoSecrets(base, provider, key) {
@@ -1217,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"],
@@ -1340,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,
@@ -1772,7 +1804,9 @@ async function runInit(opts) {
           maxFileReads: 25,
           maxContextBytes: 5e4,
           maxDurationSeconds: 180
-        }
+        },
+        cache: { enabled: true },
+        maxOutputTokens: DEFAULT_PLANNER_MAX_OUTPUT_TOKENS
       };
     }
   } else {
@@ -1798,7 +1832,9 @@ async function runInit(opts) {
           maxFileReads: 25,
           maxContextBytes: 5e4,
           maxDurationSeconds: 180
-        }
+        },
+        cache: { enabled: true },
+        maxOutputTokens: DEFAULT_PLANNER_MAX_OUTPUT_TOKENS
       };
     }
   }
@@ -1969,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());
@@ -1989,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 {};
   }
@@ -2143,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;
@@ -2158,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);
@@ -2242,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.*
@@ -2965,6 +3058,10 @@ function prefixOf(provider, req) {
   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));
@@ -2986,18 +3083,83 @@ function buildPlannerRunStats(budget, turns, runStartedAt) {
     durationMs: Date.now() - runStartedAt
   };
 }
+function readBudgetishError(result) {
+  return result.isError && (/budget/i.test(result.content) || /max file reads/i.test(result.content));
+}
+function extendAllSessionLimits(input5, maxIter, maxOut, baseMaxIter, baseMaxOut) {
+  input5.budget.extendSession();
+  maxIter.current += baseMaxIter;
+  maxOut.current += baseMaxOut;
+}
 async function runPlanner(input5) {
   const runStartedAt = Date.now();
-  const maxIter = input5.maxIterations ?? 40;
+  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;
-  while (iterations < maxIter) {
+  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,
@@ -3008,6 +3170,24 @@ async function runPlanner(input5) {
       };
     }
     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,
@@ -3023,7 +3203,7 @@ async function runPlanner(input5) {
       tools: [READ_FILE_TOOL],
       turns,
       apiKey: input5.apiKey,
-      maxOutputTokens: 8192,
+      maxOutputTokens: maxOut.current,
       cacheEnabled: input5.cacheEnabled ?? true
     };
     if (process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test" && prevRequestPrefix !== void 0) {
@@ -3067,13 +3247,34 @@ async function runPlanner(input5) {
       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)
+        stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt),
+        incompleteKind: "max_output_tokens"
       };
     }
     if (response.stopReason === "end_turn" || !response.toolCalls?.length) {
@@ -3093,17 +3294,47 @@ async function runPlanner(input5) {
       toolCalls: response.toolCalls
     });
     const toolResults = [];
-    for (const tc of response.toolCalls) {
+    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;
-      const result = readFileTool(input5.root, input5.budget, tc.input);
+      let result = readFileTool(input5.root, input5.budget, tc.input);
       const after = input5.budget.snapshot().bytes;
       input5.onToolCall?.(tc, after - before, after);
-      if (result.isError && (/budget/i.test(result.content) || /max file reads/i.test(result.content))) {
-        budgetExhausted = true;
+      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 });
     }
@@ -3115,14 +3346,6 @@ async function runPlanner(input5) {
       });
     }
   }
-  return {
-    planText: accumulatedText,
-    budgetExhausted,
-    timedOut: false,
-    finishedNormally: false,
-    iterations,
-    stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
-  };
 }
 function firstByteDiff(a, b) {
   const n = Math.min(a.length, b.length);
@@ -3151,6 +3374,84 @@ function composePlannerError(providerName, response, retriedRateLimit, retrySkip
   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) {
@@ -3167,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, 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 };
   }
@@ -3194,11 +3512,11 @@ var Budget = class {
     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 {
@@ -3337,10 +3655,19 @@ function formatSequence(n) {
 }
 
 // src/planner/writer.ts
+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;
@@ -3351,10 +3678,7 @@ function writePlanFile(input5) {
     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 = `${input5.metadataHeader.trimEnd()}
@@ -3362,12 +3686,45 @@ function writePlanFile(input5) {
 ${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, 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()}
+
+${input5.planBodyMarkdown.trimStart()}
+`;
+  fs20.writeFileSync(targetPath, body, "utf8");
+  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;
@@ -3375,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
 
@@ -3423,7 +3781,15 @@ 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
@@ -3561,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(
@@ -3586,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(
@@ -3602,6 +3984,18 @@ async function emitViaApi(story, paths, config2, _opts) {
   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,
@@ -3610,7 +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(
@@ -3636,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,
@@ -3644,14 +4041,16 @@ 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, {
@@ -3662,9 +4061,10 @@ async function emitViaApi(story, paths, config2, _opts) {
     });
   } catch {
   }
+  const relPlan = path15.relative(paths.root, planFile);
   blank();
-  summaryBox(" plan generated ", [
-    { key: "file", value: path15.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` },
@@ -3673,13 +4073,22 @@ async function emitViaApi(story, paths, config2, _opts) {
       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 ${path15.basename(planFile)}`);
@@ -3859,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]);
 }
@@ -5344,7 +5753,7 @@ async function runRmPlan(planPathOrSequence, opts = {}) {
 
 // src/cli.ts
 var program = new Command();
-program.name("squad").description("Plan once, execute cheap. A 3-step SDD workflow CLI.").version("0.3.0");
+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)"
@@ -5398,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);
 });
@@ -5406,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);
     }
@@ -5416,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);
     }