@mccune1224/pi-pstack 0.1.0 → 0.2.0

package/extensions/index.ts

@@ -1,17 +1,48 @@
-import { CONFIG_DIR_NAME, type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import {
+  CONFIG_DIR_NAME,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { analyzeSkillBudget, readSkillSources } from "./skill-budget.ts";
+import {
+  POTETO_COMPACT_INSTRUCTIONS,
+  loadConversationHelpers,
+  runPotetoCompaction,
+} from "./compaction.ts";
+import {
+  type DoctorCheck,
+  checkAgentFrontmatter,
+  checkModelMap,
+  renderReport,
+} from "./doctor.ts";
+import {
+  guardAdvice,
+  guardLevel,
+  isStronger,
+  meterLine,
+  type GuardLevel,
+} from "./context-guard.ts";
+import {
+  BUDGETS,
   MODE_ENTRY_TYPE,
   POTETO_DIRECTIVE,
   ROLE_KEYS,
   availableModels,
+  applyBudget,
   buildTier,
   lastModeEnabled,
   loadSettings,
   parseArgs,
   parseModelId,
+  resolvedMapping,
   saveSettings,
   settingsPath,
   summaryText,
+  budgetLabel,
+  type BudgetKey,
   type ModeEntry,
   type ModelMap,
   type ModelSpec,
@@ -19,6 +50,22 @@ import {
   type Scope,
 } from "./settings.ts";
 
+const SKILLS_DIR = join(import.meta.dirname, "..", "skills");
+const AGENTS_DIR = join(import.meta.dirname, "..", "agents");
+const DELTAS_PATH = join(import.meta.dirname, "..", "scripts", "pi-deltas.json");
+
+const PACKAGE_AGENTS = ["poteto-agent.md", "comment-sicko.md"];
+
+const PLAYBOOK_COMPLETIONS: Array<{ value: string; label: string }> = (() => {
+  try {
+    return readdirSync(join(SKILLS_DIR, "poteto-mode", "playbooks"))
+      .filter((file) => file.endsWith(".md"))
+      .map((file) => ({ value: file.replace(/\.md$/, ""), label: file.replace(/\.md$/, "") }));
+  } catch {
+    return [];
+  }
+})();
+
 const SETUP_COMPLETIONS = [
   "-l",
   "--local",
@@ -27,6 +74,10 @@ const SETUP_COMPLETIONS = [
   "all-inherit",
   "light",
   "custom",
+  "unlimited",
+  "large",
+  "medium",
+  "small",
   "default",
   "scout",
   "worker",
@@ -101,6 +152,21 @@ function pstackSkillNames(commands: Array<{ name: string; source: string }>): st
     .sort();
 }
 
+function effectiveModelMap(cwd: string): { map: ModelMap; scope: Scope | "none"; path: string } {
+  const userPath = settingsPath(cwd, "user", CONFIG_DIR_NAME);
+  const projectPath = settingsPath(cwd, "project", CONFIG_DIR_NAME);
+  const projectMap = loadSettings(projectPath);
+  if (Object.keys(projectMap).length > 0) {
+    return { map: projectMap, scope: "project", path: projectPath };
+  }
+  const userMap = loadSettings(userPath);
+  return {
+    map: userMap,
+    scope: Object.keys(userMap).length > 0 ? "user" : "none",
+    path: userPath,
+  };
+}
+
 function modelChoices(ctx: ExtensionCommandContext, currentValue: string) {
   return availableModels(ctx.modelRegistry.getAvailable()).map((choice) =>
     choice.id === currentValue ? `${choice.label}  [current]` : choice.label,
@@ -124,19 +190,34 @@ async function announceAndReload(
 
 async function pstackSetupHandler(args: string, ctx: ExtensionCommandContext): Promise<void> {
   const parsed = parseArgs(args);
-  const scopePick =
-    parsed.scope ??
-    (ctx.hasUI
+  let scope: Scope | undefined = parsed.scope;
+  if (!scope) {
+    const label = ctx.hasUI
       ? await ctx.ui.select("Where to save the pstack model map?", [
           "User (~/.pi/agent/settings.json) - recommended",
           "Project (.pi/settings.json) - team shared",
         ])
-      : "user");
-  if (!scopePick) return;
-  const scope: Scope = scopePick.startsWith("Project") ? "project" : "user";
+      : "user";
+    if (!label) return;
+    scope = label.startsWith("Project") ? "project" : "user";
+  }
   const path = settingsPath(ctx.cwd, scope, CONFIG_DIR_NAME);
   const current = loadSettings(path);
 
+  // Fast paths (-l, a tier, or a bare role) skip the budget question, mirroring
+  // upstream's budget-first flow only when the run is fully interactive.
+  const hasFastPath = parsed.tier !== undefined || parsed.role !== undefined;
+  let budget: BudgetKey | undefined = parsed.budget;
+  if (!budget && ctx.hasUI && !hasFastPath) {
+    const pick = await ctx.ui.select(
+      `Reasoning budget for roles without their own level - now ${budgetLabel(current)}`,
+      Object.entries(BUDGETS).map(([key, spec]) => `${key} - ${spec.blurb}`),
+    );
+    if (!pick) return;
+    budget = pick.split(" ")[0] as BudgetKey;
+  }
+  const withBudget = (map: ModelMap): ModelMap => (budget ? applyBudget(map, budget) : map);
+
   if (parsed.role) {
     const currentValue =
       parsed.role === "default"
@@ -157,8 +238,8 @@ async function pstackSetupHandler(args: string, ctx: ExtensionCommandContext): P
         [parsed.role]: { ...current.agentOverrides?.[parsed.role], model: id },
       };
     }
-    saveSettings(path, map);
-    await announceAndReload(ctx, path, map, scope);
+    saveSettings(path, withBudget(map));
+    await announceAndReload(ctx, path, withBudget(map), scope);
     return;
   }
 
@@ -167,7 +248,7 @@ async function pstackSetupHandler(args: string, ctx: ExtensionCommandContext): P
     ctx.ui.notify(summaryText(current, "none", []), "info");
     const pick = await ctx.ui.select("Pick a tier", [
       "All inherit (cheapest) - every role uses the parent model (Recommended)",
-      "Light tier (scout low, oracle fallback, agents high thinking)",
+      "Light tier (scout low thinking, every model still inherits the parent)",
       "Custom per role",
     ]);
     if (!pick) return;
@@ -199,6 +280,7 @@ async function pstackSetupHandler(args: string, ctx: ExtensionCommandContext): P
   } else {
     map = buildTier(tier);
   }
+  map = withBudget(map);
   saveSettings(path, map);
   await announceAndReload(ctx, path, map, scope);
 }
@@ -208,16 +290,13 @@ async function pstackStatusHandler(
   _args: string,
   ctx: ExtensionCommandContext,
 ): Promise<void> {
-  const userPath = settingsPath(ctx.cwd, "user", CONFIG_DIR_NAME);
-  const projectPath = settingsPath(ctx.cwd, "project", CONFIG_DIR_NAME);
-  const userMap = loadSettings(userPath);
-  const projectMap = loadSettings(projectPath);
-  const projectWins = Object.keys(projectMap).length > 0;
-  const effective = projectWins ? projectMap : userMap;
-  const scope = projectWins ? "project" : Object.keys(userMap).length > 0 ? "user" : "none";
+  const effective = effectiveModelMap(ctx.cwd);
+  const budget = analyzeSkillBudget(readSkillSources(SKILLS_DIR));
   const text =
-    summaryText(effective, scope, pstackSkillNames(pi.getCommands())) +
-    `\nsettings: ${projectWins ? projectPath : userPath}`;
+    summaryText(effective.map, effective.scope, pstackSkillNames(pi.getCommands())) +
+    `\nsettings: ${effective.path}` +
+    `\nprompt cost: ${budget.modelInvocable} of ${budget.total} pstack skills exposed to the model,` +
+    ` ${budget.filtered} filtered by disable-model-invocation, ~${budget.estimatedTokens} tokens`;
   const parent =
     ctx.model && typeof ctx.model === "object"
       ? `${(ctx.model as { provider?: string }).provider}/${(ctx.model as { id?: string }).id}`
@@ -252,6 +331,106 @@ function textContent(content: unknown): string | undefined {
   return parts.length > 0 ? parts.join("\n") : undefined;
 }
 
+function upstreamPin(): { ref: string; version: string } | undefined {
+  try {
+    const spec = JSON.parse(readFileSync(DELTAS_PATH, "utf8")) as {
+      upstream?: { ref?: string; version?: string };
+    };
+    if (!spec.upstream?.ref || !spec.upstream.version) return undefined;
+    return { ref: spec.upstream.ref, version: spec.upstream.version };
+  } catch {
+    return undefined;
+  }
+}
+
+function doctorChecks(pi: ExtensionAPI, ctx: ExtensionCommandContext): DoctorCheck[] {
+  const checks: DoctorCheck[] = [];
+
+  for (const scope of ["user", "project"] as const) {
+    const path = settingsPath(ctx.cwd, scope, CONFIG_DIR_NAME);
+    if (!existsSync(path)) {
+      checks.push({ name: `settings (${scope})`, status: "ok", detail: `${path} absent, nothing pinned` });
+      continue;
+    }
+    const problems = checkModelMap(loadSettings(path), ROLE_KEYS);
+    checks.push({
+      name: `settings (${scope})`,
+      status: problems.length > 0 ? "warn" : "ok",
+      detail: problems.length > 0 ? problems.join("; ") : `${path} parses clean`,
+    });
+  }
+
+  for (const file of PACKAGE_AGENTS) {
+    const path = join(AGENTS_DIR, file);
+    try {
+      const problems = checkAgentFrontmatter(file, readFileSync(path, "utf8"));
+      checks.push({
+        name: `agent ${file}`,
+        status: problems.length > 0 ? "fail" : "ok",
+        detail: problems.length > 0 ? problems.join("; ") : "frontmatter registers with pi-subagents",
+      });
+    } catch {
+      checks.push({ name: `agent ${file}`, status: "fail", detail: `${path} is missing` });
+    }
+  }
+
+  try {
+    const playbooks = readdirSync(join(SKILLS_DIR, "poteto-mode", "playbooks")).filter((f) => f.endsWith(".md"));
+    checks.push({
+      name: "skills",
+      status: existsSync(join(SKILLS_DIR, "poteto-mode", "SKILL.md")) ? "ok" : "fail",
+      detail: `poteto-mode present, ${playbooks.length} playbooks vendored under skills/`,
+    });
+  } catch {
+    checks.push({ name: "skills", status: "fail", detail: "skills/poteto-mode is missing" });
+  }
+
+  const toolNames = new Set(pi.getAllTools().map((tool) => tool.name));
+  for (const companion of COMPANIONS) {
+    const present = toolNames.has(companion.tool);
+    checks.push({
+      name: `companion ${companion.tool}`,
+      status: present ? "ok" : companion.required ? "fail" : "warn",
+      detail: present ? "registered" : `absent: install ${companion.pkg}`,
+    });
+  }
+
+  const pin = upstreamPin();
+  checks.push({
+    name: "upstream pin",
+    status: pin ? "ok" : "warn",
+    detail: pin
+      ? `pstack ${pin.version} at ${pin.ref.slice(0, 12)}; npm run verify:sync proves the port matches`
+      : "scripts/pi-deltas.json unreadable",
+  });
+
+  const effective = effectiveModelMap(ctx.cwd);
+  const parent =
+    ctx.model && typeof ctx.model === "object"
+      ? `${(ctx.model as { provider?: string }).provider ?? "?"}/${(ctx.model as { id?: string }).id ?? "?"}`
+      : "unknown";
+  checks.push({
+    name: "session",
+    status: "ok",
+    detail: `parent model ${parent}, map ${effective.scope}, ${budgetLabel(effective.map)}`,
+  });
+
+  return checks;
+}
+
+async function pstackDoctorHandler(
+  pi: ExtensionAPI,
+  _args: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const report = renderReport(doctorChecks(pi, ctx));
+  if (ctx.hasUI) {
+    ctx.ui.notify(report, "info");
+  } else {
+    console.log(report);
+  }
+}
+
 async function broHandler(
   pi: ExtensionAPI,
   _args: string,
@@ -274,6 +453,8 @@ async function broHandler(
 
 export default function (pi: ExtensionAPI): void {
   let potetoMode = false;
+  let guardNotified: GuardLevel = "ok";
+  let conversationHelpers: Awaited<ReturnType<typeof loadConversationHelpers>> | "unavailable" | undefined;
 
   function sessionEntries(ctx: {
     sessionManager: { getBranch?: () => ModeEntry[]; getEntries: () => ModeEntry[] };
@@ -283,20 +464,37 @@ export default function (pi: ExtensionAPI): void {
       : ctx.sessionManager.getEntries();
   }
 
-  function setModeStatus(ctx: import("@earendil-works/pi-coding-agent").ExtensionContext): void {
+  function widgetLines(ctx: ExtensionContext): string[] {
+    const map = effectiveModelMap(ctx.cwd).map;
+    const roles = resolvedMapping(map, ROLE_KEYS);
+    const inherited = roles.filter((role) => role.model === "inherit").length;
+    const summary =
+      inherited === roles.length
+        ? `${inherited} inherit`
+        : `${inherited}/${roles.length} inherit`;
+    return [
+      `pstack: poteto mode on | roles: ${summary}`,
+      meterLine(ctx.getContextUsage(), budgetLabel(map)),
+    ];
+  }
+
+  function renderModeUi(ctx: ExtensionContext): void {
     if (ctx.mode !== "tui") return;
     ctx.ui.setStatus("pstack-mode", potetoMode ? "pstack: poteto mode" : undefined);
+    ctx.ui.setWidget("pstack", potetoMode ? widgetLines(ctx) : undefined, {
+      placement: "belowEditor",
+    });
   }
 
-  function persistMode(enabled: boolean, ctx?: import("@earendil-works/pi-coding-agent").ExtensionContext): void {
+  function persistMode(enabled: boolean, ctx?: ExtensionContext): void {
     potetoMode = enabled;
     pi.appendEntry(MODE_ENTRY_TYPE, { enabled });
-    if (ctx) setModeStatus(ctx);
+    if (ctx) renderModeUi(ctx);
   }
 
   pi.on("session_start", async (_event, ctx) => {
     potetoMode = lastModeEnabled(sessionEntries(ctx));
-    setModeStatus(ctx);
+    renderModeUi(ctx);
     const toolNames = new Set(pi.getAllTools().map((tool) => tool.name));
     const missing = COMPANIONS.filter((companion) => !toolNames.has(companion.tool));
     if (missing.length === 0) return;
@@ -319,6 +517,62 @@ export default function (pi: ExtensionAPI): void {
     return { systemPrompt: `${event.systemPrompt}\n\n${POTETO_DIRECTIVE}` };
   });
 
+  // Context guard: meter the context window while the mode is on, warn as it
+  // fills, and offer a one-key poteto compaction when it is nearly full.
+  pi.on("agent_end", async (_event, ctx) => {
+    if (!potetoMode) return;
+    renderModeUi(ctx);
+    const percent = ctx.getContextUsage()?.percent ?? null;
+    const level = guardLevel(percent);
+    if (level === "ok") {
+      guardNotified = "ok";
+      return;
+    }
+    if (!isStronger(level, guardNotified)) return;
+    guardNotified = level;
+    const advice = guardAdvice(level, percent);
+    if (level === "compact" && ctx.hasUI) {
+      const accepted = await ctx.ui.confirm("Context nearly full", `${advice}\n\nCompact now with the poteto summary?`);
+      if (accepted) ctx.compact({ customInstructions: POTETO_COMPACT_INSTRUCTIONS });
+      return;
+    }
+    ctx.ui.notify(advice, "warning");
+  });
+
+  pi.on("session_compact", (_event, ctx) => {
+    guardNotified = "ok";
+    renderModeUi(ctx);
+  });
+
+  // Poteto compaction: while the mode is on, own the summary shape. Any
+  // failure falls back to Pi's default compaction.
+  pi.on("session_before_compact", async (event, ctx) => {
+    if (!potetoMode) return;
+    if (conversationHelpers === undefined) {
+      conversationHelpers = (await loadConversationHelpers()) ?? "unavailable";
+    }
+    if (conversationHelpers === "unavailable") return;
+    const helpers = conversationHelpers;
+    const result = await runPotetoCompaction(
+      event.preparation,
+      event.customInstructions,
+      event.signal,
+      {
+        model: ctx.model,
+        complete: (model, context, options) =>
+          ctx.modelRegistry.complete(
+            model as Parameters<typeof ctx.modelRegistry.complete>[0],
+            context as Parameters<typeof ctx.modelRegistry.complete>[1],
+            options as Parameters<typeof ctx.modelRegistry.complete>[2],
+          ),
+        serialize: helpers.serialize,
+        notify: (message, level) => ctx.ui.notify(message, level ?? "warning"),
+      },
+    );
+    if (!result) return;
+    return { compaction: result };
+  });
+
   const setupCommand = {
     description: "Configure pstack subagent models for Pi via TUI pickers (fast paths: -l scope, inherit|light|custom tier, or one role). Writes only the subagents.* keys; default is all-inherit.",
     getArgumentCompletions: completions,
@@ -326,11 +580,16 @@ export default function (pi: ExtensionAPI): void {
   };
   pi.registerCommand("pstack-setup", setupCommand);
   pi.registerCommand("poteto-mode", {
-    description: "Enable or disable sticky Poteto Mode. Usage: /poteto-mode [task] | /poteto-mode off",
+    description: "Enable or disable sticky Poteto Mode. Usage: /poteto-mode [task or playbook] | /poteto-mode off",
     getArgumentCompletions: (prefix: string) => {
       const token = prefix.trim().toLowerCase();
-      if (!token || "off".startsWith(token)) return [{ value: "off", label: "off" }];
-      return null;
+      if (token.includes(" ")) return null;
+      if (!token) return [{ value: "off", label: "off" }, ...PLAYBOOK_COMPLETIONS.slice(0, 20)];
+      const items = [
+        ...("off".startsWith(token) ? [{ value: "off", label: "off" }] : []),
+        ...PLAYBOOK_COMPLETIONS.filter((item) => item.value.startsWith(token)),
+      ];
+      return items.length > 0 ? items : null;
     },
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const raw = args.trim();
@@ -351,6 +610,10 @@ export default function (pi: ExtensionAPI): void {
     description: "Show the effective pstack model map (resolved through defaults), the winning settings file, and loaded pstack skills.",
     handler: (_args, ctx) => pstackStatusHandler(pi, _args, ctx),
   });
+  pi.registerCommand("pstack-doctor", {
+    description: "Check the pstack install: settings validity, package agents, vendored playbooks, companion tools, and the upstream pin.",
+    handler: (_args, ctx) => pstackDoctorHandler(pi, _args, ctx),
+  });
   pi.registerCommand("bro", {
     description: "Restate the last assistant reply in plain human language, no jargon.",
     handler: (_args, ctx) => broHandler(pi, _args, ctx),

package/extensions/settings.test.ts

@@ -5,6 +5,9 @@ import { join } from "node:path";
 import { test } from "node:test";
 import {
   POTETO_DIRECTIVE,
+  applyBudget,
+  budgetLabel,
+  budgetOf,
   buildTier,
   lastModeEnabled,
   loadSettings,
@@ -12,16 +15,53 @@ import {
   parseModelId,
   resolvedMapping,
   saveSettings,
+  summaryText,
   type ModeEntry,
 } from "./settings.ts";
 
 test("parseArgs maps scope, tier, and role tokens", () => {
-  assert.deepEqual(parseArgs("-l inherit"), { scope: "project", tier: "all-inherit", role: undefined });
-  assert.deepEqual(parseArgs("scout"), { scope: undefined, tier: undefined, role: "scout" });
-  assert.deepEqual(parseArgs(""), { scope: undefined, tier: undefined, role: undefined });
-  assert.deepEqual(parseArgs("--local light"), { scope: "project", tier: "light", role: undefined });
-  assert.deepEqual(parseArgs("custom poteto-agent"), { scope: undefined, tier: "custom", role: "poteto-agent" });
-  assert.deepEqual(parseArgs("nonsense-token"), { scope: undefined, tier: undefined, role: undefined });
+  assert.deepEqual(parseArgs("-l inherit"), { scope: "project", tier: "all-inherit", role: undefined, budget: undefined });
+  assert.deepEqual(parseArgs("scout"), { scope: undefined, tier: undefined, role: "scout", budget: undefined });
+  assert.deepEqual(parseArgs(""), { scope: undefined, tier: undefined, role: undefined, budget: undefined });
+  assert.deepEqual(parseArgs("--local light"), { scope: "project", tier: "light", role: undefined, budget: undefined });
+  assert.deepEqual(parseArgs("custom poteto-agent"), { scope: undefined, tier: "custom", role: "poteto-agent", budget: undefined });
+  assert.deepEqual(parseArgs("nonsense-token"), { scope: undefined, tier: undefined, role: undefined, budget: undefined });
+});
+
+test("parseArgs maps budget tokens, alone and combined", () => {
+  assert.equal(parseArgs("small").budget, "small");
+  assert.equal(parseArgs("unlimited").budget, "unlimited");
+  assert.deepEqual(parseArgs("-l large"), { scope: "project", tier: undefined, role: undefined, budget: "large" });
+  assert.equal(parseArgs("medium scout").role, "scout");
+  assert.equal(parseArgs("medium scout").budget, "medium");
+});
+
+test("applyBudget sets and clears defaultThinking without mutating its input", () => {
+  const base = { defaultModel: "inherit", defaultThinking: "high" as const };
+  const raised = applyBudget(base, "large");
+  assert.equal(raised.defaultThinking, "xhigh");
+  assert.equal(base.defaultThinking, "high", "input map is untouched");
+  const cleared = applyBudget(base, "unlimited");
+  assert.equal(cleared.defaultThinking, undefined);
+  assert.ok("defaultThinking" in cleared === false, "unlimited removes the key instead of writing null");
+  const lowered = applyBudget({}, "small");
+  assert.equal(lowered.defaultThinking, "medium");
+});
+
+test("budgetOf reads the recorded budget back off the map", () => {
+  assert.equal(budgetOf({}), "unlimited");
+  assert.equal(budgetOf({ defaultThinking: "xhigh" }), "large");
+  assert.equal(budgetOf({ defaultThinking: "max" }), "large");
+  assert.equal(budgetOf({ defaultThinking: "high" }), "medium");
+  assert.equal(budgetOf({ defaultThinking: "medium" }), "small");
+  assert.equal(budgetOf({ defaultThinking: "low" }), "unlimited", "a hand-written level below the ladder reads as unlimited");
+  assert.equal(budgetLabel({ defaultThinking: "high" }), "medium (high reasoning)");
+});
+
+test("summaryText names the budget on the header line", () => {
+  const text = summaryText(applyBudget(buildTier("all-inherit"), "small"), "user", []);
+  assert.ok(text.includes("budget: small"), text);
+  assert.ok(text.startsWith("pstack models (user), budget: small"), text);
 });
 
 test("parseModelId strips labels to ids", () => {
@@ -37,25 +77,40 @@ test("buildTier is pure and idempotent", () => {
   assert.equal(JSON.stringify(buildTier("all-inherit")), JSON.stringify(all));
 
   const light = buildTier("light");
-  assert.equal(light.defaultModel, "opencode-go/hy3");
   assert.equal(light.defaultThinking, "high");
-  assert.equal(light.agentOverrides?.scout?.thinking, "low");
-  assert.deepEqual(light.agentOverrides?.oracle?.fallbackModels, ["opencode-go/deepseek-v4-flash"]);
-  assert.equal(light.agentOverrides?.["poteto-agent"]?.thinking, "high");
+  assert.deepEqual(light.agentOverrides, {
+    scout: { thinking: "low" },
+    oracle: { thinking: "high" },
+    "poteto-agent": { thinking: "high" },
+    "comment-sicko": { thinking: "high" },
+  });
+  assert.equal(JSON.stringify(buildTier("light")), JSON.stringify(light));
+});
+
+test("light tier writes no model slug other than inherit", () => {
+  const json = JSON.stringify(buildTier("light"));
+  assert.deepEqual(json.match(/[a-z0-9-]+\/[a-z0-9.-]+/gi), null, "no provider/model slug is pinned");
+  assert.ok(json.includes('"defaultModel":"inherit"'), "every role inherits the parent model");
 });
 
 test("resolvedMapping falls back default -> inherit and includes extras", () => {
   const light = buildTier("light");
   const mapped = resolvedMapping(light, ["default", "scout", "oracle", "poteto-agent"]);
-  assert.deepEqual(mapped.map((row) => [row.role, row.model]), [
-    ["default", "opencode-go/hy3"],
-    ["scout", "inherit"],
-    ["oracle", "inherit"],
-    ["poteto-agent", "inherit"],
+  assert.deepEqual(mapped, [
+    { role: "default", model: "inherit", extra: undefined },
+    { role: "scout", model: "inherit", extra: "thinking:low" },
+    { role: "oracle", model: "inherit", extra: "thinking:high" },
+    { role: "poteto-agent", model: "inherit", extra: "thinking:high" },
   ]);
-  assert.ok(mapped.find((row) => row.role === "oracle")?.extra?.includes("fallback:"));
   const empty = resolvedMapping({}, ["default", "worker"]);
   assert.deepEqual(empty.map((row) => row.model), ["inherit", "inherit"]);
+  const handWrittenFallback = resolvedMapping(
+    { agentOverrides: { oracle: { model: "inherit", fallbackModels: ["demo/one"] } } },
+    ["oracle"],
+  );
+  assert.deepEqual(handWrittenFallback, [
+    { role: "oracle", model: "inherit", extra: "fallback:demo/one" },
+  ]);
 });
 
 test("saveSettings merges into existing settings, never clobbers", () => {

package/extensions/settings.ts

@@ -36,6 +36,52 @@ export interface ModelMap {
 export type Tier = "all-inherit" | "light" | "custom";
 export type Scope = "user" | "project";
 
+export type BudgetKey = "unlimited" | "large" | "medium" | "small";
+
+export interface BudgetSpec {
+  thinking: ThinkingLevel | undefined;
+  blurb: string;
+}
+
+export const BUDGETS: Record<BudgetKey, BudgetSpec> = {
+  unlimited: { thinking: undefined, blurb: "keep each role's own setting" },
+  large: { thinking: "xhigh", blurb: "xhigh reasoning" },
+  medium: { thinking: "high", blurb: "high reasoning" },
+  small: { thinking: "medium", blurb: "medium reasoning" },
+};
+
+const BUDGET_KEYS = new Set<string>(Object.keys(BUDGETS));
+
+export function applyBudget(map: ModelMap, budget: BudgetKey): ModelMap {
+  const next: ModelMap = { ...map };
+  const thinking = BUDGETS[budget].thinking;
+  if (thinking) {
+    next.defaultThinking = thinking;
+  } else {
+    delete next.defaultThinking;
+  }
+  return next;
+}
+
+export function budgetOf(map: ModelMap): BudgetKey {
+  switch (map.defaultThinking) {
+    case "xhigh":
+    case "max":
+      return "large";
+    case "high":
+      return "medium";
+    case "medium":
+      return "small";
+    default:
+      return "unlimited";
+  }
+}
+
+export function budgetLabel(map: ModelMap): string {
+  const key = budgetOf(map);
+  return `${key} (${BUDGETS[key].blurb})`;
+}
+
 export const ROLE_KEYS: RoleKey[] = [
   "default",
   "scout",
@@ -74,13 +120,14 @@ export interface ParsedArgs {
   scope: Scope | undefined;
   tier?: Tier;
   role?: RoleKey;
+  budget?: BudgetKey;
 }
 
 const ROLE_SET = new Set<string>(ROLE_KEYS);
 
 export function parseArgs(raw: string): ParsedArgs {
   const tokens = raw.trim().split(/\s+/).filter(Boolean);
-  const out: ParsedArgs = { scope: undefined, tier: undefined, role: undefined };
+  const out: ParsedArgs = { scope: undefined, tier: undefined, role: undefined, budget: undefined };
   for (const token of tokens) {
     if (token === "-l" || token === "--local" || token === "local") {
       out.scope = "project";
@@ -90,6 +137,8 @@ export function parseArgs(raw: string): ParsedArgs {
       out.tier = "light";
     } else if (token === "custom") {
       out.tier = "custom";
+    } else if (BUDGET_KEYS.has(token)) {
+      out.budget = token as BudgetKey;
     } else if (ROLE_SET.has(token)) {
       out.role = token as RoleKey;
     }
@@ -183,15 +232,13 @@ export function buildTier(tier: "all-inherit" | "light"): ModelMap {
     };
   }
   return {
-    defaultModel: "opencode-go/hy3",
+    defaultModel: "inherit",
     defaultThinking: "high",
     agentOverrides: {
-      scout: { model: "inherit", thinking: "low" },
-      worker: { model: "inherit" },
-      reviewer: { model: "inherit" },
-      oracle: { model: "inherit", fallbackModels: ["opencode-go/deepseek-v4-flash"] },
-      "poteto-agent": { model: "inherit", thinking: "high" },
-      "comment-sicko": { model: "inherit", thinking: "high" },
+      scout: { thinking: "low" },
+      oracle: { thinking: "high" },
+      "poteto-agent": { thinking: "high" },
+      "comment-sicko": { thinking: "high" },
     },
   };
 }
@@ -226,7 +273,8 @@ export function summaryText(
   loadedPstackSkills: string[],
 ): string {
   const scopeName = scope === "project" ? "project" : scope === "user" ? "user" : "none saved";
-  const lines = [`pstack models (${scopeName}):`];
+  const budget = budgetOf(map);
+  const lines = [`pstack models (${scopeName}), budget: ${budget} (${BUDGETS[budget].blurb}):`];
   for (const role of resolvedMapping(map, ROLE_KEYS)) {
     lines.push(
       `  ${role.role} -> ${role.model}${role.extra ? ` (${role.extra})` : ""}`,