pi-magi-theme 0.2.4 → 0.3.1

package/README.md

@@ -36,14 +36,18 @@ Clone the repo and point pi at it instead (edits in the repo are live on the nex
 
 | Command | What it does |
 |---------|--------------|
-| `/magi <question>` | the council answers a question (recent conversation as context) |
-| `/magi review [focus]` | the council reviews your pending changes (`git diff HEAD` plus untracked file names) before you commit |
+| `/magi council <question>` | the council answers a question (recent conversation as context) |
+| `/magi council review [focus]` | the council reviews your pending changes (`git diff HEAD` plus untracked file names) before you commit |
 | `/magi config` | pick a model for each MAGI |
 | `/magi mecha` | MECHA SELECT: pick the llama-swap model to activate, each shown as a mecha head lit by its real state |
-| `/magi-ui compact` | toggle the compact side panel (basic info and animations only); remembered across sessions |
-| `/magi-ui status` | llama-swap report from its last 100 requests: speed, tokens, cache hits, MTP draft acceptance, durations, errors per model |
-| `/magi-ui config` | set the electricity price per kWh and the currency (EUR or USD) for the COST row |
-| `/magi-ui panel` · `on` · `off` | hide/show the side panel, enable/disable the whole chrome |
+| `/magi compact` | toggle the compact side panel (basic info and animations only); remembered across sessions |
+| `/magi status` | llama-swap report from its last 100 requests: speed, tokens, cache hits, MTP draft acceptance, durations, errors per model |
+| `/magi cost` | set the electricity price per kWh and the currency (EUR or USD) for the COST row |
+| `/magi panel` · `on` · `off` | hide/show the side panel, enable/disable the whole chrome |
+| `/magi hygiene` · `on` · `off` · `step <tokens>` · `<turns> <results>` | show how much context the hygiene pruned; enable/disable it; how many prunable tokens make a pruning step (e.g. `step 40k`, default 15k); how many recent turns keep their thinking and how many tool results stay whole (e.g. `3 5`) |
+| `/magi budget` · `auto` · `off` · `reset` · `message` · `<planning> <acting>` | show the thinking budget of the current model; learn it per model (default); leave it to llama-server; forget what was learned for this model; turn the closing message off/on; or fix it (e.g. `16k 4k`) |
+
+Everything lives under `/magi`: type `/magi ` (with the space) to see every option with a short description; keep typing to narrow it down, Tab or Enter to pick one. Anything that is not an option is a question for the council.
 
 ## Lore ↔ function
 
@@ -84,9 +88,39 @@ pi install npm:pi-smart-compact
 
 It extracts files, errors, decisions and open loops locally (no LLM calls), then synthesizes and verifies the summary. Point its `summaryModel` at a local model to keep compaction free. When it is installed, the sixth seal suggests `/smart-compact`, the seals name it while they break (`✶ BREAKING THE SEALS · smart-compact · 4s`) and the seventh seal reports who actually produced the summary: `smart-compact`, or `pi native` if it fell back to pi's own compactor.
 
+## Local models: context hygiene, thinking budget, loop guard, MAGI.md
+
+Local models run out of context on long tasks well before they run out of work. They also tend to think for minutes between two tool calls and to repeat the same command when stuck. MAGI works on all three, automatically (the thinking budget for llama-swap models, the rest for any model):
+
+- **Context hygiene: the model's memory stays lean.** *Problem:* every file the agent reads and every long reasoning stays in the conversation, until the model's context is full and the task falls apart. *What MAGI does:* before each request it replaces old reasoning, old tool outputs and old file writes with a one-line note (`<<pruned by MAGI…>>`). Only what the model sees is trimmed: your saved session stays complete. The latest 3 turns keep their reasoning and the latest 5 tool outputs stay whole. On two real sessions it brought 104k and 119k tokens down to ~64k and ~47k.
+- **Thinking budget: no more ten-minute thinks.** *Problem:* a local model can reason for thousands of tokens before a simple step, and at 10 tokens/s that is minutes of waiting. *What MAGI does:* it gives the model a maximum length of thinking on every request: larger right after you write (planning), smaller between tool calls (acting). When the limit is reached the model is stopped mid-thought, says *"Time is up. I will take the smallest safe next step…"* and acts. The limit adapts to each model on its own. The side panel counts these cuts (`HYGIENE -18.2k ✂2`).
+- **Loop guard: no endless retries.** *Problem:* a stuck model runs the same command again and again. *What MAGI does:* the third identical tool call in a row is blocked, with a message asking the model to try something else.
+- **MAGI.md: house rules for the model.** *Problem:* local models repeat the same mistakes: reading whole files, inventing paths, claiming success without checking. *What MAGI does:* it creates `MAGI.md` in your project on the first start (never overwritten) and adds it to the model's instructions on every run: short rules against these mistakes, plus the habit of keeping the task plan in `PLAN.md` and findings in `NOTES.md`, so nothing important is lost when old context is trimmed. Edit it per project; delete it to get the defaults back.
+
+Nothing needs setting up in llama-swap. The defaults suit most tasks; two adjustments are worth knowing:
+
+- **Long tasks: `/magi hygiene step 40k`.** Each time the hygiene trims, the server has to re-read part of the conversation, and on some models (see *Hybrid models* below) almost all of it, which can take a few minutes. A step of 40k trims less often: on a real session it cut the re-reading from ~6 minutes to ~1.
+- **A model that really needs to think longer: `/magi budget <planning> <acting>`**, e.g. `/magi budget 16k 8k`. Frequent ✂ cuts in the side panel are the sign.
+
+### How it works
+
+For the curious, and for tuning.
+
+**Hygiene.** Trimming happens in steps, not on every request: the conversation up to a mark is trimmed, and the mark only moves forward once ~15k more tokens (the step) could be trimmed. Between steps the conversation only grows at the end, so llama.cpp reuses what it already processed (its KV cache) and only reads the new messages. Each step changes the conversation from the first newly trimmed message on, and the server re-reads from there: that is why steps are large and rare. Old tool outputs are replaced, not summarized: [simple observation masking matches LLM summarization at half the cost](https://arxiv.org/abs/2508.21433).
+
+**Hybrid models.** Some models (e.g. Qwen3.8 Flash Next; dense or MoE does not matter) mix a few classic attention layers with recurrent ones, which squeeze the whole conversation into a fixed-size state instead of keeping each token. The server cannot rewind that state to an arbitrary point: it can only restore a saved copy (a checkpoint) and re-read from there, and the only copy before the trimmed part is usually the end of the system prompt. So on these models each step re-reads almost the whole prompt. With 10k-token thoughts and 4k-token file reads, a 15k step is crossed every 2–3 turns: on a real 70k-token session that was 3 re-reads in 6 requests (~6 min at 185 tokens/s); with a 40k step, 1 re-read (~1 min) for a prompt at most 6k larger. A model is hybrid if its llama-server log shows `restored context checkpoint` lines.
+
+**Thinking budget.** MAGI sends the limit with every request (`thinking_budget_tokens`), and llama.cpp applies it. It learns per model and per phase: 1.5 × the 95th percentile of the model's last 30 thinking lengths, rounded up to 1k. A cut is recorded as 1/1.5 of the limit it hit, so cuts never raise the limit: a model that often runs away is held, not chased. Replies that end close under the limit raise it; a model that thinks little lowers it. Limits: planning 4k–32k, acting 2k–4k (past ~4k between two tool calls it is overthinking). Until a model has 10 replies in a phase it uses 16k / 4k.
+
+When the limit is reached llama.cpp does not abort the reply: it inserts the closing sentence and the end-of-thinking tag, and the model goes on to act. MAGI sends that sentence with every request too (`reasoning_budget_message`; `/magi budget message` turns it off and on). `MAGI.md` tells the model what to do after a cut (one small verifiable step, the open plan into `PLAN.md`), and the next turn gets a fresh budget.
+
+**llama-server versions.** The per-request limit works whenever llama-server was started without `--reasoning-budget`, which is the default. If it was started with one, the server's limit wins: MAGI notices the model thinking well past its own limit and `/magi budget` says so. A llama-server too old for the closing sentence ends the thinking silently, and MAGI detects the cut by its length.
+
+**Loop guard details.** A tool call counts as identical when both the tool and its arguments match. A file write or edit that copies a `<<pruned by MAGI…>>` note into a file is blocked too.
+
 ## The council
 
-`/magi <question>` asks three models in parallel, each with its own nature, then shows the votes and a majority verdict:
+`/magi council <question>` asks three models in parallel, each with its own nature, then shows the votes and a majority verdict:
 
 | Unit | Nature | Looks at |
 |------|--------|----------|
@@ -96,18 +130,20 @@ It extracts files, errors, decisions and open loops locally (no LLM calls), then
 
 Each nature is a lens, not a specialty, so the council answers any question, not only software ones. Every MAGI first answers the question, then judges it through its lens, naming concrete tools, numbers and scenarios from your question instead of generic advice. Votes: **APPROVE** = go ahead or clear recommendation; **CONDITIONAL** = only if the named conditions hold, or when information is missing (it says what it needs); **REJECT** = a concrete problem, with what to do instead. A MAGI never rejects because a topic is outside its nature. Answers come back in the language of your question.
 
-`/magi <question>` gives the MAGI the recent conversation as context; `/magi review` gives them the pending diff (truncated at 24k characters). Full opinions are added to the chat (not sent to the agent), and the last verdict stays under the MAGI in the side panel.
+`/magi council <question>` gives the MAGI the recent conversation as context; `/magi council review` gives them the pending diff (truncated at 24k characters). Full opinions are added to the chat (not sent to the agent), and the last verdict stays under the MAGI in the side panel.
 
 ## Configuration
 
-`~/.pi/agent/magi.json` (written by `/magi config`, `/magi-ui compact` and `/magi-ui config`, editable by hand):
+`~/.pi/agent/magi.json` (written by `/magi config`, `/magi compact` and `/magi cost`, editable by hand):
 
 ```json
 {
   "MELCHIOR": { "model": "llama-swap/Qwen3.8 27B Q4_K_M - Thinking", "thinking": "low" },
   "ui": { "compact": false, "kwhPrice": 0.30, "currency": "EUR" },
   "loads": { "qwen3.8-27b": 41200 },
-  "totalWh": 1843.2
+  "totalWh": 1843.2,
+  "hygiene": { "enabled": true, "keepThinkingTurns": 3, "keepToolResults": 5, "stepTokens": 15000, "minPruneChars": 600 },
+  "thinkingBudget": { "mode": "auto", "planning": 16384, "acting": 4096, "message": true, "learned": { "qwen3.8-27b": { "acting": [812, 430, 2211] } } }
 }
 ```
 
@@ -115,6 +151,7 @@ Each nature is a lens, not a specialty, so the council answers any question, not
 - `ui.compact`: start with the compact side panel;
 - `ui.kwhPrice` and `ui.currency` (`EUR` or `USD`): the COST row multiplies the GPU energy by this price, showing the running total of every session with the current one in brackets;
 - `totalWh`: written by the theme, GPU energy summed over every session (delete the key to reset the COST total);
+- `hygiene` and `thinkingBudget` are set with `/magi hygiene` and `/magi budget` (`hygiene.minPruneChars` by hand only); `thinkingBudget.message` sends the closing message with every request (default `true`); `thinkingBudget.learned` is written by the theme (recent thinking lengths per model and phase);
 - `loads`: written by the theme, how long each llama-swap model took to load last time (paces the angel attack; 60s when unknown).
 
 ## Release
@@ -129,6 +166,8 @@ No token: npmjs is configured to trust this repository's `publish.yml` (npm trus
 
 ## llama-swap
 
+**Thinking levels.** [pi-llama-swap](https://www.npmjs.com/package/@danielmeneses/pi-llama-swap) registers every model with reasoning off, so `/thinking` only offers `off`. At session start MAGI reads the reasoning levels llama-swap publishes in `/v1/models` (`meta.llamaswap.reasoning.levels`) and re-registers those models with thinking on: `/thinking` then offers exactly those levels, sent as `chat_template_kwargs` (`enable_thinking`, `reasoning_effort`). Aliases (e.g. the Instruct twin of a Thinking model) stay off, and image input follows `architecture.input_modalities`. A new or renamed model works without a `modelOverrides` entry in `models.json`; entries you keep there still apply on top (e.g. `samplingParams`). The starting level is pi's usual one for a model switch: the level saved for that model (`Ctrl+S` in `/thinking`), else `defaultThinkingLevel`.
+
 When the session model uses the `llama-swap` provider, the side panel:
 
 - loads nothing at startup: a new session opens MECHA SELECT, a resumed one shows whether its model is already in VRAM;

package/extensions/magi/index.ts

@@ -17,22 +17,41 @@
  *  - while a model loads an angel attacks the MAGI: red spreads through BALTHASAR, MELCHIOR and CASPAR at the pace of
  *    the model's last load, a corner of CASPAR holds out blinking; once loaded, blue takes the MAGI back from that corner
  *  - llama-swap telemetry: VRAM, GPU load/temp/power, energy used, RAM, server-side tok/s, prompt tok/s, cache hits
- *  - /magi config → assign a model to each MAGI; /magi-ui compact|status → smaller panel, llama-swap report
+ *  - /magi config → assign a model to each MAGI; /magi compact|status → smaller panel, llama-swap report
  *
  * Fan art: the MAGI and their screen come from Neon Genesis Evangelion, all rights reserved to khara, Inc.
  * Use with the theme ../../themes/magi.json
  */
 
 import { execFile } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import type { AssistantMessage, Model } from "@earendil-works/pi-ai";
 import { completeSimple } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import type { Component, OverlayHandle, TUI } from "@earendil-works/pi-tui";
 import { HStack, matchesKey, sliceByColumn, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import {
+	BUDGET_DEFAULTS,
+	BUDGET_MESSAGE,
+	BUDGET_WINDOW,
+	HYGIENE_DEFAULTS,
+	MAGI_MD,
+	PRUNED_MARK,
+	learnedBudget,
+	budgetSample,
+	pruneContext,
+	requestPhase,
+	thinkingTokens,
+	budgetVerdict,
+	thinkingWasCut,
+	type BudgetMode,
+	type BudgetPhase,
+	type HygieneOptions,
+	type HygieneStats,
+} from "./local-models.ts";
 
 /* ────────────────────────────────────────────────────────────── art ── */
 
@@ -317,6 +336,8 @@ const state = {
 	rebornAt: 0,
 	hasSmartCompact: false,
 	lastCouncil: undefined as { verdict: Vote | null; tally: number; question: string } | undefined,
+	pruned: 0, // tokens the context hygiene keeps away from the model
+	thinkCuts: 0, // replies whose thinking llama.cpp cut at the budget
 };
 
 /** Panel preferences, persisted under "ui" in ~/.pi/agent/magi.json. */
@@ -324,7 +345,7 @@ type Currency = "EUR" | "USD";
 
 const ui = {
 	compact: false,
-	kwhPrice: undefined as number | undefined, // price per kWh, for the COST row (/magi-ui config)
+	kwhPrice: undefined as number | undefined, // price per kWh, for the COST row (/magi cost)
 	currency: "EUR" as Currency,
 };
 
@@ -421,7 +442,9 @@ interface TokenStats {
 
 const tokens: TokenStats = { input: 0, output: 0, cacheRead: 0, cost: 0 };
 
-function addUsage(m: AssistantMessage): void {
+/** Session totals from one assistant reply: tokens, cost, and whether its thinking was cut at the budget. */
+function countAssistant(m: AssistantMessage): void {
+	if (thinkingWasCut(m as any)) state.thinkCuts++;
 	tokens.input += m.usage?.input ?? 0;
 	tokens.output += m.usage?.output ?? 0;
 	tokens.cacheRead += m.usage?.cacheRead ?? 0;
@@ -432,8 +455,9 @@ function addUsage(m: AssistantMessage): void {
 function recountSession(ctx: ExtensionContext): void {
 	Object.assign(tokens, { input: 0, output: 0, cacheRead: 0, cost: 0 });
 	state.lastCouncil = undefined;
+	state.thinkCuts = 0;
 	for (const entry of ctx.sessionManager.getBranch()) {
-		if (entry.type === "message" && entry.message.role === "assistant") addUsage(entry.message as AssistantMessage);
+		if (entry.type === "message" && entry.message.role === "assistant") countAssistant(entry.message as AssistantMessage);
 		if (entry.type === "custom" && entry.customType === "magi-verdict") {
 			const d = entry.data as { verdict?: Vote | null; tally?: number; question?: string } | undefined;
 			if (d && Array.isArray((d as any).opinions)) state.lastCouncil = { verdict: d.verdict ?? null, tally: d.tally ?? 0, question: d.question ?? "" };
@@ -781,10 +805,11 @@ let lastPersistAt = 0;
 /**
  * Adds this session's new energy to the running total in magi.json, so the COST row survives restarts.
  * ponytail: writes at most once a minute, and adds a delta so parallel sessions do not overwrite each other.
+ * A crash therefore loses up to a minute of energy, which is what a kill loses anyway.
  */
-function persistEnergy(force = false): void {
+function persistEnergy(): void {
 	const delta = swap.energyWh - swap.savedWh;
-	if (delta <= 0 || (!force && Date.now() - lastPersistAt < ENERGY_SAVE_MS)) return;
+	if (delta <= 0 || Date.now() - lastPersistAt < ENERGY_SAVE_MS) return;
 	lastPersistAt = Date.now();
 	const cfg = loadMagiConfig();
 	cfg.totalWh = (cfg.totalWh ?? 0) + delta;
@@ -882,6 +907,56 @@ async function swapAliases(): Promise<Map<string, string>> {
 	return aliases;
 }
 
+const PI_THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"];
+
+/**
+ * pi-llama-swap registers every model with reasoning off, so /thinking only offers "off".
+ * llama-swap publishes each model's reasoning levels in /v1/models: re-register the provider with them,
+ * sent as chat_template_kwargs (enable_thinking + reasoning_effort). Aliases (the Instruct twins) stay off.
+ * models.json modelOverrides still apply on top.
+ */
+async function enableSwapReasoning(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+	const config = ctx.modelRegistry.getRegisteredProviderConfig("llama-swap") as any;
+	if (!config?.models?.length || !config.baseUrl) return;
+	try {
+		const headers: Record<string, string> = config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {};
+		const res = await fetch(`${config.baseUrl.replace(/\/$/, "")}/models`, { headers, signal: AbortSignal.timeout(5000) });
+		const { data } = (await res.json()) as { data?: any[] };
+		const meta = new Map((data ?? []).map((m) => [m.id, m]));
+		let changed = false;
+		const models = config.models.map((m: any) => {
+			const entry = meta.get(m.id);
+			const levels: string[] | undefined = entry?.meta?.llamaswap?.reasoning?.levels;
+			const input = entry?.architecture?.input_modalities?.includes("image") ? ["text", "image"] : ["text"];
+			if (!levels?.length || entry.meta.llamaswap.type === "alias") return { ...m, input };
+			changed = true;
+			return {
+				...m,
+				input,
+				reasoning: true,
+				thinkingLevelMap: Object.fromEntries(PI_THINKING_LEVELS.map((l) => [l, levels.includes(l) ? l : null])),
+				compat: {
+					...m.compat,
+					thinkingFormat: "chat-template",
+					chatTemplateKwargs: {
+						enable_thinking: { $var: "thinking.enabled" },
+						preserve_thinking: true,
+						reasoning_effort: { $var: "thinking.effort", omitWhenOff: true },
+					},
+				},
+			};
+		});
+		// ponytail: a /llama-swap refresh re-registers the plain models until the next session start
+		if (!changed) return;
+		ctx.modelRegistry.registerProvider("llama-swap", { ...config, models });
+		// the session already holds the old model object: swap in the new one
+		const fresh = ctx.model?.provider === "llama-swap" ? ctx.modelRegistry.find("llama-swap", ctx.model.id) : undefined;
+		if (fresh?.reasoning) await pi.setModel(fresh);
+	} catch {
+		// server unreachable: models stay as pi-llama-swap registered them
+	}
+}
+
 /** Models llama-swap keeps in memory: real id → "ready" | "starting" | … (empty when the server is unreachable). */
 async function swapRunning(): Promise<Map<string, string>> {
 	try {
@@ -1030,7 +1105,7 @@ async function prewarmPrefix(cwd: string): Promise<void> {
 	}
 }
 
-/* ── /magi-ui status: a report built from the last requests llama-swap recorded ── */
+/* ── /magi status: a report built from the last requests llama-swap recorded ── */
 
 interface ActivityRow {
 	timestamp: string;
@@ -1315,6 +1390,11 @@ class MagiPanel implements Component {
 		if (!compact && usage?.contextWindow) {
 			out.push(this.field("CONTEXT", `${usage.tokens == null ? "?" : fmtTokens(usage.tokens)} / ${fmtTokens(usage.contextWindow)}`, inner, "muted"));
 		}
+		// HYGIENE: tokens pruned from what the model sees, ✂ = thinking cut at the budget
+		if (!compact && (state.pruned || state.thinkCuts)) {
+			const cuts = state.thinkCuts ? ` ✂${state.thinkCuts}` : "";
+			out.push(this.field("HYGIENE", `-${fmtTokens(state.pruned)}${cuts}`, inner, state.thinkCuts ? "warning" : "muted"));
+		}
 		return out;
 	}
 
@@ -1346,14 +1426,12 @@ class MagiPanel implements Component {
 		return out;
 	}
 
-	/** COST: GPU energy × price per kWh set with /magi-ui config — all sessions, with this one in brackets. */
+	/** COST: GPU energy × price per kWh set with /magi cost — all sessions, with this one in brackets. */
 	private costRow(inner: number): string {
 		if (!swap.gpus.length) return this.field("COST", "—", inner, "muted");
-		if (ui.kwhPrice === undefined) return this.field("COST", "→ /magi-ui config", inner, "dim");
-		const th = this.theme;
+		if (ui.kwhPrice === undefined) return this.field("COST", "→ /magi cost", inner, "dim");
 		const price = (wh: number) => fmtMoney((wh / 1000) * ui.kwhPrice!);
-		const label = th.fg("dim", "COST".padEnd(9));
-		return this.frameLine(" " + label + th.fg("warning", price(totalWh())) + th.fg("dim", ` (ses ${price(swap.energyWh)})`), inner);
+		return this.field("COST", price(totalWh()) + this.theme.fg("dim", ` (ses ${price(swap.energyWh)})`), inner, "warning");
 	}
 
 	private swapRows(inner: number, compact: boolean): string[] {
@@ -1505,9 +1583,49 @@ type MagiConfig = Partial<Record<MagiUnit, MagiUnitConfig>> & {
 	ui?: { compact?: boolean; kwhPrice?: number; currency?: Currency };
 	loads?: Record<string, number>; // real model id → ms its last load took
 	totalWh?: number; // GPU energy summed over every session, for the COST row
+	hygiene?: Partial<HygieneOptions> & { enabled?: boolean }; // context pruning for local models, see local-models.ts
+	thinkingBudget?: {
+		mode?: BudgetMode; // auto (learned per model) · fixed · off, set with /magi budget
+		planning?: number; // fixed budgets
+		acting?: number;
+		message?: boolean; // send BUDGET_MESSAGE as reasoning_budget_message (default on), /magi budget message
+		learned?: Record<string, Partial<Record<BudgetPhase, number[]>>>; // written by the theme: recent thinking lengths per model
+	};
 };
 
 const MAGI_CONFIG_PATH = join(homedir(), ".pi", "agent", "magi.json");
+/** /magi arguments that manage the theme instead of asking the council. */
+const UI_ARGS = /^(on|off|panel|compact|status|cost)$|^(hygiene|budget)(\s|$)/i;
+/** /magi arguments offered by autocomplete: the full argument, and what it does. */
+const MAGI_ARGS: [string, string][] = [
+	["council", "ask the three MAGI a question (recent conversation as context)"],
+	["council review", "the council reviews your pending changes before you commit"],
+	["config", "pick a model for each MAGI"],
+	["mecha", "MECHA SELECT: pick the llama-swap model to activate"],
+	["status", "llama-swap report: speed, tokens, cache hits, errors per model"],
+	["panel", "hide/show the side panel"],
+	["compact", "toggle the compact side panel"],
+	["cost", "electricity price and currency for the COST row"],
+	["on", "enable the MAGI chrome"],
+	["off", "disable the MAGI chrome"],
+	["hygiene", "show how much context was pruned"],
+	["hygiene on", "enable context pruning"],
+	["hygiene off", "disable context pruning"],
+	["hygiene step 40k", "prune less often: fewer prompt re-reads on long tasks (default 15k)"],
+	["hygiene 3 5", "recent turns that keep their thinking, tool results kept whole"],
+	["budget", "show the thinking budget of the current model"],
+	["budget auto", "learn the budget per model (default)"],
+	["budget off", "no budget: llama-server decides"],
+	["budget reset", "forget what was learned for the current model"],
+	["budget message", "turn the closing message after a cut off/on"],
+	["budget 16k 4k", "fixed budget: planning, acting"],
+];
+function argCompletions(table: [string, string][], prefix: string) {
+	const p = prefix.trimStart().toLowerCase();
+	const items = table.filter(([value]) => value.startsWith(p)).map(([value, description]) => ({ value, label: value, description }));
+	return items.length ? items : null;
+}
+const LOOP_REPEATS = 3; // the same tool call this many times in a row is blocked
 
 function loadMagiConfig(): MagiConfig {
 	try {
@@ -1561,7 +1679,7 @@ function conversationExcerpt(ctx: ExtensionContext, maxChars = 6000): string {
 
 const REVIEW_MAX_CHARS = 24_000;
 
-/** The pending changes for /magi review: tracked changes against HEAD plus the names of untracked files. */
+/** The pending changes for /magi council review: tracked changes against HEAD plus the names of untracked files. */
 async function pendingChanges(cwd: string): Promise<{ diff: string; untracked: string[] }> {
 	const git = (args: string[]) => promisify(execFile)("git", args, { cwd, maxBuffer: 32 * 1024 * 1024 }).then((r) => r.stdout);
 	let diff: string;
@@ -1723,7 +1841,7 @@ function buildDeliberationView(
 	};
 }
 
-/** A read-only boxed report (used by /magi-ui status); any key closes it. */
+/** A read-only boxed report (used by /magi status); any key closes it. */
 function buildReportView(theme: Theme, lines: string[], close: () => void) {
 	return {
 		render(width: number): string[] {
@@ -1984,7 +2102,7 @@ function buildFooter(tui: TUI, theme: Theme, footerData: any) {
 			// change would shift it under the window. A fresh line is taken when it has the same
 			// width, so nothing moves, otherwise at the end of the loop.
 			const line = left + dim(FOOTER_SCROLL_GAP) + right + dim(FOOTER_SCROLL_GAP);
-			const period = Math.max(1, visibleWidth(line));
+			const period = visibleWidth(line);
 			if (!scrollLine || scrollOff === 0 || period === scrollPeriod) {
 				scrollLine = line;
 				scrollPeriod = period;
@@ -2021,6 +2139,22 @@ export default function (pi: ExtensionAPI) {
 	let panelHandle: OverlayHandle | undefined;
 	let panel: MagiPanel | undefined;
 	let titleDone = false;
+	let hygiene = { enabled: true, ...HYGIENE_DEFAULTS };
+	let hygieneStats: HygieneStats | undefined;
+	let budgetMode: BudgetMode = "auto";
+	let fixedBudget = { ...BUDGET_DEFAULTS };
+	let budgetMessage = true;
+	let learned: Record<string, Partial<Record<BudgetPhase, number[]>>> = {};
+	let pendingBudget: { model: string; phase: BudgetPhase; tokens: number } | undefined; // the request in flight
+	const budgetIgnored = new Set<string>(); // models whose llama-server thought past the budget: it sets its own
+	const budgetFor = (model: string, phase: BudgetPhase) =>
+		budgetMode === "fixed" ? fixedBudget[phase] : (learnedBudget(learned[model]?.[phase] ?? [], phase) ?? BUDGET_DEFAULTS[phase]);
+	const persistBudget = () => {
+		const cfg = loadMagiConfig();
+		saveMagiConfig({ ...cfg, thinkingBudget: { mode: budgetMode, ...fixedBudget, message: budgetMessage, learned } });
+	};
+	let lastCall = ""; // loop guard: fingerprint of the previous tool call and how often it repeated
+	let repeats = 0;
 
 	const repaint = () => {
 		panel?.invalidate();
@@ -2181,6 +2315,24 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_start", async (event, ctx) => {
 		liveCtx = ctx;
+		const magiCfg = loadMagiConfig();
+		hygiene = { enabled: true, ...HYGIENE_DEFAULTS, ...magiCfg.hygiene };
+		const tb = magiCfg.thinkingBudget ?? {};
+		budgetMode = tb.mode ?? "auto";
+		fixedBudget = { planning: tb.planning ?? BUDGET_DEFAULTS.planning, acting: tb.acting ?? BUDGET_DEFAULTS.acting };
+		budgetMessage = tb.message ?? true;
+		learned = tb.learned ?? {};
+		await enableSwapReasoning(pi, ctx);
+		// the local-model rules live next to AGENTS.md, created once so the user can edit them
+		const rules = join(ctx.cwd, "MAGI.md");
+		if (!existsSync(rules)) {
+			try {
+				writeFileSync(rules, MAGI_MD);
+				if (ctx.mode === "tui") ctx.ui.notify("MAGI.md created: rules for local models, appended to the system prompt", "info");
+			} catch {
+				// read-only directory: the built-in rules are used as they are
+			}
+		}
 		void refreshUnit(ctx);
 		recountSession(ctx);
 		state.hasSmartCompact = pi.getCommands().some((c) => c.name.replace(/^\//, "") === "smart-compact");
@@ -2233,6 +2385,12 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("before_provider_request", (event, ctx) => {
 		rememberPrefix(ctx.cwd, event.payload);
+		// llama.cpp honours a per-request thinking budget only when llama-server runs without --reasoning-budget
+		if (budgetMode === "off" || !swap.base || !ctx.model) return;
+		const phase = requestPhase(event.payload);
+		pendingBudget = { model: ctx.model.id, phase, tokens: budgetFor(ctx.model.id, phase) };
+		const payload = { ...(event.payload as object), thinking_budget_tokens: pendingBudget.tokens };
+		return budgetMessage ? { ...payload, reasoning_budget_message: `\n\n${BUDGET_MESSAGE}` } : payload;
 	});
 
 	pi.on("model_select", async (event, ctx) => {
@@ -2242,7 +2400,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", async () => {
-		persistEnergy(true);
+		persistEnergy();
 		prewarm.abort?.abort();
 		clearInterval(metricsTimer);
 		metricsTimer = undefined;
@@ -2257,6 +2415,40 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("agent_start", async () => {
 		state.runStart = Date.now();
+		lastCall = "";
+	});
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		let rules = MAGI_MD;
+		try {
+			rules = readFileSync(join(ctx.cwd, "MAGI.md"), "utf8");
+		} catch {
+			// no MAGI.md (deleted, or unwritable cwd): the built-in rules
+		}
+		return rules.trim() ? { systemPrompt: `${event.systemPrompt}\n\n${rules.trim()}` } : undefined;
+	});
+
+	// before every request: drop old thinking and tool outputs from what the model sees, never from the session
+	pi.on("context", async (event) => {
+		if (!hygiene.enabled) return;
+		const pruned = pruneContext(event.messages as any, hygiene);
+		hygieneStats = pruned.stats;
+		state.pruned = pruned.stats.prunedTokens;
+		return { messages: pruned.messages as any };
+	});
+
+	// local models loop on the same call, and may copy a pruned placeholder into a file
+	pi.on("tool_call", async (event) => {
+		const args = JSON.stringify(event.input);
+		if ((event.toolName === "write" || event.toolName === "edit") && args.includes(PRUNED_MARK)) {
+			return { block: true, reason: `MAGI: this ${event.toolName} contains a "${PRUNED_MARK}" placeholder, not real content. Read the file and use the actual text.` };
+		}
+		const fingerprint = event.toolName + args;
+		repeats = fingerprint === lastCall ? repeats + 1 : 1;
+		lastCall = fingerprint;
+		if (repeats >= LOOP_REPEATS) {
+			return { block: true, reason: `MAGI: identical ${event.toolName} call ${repeats} times in a row. Repeating it will not change the outcome: change approach, or tell the user what blocks you.` };
+		}
 	});
 
 	pi.on("turn_start", async (_event, ctx) => {
@@ -2300,7 +2492,19 @@ export default function (pi: ExtensionAPI) {
 	pi.on("message_end", async (event) => {
 		if (event.message.role !== "assistant") return;
 		const m = event.message as AssistantMessage;
-		addUsage(m);
+		countAssistant(m);
+		// learn how long this model thinks in this phase; a cut must not raise the budget
+		const thought = thinkingTokens(m as any);
+		if (pendingBudget && thought > 0 && m.stopReason !== "aborted" && m.stopReason !== "error") {
+			const verdict = budgetVerdict(m as any, pendingBudget.tokens);
+			if (verdict === "ignored") budgetIgnored.add(pendingBudget.model);
+			if (verdict === "cut" && !thinkingWasCut(m as any)) state.thinkCuts++; // silent cut: no budget message on the server
+			const samples = ((learned[pendingBudget.model] ??= {})[pendingBudget.phase] ??= []);
+			samples.push(budgetSample(thought, pendingBudget.tokens, verdict === "cut"));
+			samples.splice(0, samples.length - BUDGET_WINDOW);
+			persistBudget();
+		}
+		pendingBudget = undefined;
 		if (perf.start) {
 			const end = Date.now();
 			perf.lastMs = end - perf.start;
@@ -2436,9 +2640,11 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	pi.registerCommand("magi", {
-		description: "Ask the three MAGI (pragmatist, guardian, visionary); /magi review [focus] judges the git diff; /magi config assigns models; /magi mecha picks the model",
+		description: "Ask the three MAGI, or manage them: review [focus] · config · mecha · status · panel · compact · cost · on · off · hygiene · budget (type a space to see them all)",
+		getArgumentCompletions: (prefix) => argCompletions(MAGI_ARGS, prefix),
 		handler: async (args, ctx) => {
 			const arg = args.trim();
+			if (UI_ARGS.test(arg)) return manageUi(arg, ctx);
 			if (arg === "config") return configureMagi(ctx);
 			if (arg === "mecha") {
 				if (ctx.mode !== "tui" || !swap.base) return ctx.ui.notify("MECHA SELECT needs the TUI and a llama-swap model", "error");
@@ -2446,8 +2652,12 @@ export default function (pi: ExtensionAPI) {
 				return pickModel(ctx);
 			}
 
-			if (arg === "review" || arg.startsWith("review ")) {
-				const focus = arg.slice("review".length).trim();
+			if (arg !== "council" && !arg.startsWith("council ")) {
+				return ctx.ui.notify(arg ? `Unknown /magi command "${arg}": to ask the MAGI, /magi council <question>` : "Ask the MAGI with /magi council <question>; type /magi and a space to see every command", arg ? "warning" : "info");
+			}
+			const ask = arg.slice("council".length).trim();
+			if (ask === "review" || ask.startsWith("review ")) {
+				const focus = ask.slice("review".length).trim();
 				let changes: { diff: string; untracked: string[] };
 				try {
 					changes = await pendingChanges(ctx.cwd);
@@ -2470,93 +2680,151 @@ export default function (pi: ExtensionAPI) {
 				return runCouncil(ctx, question, "```diff\n" + diff + "\n```" + untracked, "Pending changes (git diff HEAD)");
 			}
 
-			const question = arg || (await ctx.ui.input("Question for the MAGI:", "should we …?"))?.trim() || "";
+			const question = ask || (await ctx.ui.input("Question for the MAGI:", "should we …?"))?.trim() || "";
 			if (!question) return;
 			return runCouncil(ctx, question, conversationExcerpt(ctx));
 		},
 	});
 
-	pi.registerCommand("magi-ui", {
-		description: "MAGI chrome: enable the theme, or manage it (on|off|panel|compact|status|config)",
-		handler: async (args, ctx) => {
-			liveCtx = ctx;
-			const arg = args.trim().toLowerCase();
-
-			if (arg === "panel") {
-				panelEnabled = !panelEnabled;
-				if (panelEnabled) showPanel(ctx.ui.theme);
-				else hidePanel();
-				ctx.ui.notify(`Side panel ${panelEnabled ? "enabled" : "disabled"}`, "info");
+	/** /magi on|off|panel|compact|status|cost|hygiene|budget: the theme, its panel and the local-model settings. */
+	async function manageUi(args: string, ctx: ExtensionCommandContext) {
+		liveCtx = ctx;
+		const arg = args.trim().toLowerCase();
+
+		if (arg === "hygiene" || arg.startsWith("hygiene ")) {
+			const sub = arg.slice("hygiene".length).trim();
+			const keep = /^(\d+)\s+(\d+)$/.exec(sub);
+			const step = /^step\s+(\d+)(k?)$/.exec(sub);
+			if (sub === "on" || sub === "off" || keep || step) {
+				if (keep) Object.assign(hygiene, { enabled: true, keepThinkingTurns: Number(keep[1]), keepToolResults: Number(keep[2]) });
+				else if (step) hygiene.stepTokens = Math.max(1000, Number(step[1]) * (step[2] ? 1000 : 1));
+				else hygiene.enabled = sub === "on";
+				const cfg = loadMagiConfig();
+				const { enabled, keepThinkingTurns, keepToolResults, stepTokens } = hygiene;
+				saveMagiConfig({ ...cfg, hygiene: { ...cfg.hygiene, enabled, keepThinkingTurns, keepToolResults, stepTokens } });
+			} else if (sub) {
+				ctx.ui.notify("Usage: /magi hygiene [on|off|step <tokens>|<thinking turns kept> <tool results kept>], e.g. step 40k, 3 5", "warning");
 				return;
 			}
-			if (arg === "compact") {
-				ui.compact = !ui.compact;
-				const cfg = loadMagiConfig();
-				saveMagiConfig({ ...cfg, ui: { ...cfg.ui, compact: ui.compact } });
-				repaint();
-				ctx.ui.notify(`Side panel ${ui.compact ? "compact" : "detailed"}`, "info");
+			const s = hygieneStats;
+			ctx.ui.notify(
+				(!hygiene.enabled
+					? "Context hygiene off: /magi hygiene on"
+					: s
+						? `Context hygiene: ${fmtTokens(s.prunedTokens)} tokens pruned in the first ${s.watermark}/${s.messages} messages, ${fmtTokens(s.pendingTokens)} waiting for the next step (every ${fmtTokens(hygiene.stepTokens)})`
+						: "Context hygiene on: nothing sent to the model yet") +
+					` · keeps thinking of the last ${hygiene.keepThinkingTurns} turns, the last ${hygiene.keepToolResults} tool results` +
+					(state.thinkCuts ? ` · thinking cut at the budget ${state.thinkCuts}×` : ""),
+				"info",
+			);
+			return;
+		}
+		if (arg === "budget" || arg.startsWith("budget ")) {
+			const sub = arg.slice("budget".length).trim();
+			const model = ctx.model?.id ?? "";
+			const tokens = (t: string) => Math.round(Number(t.replace(/k$/, "")) * (t.endsWith("k") ? 1024 : 1));
+			const fixed = /^(\d+k?)\s+(\d+k?)$/.exec(sub);
+			if (sub === "auto" || sub === "off") budgetMode = sub;
+			else if (sub === "reset") delete learned[model];
+			else if (sub === "message") budgetMessage = !budgetMessage;
+			else if (fixed) {
+				budgetMode = "fixed";
+				fixedBudget = { planning: tokens(fixed[1]!), acting: tokens(fixed[2]!) };
+			} else if (sub) {
+				ctx.ui.notify("Usage: /magi budget [auto|off|reset|message|<planning> <acting>], e.g. 16k 4k", "warning");
 				return;
 			}
-			if (arg === "config") {
-				const currency = await ctx.ui.select(`Currency for COST (current: ${ui.currency})`, ["EUR", "USD"]);
-				if (!currency) return;
-				const current = ui.kwhPrice !== undefined ? ` (current: ${ui.kwhPrice})` : "";
-				const raw = (await ctx.ui.input(`Electricity price per kWh in ${currency}${current}:`, "0.30"))?.trim();
-				if (raw === undefined) return;
-				const price = raw === "" && ui.kwhPrice !== undefined ? ui.kwhPrice : Number(raw.replace(",", "."));
-				if (raw === "" && ui.kwhPrice === undefined) {
-					ctx.ui.notify("No price entered: COST unchanged", "warning");
-					return;
-				}
-				if (!Number.isFinite(price) || price < 0) {
-					ctx.ui.notify(`Invalid price: "${raw}"`, "error");
-					return;
-				}
-				ui.currency = currency === "USD" ? "USD" : "EUR";
-				ui.kwhPrice = price;
-				const cfg = loadMagiConfig();
-				saveMagiConfig({ ...cfg, ui: { ...cfg.ui, currency: ui.currency, kwhPrice: price } });
-				repaint();
-				ctx.ui.notify(`COST: ${fmtMoney(price)} per kWh`, "info");
+			if (sub) persistBudget();
+			const phase = (p: BudgetPhase) => {
+				const n = learned[model]?.[p]?.length ?? 0;
+				const how = budgetMode === "fixed" ? "fixed" : learnedBudget(learned[model]?.[p] ?? [], p) ? `learned from ${n}` : `default, learning ${n}/10`;
+				return `${p} ${budgetFor(model, p) / 1024}k (${how})`;
+			};
+			ctx.ui.notify(
+				budgetMode === "off"
+					? "Thinking budget off: llama-server decides. /magi budget auto"
+					: `Thinking budget ${budgetMode.toUpperCase()} · ${model || "no model"}: ${phase("planning")} · ${phase("acting")}` +
+							` · closing message ${budgetMessage ? "on" : "off"}` +
+							(swap.base ? "" : " · applies to llama-swap models only") +
+							(budgetIgnored.has(model) ? " · ⚠ llama-server thinks past it: it was started with its own --reasoning-budget (or is too old), which wins" : ""),
+				"info",
+			);
+			return;
+		}
+		if (arg === "panel") {
+			panelEnabled = !panelEnabled;
+			if (panelEnabled) showPanel(ctx.ui.theme);
+			else hidePanel();
+			ctx.ui.notify(`Side panel ${panelEnabled ? "enabled" : "disabled"}`, "info");
+			return;
+		}
+		if (arg === "compact") {
+			ui.compact = !ui.compact;
+			const cfg = loadMagiConfig();
+			saveMagiConfig({ ...cfg, ui: { ...cfg.ui, compact: ui.compact } });
+			repaint();
+			ctx.ui.notify(`Side panel ${ui.compact ? "compact" : "detailed"}`, "info");
+			return;
+		}
+		if (arg === "cost") {
+			const currency = await ctx.ui.select(`Currency for COST (current: ${ui.currency})`, ["EUR", "USD"]);
+			if (!currency) return;
+			const current = ui.kwhPrice !== undefined ? ` (current: ${ui.kwhPrice})` : "";
+			const raw = (await ctx.ui.input(`Electricity price per kWh in ${currency}${current}:`, "0.30"))?.trim();
+			if (raw === undefined) return;
+			const price = raw === "" && ui.kwhPrice !== undefined ? ui.kwhPrice : Number(raw.replace(",", "."));
+			if (raw === "" && ui.kwhPrice === undefined) {
+				ctx.ui.notify("No price entered: COST unchanged", "warning");
 				return;
 			}
-			if (arg === "status") {
-				if (!swap.base) {
-					ctx.ui.notify("/magi-ui status needs a llama-swap session model", "warning");
-					return;
-				}
-				let report: { data?: ActivityRow[]; total?: number };
-				try {
-					report = (await (await swapGet(`/api/metrics/activity?limit=${ACTIVITY_REPORT_ROWS}`, 15_000)).json()) as typeof report;
-				} catch (err) {
-					ctx.ui.notify(`llama-swap status failed: ${err instanceof Error ? err.message : String(err)}`, "error");
-					return;
-				}
-				const rows = report.data ?? [];
-				if (!rows.length) {
-					ctx.ui.notify("llama-swap has no recorded requests yet", "info");
-					return;
-				}
-				await ctx.ui.custom<void>((_tui, theme, _keys, done) =>
-					buildReportView(theme, activityReport(theme, rows, report.total ?? rows.length), () => done(undefined)),
-				);
+			if (!Number.isFinite(price) || price < 0) {
+				ctx.ui.notify(`Invalid price: "${raw}"`, "error");
 				return;
 			}
-			if (arg === "off" || arg === "on") {
-				chrome = arg === "on";
-				applyChrome(ctx);
-				ctx.ui.notify(`MAGI chrome ${chrome ? "enabled" : "disabled"}`, "info");
+			ui.currency = currency === "USD" ? "USD" : "EUR";
+			ui.kwhPrice = price;
+			const cfg = loadMagiConfig();
+			saveMagiConfig({ ...cfg, ui: { ...cfg.ui, currency: ui.currency, kwhPrice: price } });
+			repaint();
+			ctx.ui.notify(`COST: ${fmtMoney(price)} per kWh`, "info");
+			return;
+		}
+		if (arg === "status") {
+			if (!swap.base) {
+				ctx.ui.notify("/magi status needs a llama-swap session model", "warning");
 				return;
 			}
-
-			const res = ctx.ui.setTheme("magi");
-			if (!res.success) {
-				ctx.ui.notify(`Theme magi not found: ${res.error}`, "error");
+			let report: { data?: ActivityRow[]; total?: number };
+			try {
+				report = (await (await swapGet(`/api/metrics/activity?limit=${ACTIVITY_REPORT_ROWS}`, 15_000)).json()) as typeof report;
+			} catch (err) {
+				ctx.ui.notify(`llama-swap status failed: ${err instanceof Error ? err.message : String(err)}`, "error");
 				return;
 			}
-			chrome = true;
+			const rows = report.data ?? [];
+			if (!rows.length) {
+				ctx.ui.notify("llama-swap has no recorded requests yet", "info");
+				return;
+			}
+			await ctx.ui.custom<void>((_tui, theme, _keys, done) =>
+				buildReportView(theme, activityReport(theme, rows, report.total ?? rows.length), () => done(undefined)),
+			);
+			return;
+		}
+		if (arg === "off") {
+			chrome = false;
 			applyChrome(ctx);
-			ctx.ui.notify("MAGI online — /magi-ui panel|compact|status|off", "info");
-		},
-	});
+			ctx.ui.notify("MAGI chrome disabled", "info");
+			return;
+		}
+
+		const res = ctx.ui.setTheme("magi");
+		if (!res.success) {
+			ctx.ui.notify(`Theme magi not found: ${res.error}`, "error");
+			return;
+		}
+		chrome = true;
+		applyChrome(ctx);
+		ctx.ui.notify("MAGI online — /magi panel|compact|status|off", "info");
+	}
 }

package/extensions/magi/local-models.ts

@@ -0,0 +1,240 @@
+/**
+ * Local-model helpers for MAGI: context hygiene, loop guard, and the MAGI.md rules template.
+ *
+ * Context hygiene rewrites the messages pi sends to the model (never the saved session):
+ *  - old thinking blocks are dropped: Qwen templates resend every reasoning block of an agent run,
+ *    one 18k-token think stays in the context until compaction
+ *  - old tool outputs become a one-line marker (observation masking, Lindenbauer et al. 2025:
+ *    as good as LLM summarization, at half the cost)
+ *  - old write/edit payloads become a marker too: the file on disk is the source of truth
+ * Pruning advances in steps behind a watermark, so between steps the prompt only grows at the end
+ * and llama.cpp keeps reusing its KV cache.
+ */
+
+export type Msg = { role: string; content?: any; [key: string]: any };
+
+export interface HygieneOptions {
+	keepThinkingTurns: number; // newest assistant messages that keep their thinking
+	keepToolResults: number; // newest tool results kept whole
+	stepTokens: number; // the watermark moves each time the prunable total crosses another multiple of this
+	minPruneChars: number; // smaller outputs/payloads are left alone
+}
+
+export interface HygieneStats {
+	messages: number;
+	watermark: number; // messages before this index are pruned
+	prunedTokens: number;
+	pendingTokens: number; // prunable, waiting for the next step
+	stepTokens: number;
+}
+
+export const HYGIENE_DEFAULTS: HygieneOptions = { keepThinkingTurns: 3, keepToolResults: 5, stepTokens: 15_000, minPruneChars: 600 };
+
+// ponytail: chars/token measured on Qwen3.x pi sessions (2.9–3.2); a tokenizer call would be exact but costs a request
+const CHARS_PER_TOKEN = 3;
+const IMAGE_CHARS = 4800;
+
+/** Marks every placeholder, so a model that copies one into a real write/edit gets blocked (see loop guard). */
+export const PRUNED_MARK = "<<pruned by MAGI";
+
+const lines = (s: string) => s.split("\n").length;
+const clip = (s: string, n = 80) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+
+function callTarget(call: any): string {
+	const a = call?.arguments ?? {};
+	return clip(String(a.path ?? a.command ?? a.pattern ?? a.query ?? a.url ?? ""));
+}
+
+function resultChars(m: Msg): number {
+	let n = 0;
+	for (const c of m.content ?? []) n += c.type === "image" ? IMAGE_CHARS : (c.text?.length ?? 0);
+	return n;
+}
+
+function editChars(call: any): number {
+	return (call.arguments?.edits ?? []).reduce((n: number, e: any) => n + (e.oldText?.length ?? 0) + (e.newText?.length ?? 0), 0);
+}
+
+/** Chars pruning would remove from this assistant message. */
+function assistantSavings(m: Msg, o: HygieneOptions): number {
+	let n = 0;
+	for (const c of m.content ?? []) {
+		if (c.type === "thinking") n += c.thinking?.length ?? 0;
+		else if (c.type === "toolCall" && c.name === "write" && (c.arguments?.content?.length ?? 0) >= o.minPruneChars) n += c.arguments.content.length;
+		else if (c.type === "toolCall" && c.name === "edit" && editChars(c) >= o.minPruneChars) n += editChars(c);
+	}
+	return n;
+}
+
+function pruneAssistant(m: Msg, o: HygieneOptions): Msg {
+	const content = [];
+	for (const c of m.content ?? []) {
+		if (c.type === "thinking") continue;
+		if (c.type === "toolCall" && c.name === "write" && (c.arguments?.content?.length ?? 0) >= o.minPruneChars) {
+			const text = c.arguments.content as string;
+			content.push({ ...c, arguments: { ...c.arguments, content: `${PRUNED_MARK}: ${lines(text)} lines written, the file on disk is the source of truth>>` } });
+		} else if (c.type === "toolCall" && c.name === "edit" && editChars(c) >= o.minPruneChars) {
+			const edits = c.arguments.edits.map((e: any) => ({ oldText: `${PRUNED_MARK}>>`, newText: `${PRUNED_MARK}: ${lines(e.newText ?? "")} lines>>` }));
+			content.push({ ...c, arguments: { ...c.arguments, edits } });
+		} else content.push(c);
+	}
+	// a message that only held thinking keeps a marker: some templates choke on an empty assistant turn
+	if (!content.length) content.push({ type: "text", text: `${PRUNED_MARK}: reasoning>>` });
+	return { ...m, content };
+}
+
+function pruneResult(m: Msg, call: any): Msg {
+	const text = (m.content ?? []).map((c: any) => c.text ?? "").join("\n");
+	const what = [m.toolName, callTarget(call)].filter(Boolean).join(" ");
+	return { ...m, content: [{ type: "text", text: `${PRUNED_MARK}: output of ${what}, ${lines(text)} lines. Run it again if you need it.>>` }] };
+}
+
+/**
+ * Prunes everything before the watermark. The watermark sits on the last point where the prunable chars,
+ * summed from the first message, crossed a multiple of stepTokens. Only messages before the protected tail
+ * count, and the tail only moves forward, so earlier crossings never move: the pruned prefix is stable.
+ */
+export function pruneContext(messages: Msg[], o: HygieneOptions = HYGIENE_DEFAULTS): { messages: Msg[]; stats: HygieneStats } {
+	const lastIndices = (role: string, keep: number) =>
+		messages.flatMap((m, i) => (m.role === role ? [i] : [])).slice(-keep);
+	const tail = [...lastIndices("assistant", o.keepThinkingTurns), ...lastIndices("toolResult", o.keepToolResults)];
+	const tailStart = tail.length ? Math.min(...tail) : messages.length;
+
+	const calls = new Map<string, any>();
+	for (const m of messages) if (m.role === "assistant") for (const c of m.content ?? []) if (c.type === "toolCall") calls.set(c.id, c);
+
+	const savings = (m: Msg) =>
+		m.role === "assistant" ? assistantSavings(m, o) : m.role === "toolResult" && resultChars(m) >= o.minPruneChars ? resultChars(m) : 0;
+
+	const step = o.stepTokens * CHARS_PER_TOKEN;
+	let sum = 0;
+	let watermark = 0;
+	let prunedChars = 0;
+	for (let i = 0; i < tailStart; i++) {
+		sum += savings(messages[i]!);
+		if (Math.floor(sum / step) > Math.floor(prunedChars / step)) {
+			watermark = i + 1;
+			prunedChars = sum;
+		}
+	}
+
+	const out = messages.map((m, i) => {
+		if (i >= watermark || !savings(m)) return m;
+		return m.role === "assistant" ? pruneAssistant(m, o) : pruneResult(m, calls.get(m.toolCallId));
+	});
+	return {
+		messages: out,
+		stats: {
+			messages: messages.length,
+			watermark,
+			prunedTokens: Math.round(prunedChars / CHARS_PER_TOKEN),
+			pendingTokens: Math.round((sum - prunedChars) / CHARS_PER_TOKEN),
+			stepTokens: o.stepTokens,
+		},
+	};
+}
+
+/**
+ * Sent as reasoning_budget_message with every request: when the thinking budget runs out llama.cpp forces this text,
+ * then the end-of-thinking tag, and the model reads it as its own words, so it says what to do next.
+ * A llama-server older than the per-request message closes the thinking silently; cuts are then detected by length (budgetVerdict).
+ */
+export const BUDGET_MESSAGE = "Time is up. I will take the smallest safe next step with what I know, and write my open plan into PLAN.md.";
+
+export type BudgetPhase = "planning" | "acting"; // right after the user spoke / between tool calls
+export type BudgetMode = "auto" | "fixed" | "off";
+
+/** Starting budgets, used until a model has enough samples to learn its own. */
+export const BUDGET_DEFAULTS: Record<BudgetPhase, number> = { planning: 16384, acting: 4096 };
+export const BUDGET_LIMITS: Record<BudgetPhase, [number, number]> = { planning: [4096, 32768], acting: [2048, 4096] }; // acting: past ~4k between tool calls it is overthinking
+
+const BUDGET_SAMPLES_MIN = 10;
+export const BUDGET_WINDOW = 30; // thinking lengths kept per model and phase
+const BUDGET_PERCENTILE = 0.95;
+const BUDGET_HEADROOM = 1.5;
+
+/** Phase of the next request, from the OpenAI-style payload: a tool result last means the agent is mid-task. */
+export function requestPhase(payload: any): BudgetPhase {
+	return payload?.messages?.at(-1)?.role === "tool" ? "acting" : "planning";
+}
+
+/**
+ * Learned budget: 1.5 × the 95th percentile of recent thinking lengths, clamped and rounded to 1k.
+ * Cuts never raise it (see budgetSample): a model that often runs away is held at its budget instead of chased.
+ * Replies that finish close under the budget raise it, a model that thinks little pulls it down.
+ * Undefined until there are enough samples.
+ */
+export function learnedBudget(samples: number[], phase: BudgetPhase): number | undefined {
+	if (samples.length < BUDGET_SAMPLES_MIN) return undefined;
+	const sorted = [...samples].sort((a, b) => a - b);
+	const p = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * BUDGET_PERCENTILE))]!;
+	const [lo, hi] = BUDGET_LIMITS[phase];
+	return Math.min(hi, Math.max(lo, Math.ceil((p * BUDGET_HEADROOM) / 1024) * 1024));
+}
+
+/** The sample to learn from a reply: a cut counts as budget / headroom, so cuts alone give back the same budget. */
+export function budgetSample(thought: number, budget: number, cut: boolean): number {
+	return cut ? budget / BUDGET_HEADROOM : thought;
+}
+
+/**
+ * What the server did with the budget sent for this reply, from the thinking length (estimated, ±10%):
+ * cut near the budget, "ignored" well past it (llama-server started with its own --reasoning-budget, or too old
+ * to read thinking_budget_tokens), otherwise within.
+ */
+export function budgetVerdict(m: Msg, budget: number): "cut" | "ignored" | "within" {
+	if (thinkingWasCut(m)) return "cut";
+	const thought = thinkingTokens(m);
+	return thought > budget * 1.3 ? "ignored" : thought >= budget * 0.9 ? "cut" : "within";
+}
+
+/** Estimated thinking tokens of a reply (same chars/token as the hygiene). */
+export function thinkingTokens(m: Msg): number {
+	const chars = (m.content ?? []).reduce((n: number, c: any) => n + (c.type === "thinking" ? (c.thinking?.length ?? 0) : 0), 0);
+	return Math.round(chars / CHARS_PER_TOKEN);
+}
+
+/** Whether llama.cpp cut this message's thinking at the budget. */
+export function thinkingWasCut(m: Msg): boolean {
+	return (m.content ?? []).some((c: any) => c.type === "thinking" && (c.thinking ?? "").trimEnd().endsWith(BUDGET_MESSAGE));
+}
+
+/**
+ * Written to <project>/MAGI.md when missing, then appended to the system prompt on every run.
+ * English on purpose: Qwen-family models reason in English and follow English rules more reliably.
+ * Kept short: it is paid for on every request.
+ */
+export const MAGI_MD = `# MAGI rules for local models
+
+These rules are appended to the system prompt by the MAGI extension. Edit them freely; delete the file to get the defaults back.
+
+## Think less, act more
+- Keep reasoning short: understand the step, decide, act. Do not re-plan what is already decided.
+- Never draft code or file contents in your reasoning. Write them directly with the write/edit tool.
+- If two attempts at the same approach fail, stop and change approach, or ask the user. Do not retry blindly.
+- If your reasoning stopped abruptly mid-thought, or ends with "${BUDGET_MESSAGE.split(". ")[0]}.", your thinking budget ran out: in that turn make no large or irreversible change. Write your open plan into PLAN.md or take one small step you can verify; the next turn gives you a fresh budget.
+
+## Your context is small: spend it carefully
+- Search before reading: use rg/find to locate code, then read only the needed range (offset/limit).
+- Do not read whole large files, and do not re-read a file you just wrote.
+- Trim long command output: pipe through tail, head or rg.
+- Old tool outputs and old reasoning are removed from your context automatically (marked "${PRUNED_MARK}…>>"). Anything you will need later must be written down (see below). Never copy those markers into a file.
+
+## Keep the task state on disk
+- For any task longer than a few steps, keep PLAN.md (a checklist) and NOTES.md (findings, decisions, commands that work).
+- Update them after every completed step. If the context is compacted or a new session starts, continue from PLAN.md.
+
+## Edit safely
+- edit oldText must match the file exactly: copy it from a fresh read, keep it small and unique.
+- If an edit fails, read that region again instead of guessing.
+- For big new files: write a skeleton first, then fill it with edits. Never replace a whole file with a partial version.
+
+## Verify, never assume
+- Never invent paths, functions, APIs or flags: check with ls, rg, --help or the docs first.
+- After a change, run the build, the tests or the program. Claim success only when a tool result proves it.
+- If you cannot verify something, say so explicitly.
+
+## Finish cleanly
+- When done: say briefly what changed, how you verified it, and what is left.
+- Answer in the user's language.
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-magi-theme",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "MAGI SYSTEM theme + extension for pi (Evangelion fan art): MAGI control screen panel, three-model /magi council, MECHA SELECT model picker, angel-attack loading, seven-seal context gauge, llama-swap telemetry",
   "keywords": [
     "pi-package",