@krtclcdy/tersio 2.25.2 → 2.25.3

package/{cli → dist/cli}/update.js

@@ -6,7 +6,7 @@ import { IS_WINDOWS, OMP_PLUGINS_DIR, PACKAGE_BIN, PACKAGE_NAME, PACKAGE_VERSION
 import { execNetwork, sayTagged } from './interactive.js';
 import { readTextIfExists, resolveRtkBinary, tersioDataPath } from '../extensions/lib/utils.js';
 import { refreshPrices } from '../extensions/shared/pricing.js';
-import { CAVEMAN_REMOTE_ULTRA, CAVEMAN_REMOTE_WENYAN, RTK_RELEASE_API, httpsGet, normalizeRtkVersion, sha256Hex, } from '../extensions/lib/utils.js';
+import { CAVEMAN_REMOTE_ULTRA, CAVEMAN_REMOTE_MEGACAVE, RTK_RELEASE_API, httpsGet, normalizeRtkVersion, sha256Hex, } from '../extensions/lib/utils.js';
 import { parseHostArg } from './hosts.js';
 const UPDATE_CHECK_TTL_MS = 6 * 60 * 60 * 1000;
 function newerThan(a, b) {
@@ -84,9 +84,9 @@ async function probeUpdatePlan(cliLatest) {
     const [rtkLocal, rtkRelease, ruleLocal, ruleRemote, ponytailLocalText] = await Promise.all([
         settle(rtkBin ? execP(rtkBin, ['--version'], { timeout: 5000 }).then((r) => normalizeRtkVersion(r.stdout.trim() || r.stderr.trim()) || null) : Promise.resolve(null), 6000),
         settle(httpsGet(RTK_RELEASE_API, { signal: controller.signal }).then((text) => normalizeRtkVersion(JSON.parse(text).tag_name) || null), 1500),
-        Promise.all([readTextIfExists(tersioRule('rule-ultra.md')), readTextIfExists(tersioRule('rule-wenyan.md'))])
+        Promise.all([readTextIfExists(tersioRule('rule-ultra.md')), readTextIfExists(tersioRule('rule-megacave.md'))])
             .then((texts) => (texts.every(Boolean) ? texts.map((t) => sha256Hex(t).slice(0, 8)).join('+') : null)),
-        settle(Promise.all([httpsGet(CAVEMAN_REMOTE_ULTRA, { signal: controller.signal }), httpsGet(CAVEMAN_REMOTE_WENYAN, { signal: controller.signal })])
+        settle(Promise.all([httpsGet(CAVEMAN_REMOTE_ULTRA, { signal: controller.signal }), httpsGet(CAVEMAN_REMOTE_MEGACAVE, { signal: controller.signal })])
             .then((texts) => texts.map((t) => sha256Hex(t).slice(0, 8)).join('+')), 1500),
         readTextIfExists(ponytailPkg),
     ]);
@@ -214,8 +214,7 @@ async function runLatestUpdate() {
     // Inherited stdio, no outer spinner; the delegated installer runs quiet and this parent owns both the plan line and the closing summary.
     try {
         await execInherit(npmCommand, npmCommandArgs);
-        const hostName = pinned === 'pi' ? 'pi' : pinned === 'opencode' ? 'OpenCode' : 'OMP';
-        console.log(`Done — tersio ${plan.cli ?? PACKAGE_VERSION}. Restart ${hostName}.`);
+        console.log(`Done — tersio ${plan.cli ?? PACKAGE_VERSION} and add-ons updated.`);
         if (!dryRun) {
             try {
                 await refreshPrices();

package/{extensions → dist/extensions}/ai-addons-updater/index.js

@@ -6,7 +6,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setExtensionLabel } from '../shared/host.js';
-import { CAVEMAN_REMOTE_ULTRA, CAVEMAN_REMOTE_WENYAN, RTK_RELEASE_API, fetchJson, findFile, findHoistedPackage, httpsGet, httpsDownload, isPiProcess, sha256Hex, parseChecksum, normalizeRtkVersion, readTextIfExists, rtkPlatformSpec, resolveRtkBinary, } from '../lib/utils.js';
+import { CAVEMAN_REMOTE_ULTRA, CAVEMAN_REMOTE_MEGACAVE, RTK_RELEASE_API, fetchJson, findFile, findHoistedPackage, httpsGet, httpsDownload, isPiProcess, sha256Hex, parseChecksum, normalizeRtkVersion, readTextIfExists, rtkPlatformSpec, resolveRtkBinary, } from '../lib/utils.js';
 const IS_WINDOWS = process.platform === 'win32';
 const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PONYTAIL_REMOTE = 'https://raw.githubusercontent.com/DietrichGebert/ponytail/main/package.json';
@@ -16,7 +16,7 @@ const cavemanRule = (name) => path.join(EXTENSION_DIR, '..', 'caveman-session',
 const CAVEMAN_LOCAL = cavemanRule('rule.md');
 const CAVEMAN_TRACKED = [
     { file: cavemanRule('rule-ultra.md'), remote: CAVEMAN_REMOTE_ULTRA },
-    { file: cavemanRule('rule-wenyan.md'), remote: CAVEMAN_REMOTE_WENYAN },
+    { file: cavemanRule('rule-megacave.md'), remote: CAVEMAN_REMOTE_MEGACAVE },
 ];
 const HOST_NAME = isPiProcess() ? 'Pi' : 'OMP';
 const RELOAD_MSG = `Reminder: restart ${HOST_NAME} (or reload extensions) for updates to take effect.`;

package/{extensions → dist/extensions}/caveman-session/index.js

@@ -7,7 +7,7 @@ import { announceStatus } from '../shared/status.js';
 import { readCavemanDefault } from '../shared/plugin-settings.js';
 const CAVERN_DIR = dirname(fileURLToPath(import.meta.url));
 // Upstream ships one skill per register: default, ultracave, megacave.
-const RULE_FILES = { lite: 'rule.md', full: 'rule.md', ultra: 'rule-ultra.md', 'wenyan-lite': 'rule-wenyan.md', 'wenyan-full': 'rule-wenyan.md', 'wenyan-ultra': 'rule-wenyan.md' };
+const RULE_FILES = { lite: 'rule.md', full: 'rule.md', ultra: 'rule-ultra.md', 'megacave-lite': 'rule-megacave.md', 'megacave-full': 'rule-megacave.md', 'megacave-ultra': 'rule-megacave.md' };
 const DEFAULT_MODE = 'off';
 function buildInstruction(mode) {
     const name = RULE_FILES[mode] ?? RULE_FILES.full;
@@ -62,7 +62,7 @@ export default function cavemanSessionExtension(pi) {
                 return;
             }
             if (!setMode(arg, ctx)) {
-                ctx?.ui?.notify?.('Usage: /caveman [lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off|status]', 'warning');
+                ctx?.ui?.notify?.('Usage: /caveman [lite|full|ultra|megacave-lite|megacave-full|megacave-ultra|off|status]', 'warning');
             }
         },
     });

package/dist/extensions/caveman-session/rule-ultra.md

@@ -0,0 +1,63 @@
+---
+name: ultracave
+description: >
+  Caveman at maximum compression: fragments, one word when one word is enough,
+  each fact once. Invoke only with /ultracave or /caveman ultra. Stays on until
+  "stop caveman" or "normal mode".
+disable-model-invocation: true
+---
+
+# ultracave
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die. Then cut again.
+
+Ultracave is caveman with the grammar stripped. Payload only.
+
+## Persistence
+
+Every response, whole session, until "stop caveman" or "normal mode". Unsure? Still on. `/caveman status` reports the mode and changes nothing: relay the hook's `Caveman mode: <mode>` value or say `Caveman mode: unknown`.
+
+## Floor
+
+Never cut: code, commands, paths, API names, error strings (verbatim). not/never/no/only/except. Numbers and units. The user's language. One term per thing. No invented abbreviations, no arrows.
+
+## Rules
+
+### 1. Fragments
+
+Drop articles, copulas, connectives when order stays clear.
+
+Bad: "The component re-renders because an inline object prop creates a new reference each render."
+Good: "Inline object prop, new ref, re-render. `useMemo`."
+
+### 2. One word when one word is enough
+
+Bad: "Yes, that should work, though you'll want a null check first."
+Good: "Yes. Null check first."
+
+### 3. Each fact once
+
+No restating, no summary after a list.
+
+Good: "Pool reuses open DB connections. No per-request handshake."
+
+### 4. Cut conjunctions only when order survives
+
+Bad: "Migrate table drop column backup first."
+Good: "Back up first. Then migrate: drops column."
+
+### 5. Tool runs
+
+One line in, one line out. Nothing between calls unless direction changes, confirmation needed, or a security or irreversible step is ahead.
+
+### 6. Never perform
+
+No prefix, no announcement, no mangled verbs for flavor. Fragment not shorter than the sentence? Use the sentence.
+
+## When to break the rules
+
+Plain prose, then resume: security warning. Irreversible action, confirm first. Any fragment with two readings. User confused. Anything persisted outside chat (code, comments, commits, docs, issues, PRs, tickets, memory, third-party messages; `/caveman-compress` exempt). Harness asks for a status line.
+
+## Pre-send check
+
+Two readings? Full sentence. Negations present? Payload verbatim? Flavor word? Cut.

package/dist/extensions/caveman-session/rule.md

@@ -0,0 +1,79 @@
+---
+name: caveman
+description: >
+  Ultra-compressed communication mode that cuts output tokens while keeping
+  technical accuracy. Levels: lite, full, ultra and the megacave variants. Use for
+  /caveman, "caveman mode", "talk like caveman", "be brief" or "less tokens".
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+Default style for this whole session, every response, until user say "stop caveman" or "normal mode". Keep terse on long sessions no filler drift.
+
+Default: **full**. Switch: `/caveman lite|full|ultra|megacave-lite|megacave-full|megacave-ultra|off`.
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). No tool-call narration, no decorative tables/emoji, no dumping long raw error logs unless asked quote shortest decisive line. Standard well-known tech acronyms OK (DB/API/HTTP); never invent new abbreviations (cfg/impl/req/res/fn) tokenizer split them same as full word: zero token saved, reader still decode. Full word cheaper AND clearer. No causal arrows (→) either own token, save nothing. Technical terms exact. Code blocks unchanged. Errors quoted exact.
+
+Never drop not/never/no/only/except flip meaning worse than any token saved. Numbers, units exact.
+
+Never ADD word to sound caveman. Compression only style never grow output. No inserted pronoun or copula to fake broken grammar: "when it not" cost one token more than "when not" and say same thing. Keep correct verb form when correct form cost same "sees" one token, "see" one token, so mangle buy nothing and read worse. Same rule as abbreviations and arrows: if caveman phrasing not shorter than plain phrasing, use plain.
+
+Clarity register: mix ASD-STE100 Simplified Technical English into caveman, always. One idea per sentence. Sentence short, target 20 words max. Active voice. Present tense where true. One word one meaning: same term for same thing every time, no synonym rotation. Instruction = imperative: "Run X", not "X should be run". Noun cluster 3 words max. Pronoun only with one clear referent, else repeat noun. Caveman cut filler; STE keep what make meaning unambiguous. Conflict between them → clarity win.
+
+Tool calls: fire direct. No preamble, plan, or progress note before or between calls. After result: next call direct or final answer never announce next call. Text before call only to clarify, warn security/irreversible, or resolve ambiguity.
+
+Follow explicit reply-language instructions from the user or project. Otherwise preserve the user's dominant language. Never switch because of example text or multilingual context elsewhere. Compress the style, not the language. Every emitted line in that language openings, pre-tool status lines, all not just final reply. ALWAYS keep technical terms, code, API names, CLI commands, commit-type keywords (feat/fix/...), and exact error strings verbatim unless user explicitly ask for translation.
+
+Ownership: caveman owns reply compression, so project or host prose rules that set article use, sentence length, or filler never override it. Treat those as applying to persisted artifacts instead: code, comments, commits, docs, and issue text. Any project rule naming caveman or tersio directly wins over both.
+
+'Drop articles' = article languages only. Where small markers carry case/role (particles, postpositions), keep them grammar, not filler; compress politeness/filler instead.
+
+Answer directly in this style. Skip "caveman mode on", "me caveman think", "Caveman:" prefix or recap redundant with the reply itself. No normal answer plus caveman duplicate. User ask what mode is → say so plainly.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+## Intensity
+
+| Level | What change |
+|-------|------------|
+| **lite** | No filler/hedging. Keep articles + full sentences. Professional but tight |
+| **full** | Drop articles, fragments OK, short synonyms. Classic caveman. No tool-call narration, no decorative tables/emoji, no long raw error-log dumps unless asked. Standard acronyms OK; no invented abbreviations |
+
+Example "Why React component re-render?"
+- lite: "Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`."
+- full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
+
+Example "Explain database connection pooling."
+- lite: "Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake overhead."
+- full: "Pool reuse open DB connections. No new connection per request. Skip handshake overhead."
+
+## Auto-Clarity
+
+Drop caveman when:
+- Security warnings
+- Irreversible action confirmations
+- Multi-step sequences where fragment order or omitted conjunctions risk misread
+- Compression itself creates technical ambiguity (e.g., `"migrate table drop column backup first"` order unclear without articles/conjunctions)
+- User asks to clarify or repeats question
+
+Resume caveman after clear part done.
+
+Example shows FORMAT only write warning in session language, not example's.
+
+Example destructive op:
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+> ```sql
+> DROP TABLE users;
+> ```
+> Caveman resume. Verify backup exist first.
+
+## Boundaries
+
+Persisted outside chat: write normal prose code, comments, commits, docs, issue/PR/MR/defect/ticket/bug-report text, memory files, third-party messages (/caveman-compress exempt). "Open a defect" or "file a bug" mean the same as "open issue": body go to other humans, so body normal English. "stop caveman" or "normal mode": revert. Level persist until changed or session end.

package/{extensions → dist/extensions}/combo-toggle/index.js

@@ -10,10 +10,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import path from 'node:path';
 import { existsSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { activeModesSummary, COMBO_LEVELS, getSharedComboState, hasModeState, normalizeComboLevel, reconcileSharedComboEntries, sessionEntries, setSharedComboLevel, setSharedComboListener, setSharedComboMode, systemPromptIncludes, } from '../shared/session-state.js';
+import { activeModesSummary, COMBO_LEVELS, getSharedComboState, hasModeState, normalizeComboLevel, reconcileSharedComboEntries, sessionEntries, setSharedComboLevel, setSharedComboListener, setSharedComboModes, systemPromptIncludes, } from '../shared/session-state.js';
 import { hostSelect, injectPromptText, onHostEvent, setExtensionLabel } from '../shared/host.js';
 import { announceStatus } from '../shared/status.js';
-import { isComboSetupComplete, readComboDefault, readPonytailDefault, saveComboSetup, } from '../shared/plugin-settings.js';
+import { isComboSetupComplete, readCavemanDefault, readComboDefault, readPluginSettings, readPonytailDefault, readRtkDefault, saveComboSetup, } from '../shared/plugin-settings.js';
 import { findHoistedPackage, isPiProcess } from '../lib/utils.js';
 const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PONYTAIL_FALLBACK_INTENSITY = {
@@ -45,6 +45,8 @@ export default function comboToggleExtension(pi) {
     setExtensionLabel(pi, 'Combo session toggle (all 3 add-ons)');
     let setupPrompted = false;
     let lastInjected = undefined;
+    // opencode has no UI event stream, so only its empty branch reconciles.
+    const OPENCODE = pi.hostId === 'opencode';
     // Siblings restore from these entries, so the fallback must write them too.
     function persistPreset(level) {
         const modes = COMBO_LEVELS[level];
@@ -53,20 +55,41 @@ export default function comboToggleExtension(pi) {
         pi.appendEntry?.('ponytail-mode', { mode: modes.ponytail });
         pi.appendEntry?.('combo-level', { level });
     }
-    function reconcile(ctx) {
-        if (!ctx?.hasUI)
+    function restoreConfiguredDefaults() {
+        const settings = readPluginSettings();
+        const hasModeDefaults = ['cavemanDefault', 'rtkDefault', 'ponytailDefault'].some((key) => key in settings);
+        const combo = readComboDefault();
+        const preset = COMBO_LEVELS[combo];
+        const modes = hasModeDefaults
+            ? { caveman: readCavemanDefault(), rtk: readRtkDefault() ? 'on' : 'off', ponytail: readPonytailDefault() }
+            : preset;
+        setSharedComboModes(modes);
+        if (modes.caveman === 'off' && modes.rtk === 'off' && modes.ponytail === 'off')
+            return;
+        pi.appendEntry?.('caveman-mode', { mode: modes.caveman });
+        pi.appendEntry?.('rtk-mode', { enabled: modes.rtk === 'on' });
+        pi.appendEntry?.('ponytail-mode', { mode: modes.ponytail });
+        if (preset && modes.caveman === preset.caveman && modes.rtk === preset.rtk && modes.ponytail === preset.ponytail) {
+            pi.appendEntry?.('combo-level', { level: combo });
+        }
+    }
+    function reconcile(ctx, resetEmpty = false) {
+        if (!ctx?.hasUI && !(resetEmpty && OPENCODE))
             return getSharedComboState();
-        return reconcileSharedComboEntries(sessionEntries(ctx));
+        const entries = sessionEntries(ctx);
+        if (!resetEmpty && entries.length === 0)
+            return getSharedComboState();
+        return reconcileSharedComboEntries(entries);
     }
     function listen(ctx) {
         if (!ctx?.hasUI)
             return;
         setSharedComboListener('combo', (state) => { announceStatus(ctx); return state; });
     }
-    function track(ctx) {
+    function track(ctx, resetEmpty = false) {
         listen(ctx);
-        if (ctx?.hasUI)
-            reconcile(ctx);
+        if (ctx?.hasUI || (resetEmpty && OPENCODE))
+            reconcile(ctx, resetEmpty);
     }
     pi.registerCommand?.('combo', {
         description: 'Toggle all 3 OMP add-ons at once. Usage: /combo <off|medium|balanced|max|status>',
@@ -113,26 +136,13 @@ export default function comboToggleExtension(pi) {
         }
     }
     pi.on('session_start', async (_event, ctx) => {
-        track(ctx);
-        await runFirstRunSetup(ctx);
-        // The configured default applies only when no persisted mode state exists.
+        track(ctx, true);
+        if (!isComboSetupComplete() && ctx?.hasUI && ctx.ui?.select)
+            await runFirstRunSetup(ctx);
+        // The configured defaults apply when a fresh session has no persisted mode state.
         const entries = sessionEntries(ctx);
-        const persisted = hasModeState(entries);
-        if (getSharedComboState().level === 'off' && !persisted) {
-            const fallback = readComboDefault();
-            if (fallback !== 'off') {
-                persistPreset(fallback);
-                setSharedComboLevel(fallback);
-            }
-        }
-        // No sibling restores a standalone ponytail default, so apply it here; skip it when the active preset already writes the same mode.
-        if (!entries.some((e) => e?.type === 'custom' && e.customType === 'ponytail-mode')) {
-            const ponytailFallback = readPonytailDefault();
-            if (ponytailFallback !== 'off' && ponytailFallback !== getSharedComboState().ponytail) {
-                pi.appendEntry?.('ponytail-mode', { mode: ponytailFallback });
-                setSharedComboMode('ponytail', ponytailFallback);
-            }
-        }
+        if (!hasModeState(entries) && (ctx?.hasUI || OPENCODE))
+            restoreConfiguredDefaults();
         // Announced last, so any default above is reflected.
         announceStatus(ctx);
     });

package/dist/extensions/headroom-session/index.js

@@ -0,0 +1,93 @@
+// /headroom session toggle. Headroom is a machine-level add-on, so this extension mirrors the stored per-agent flags and delegates every state change to the CLI.
+import { HEADROOM_INSTALL_HINT, headroomAgentState, headroomCapability, headroomProxyUp, headroomStatusFor, readHeadroomConfig, setHeadroomStatus, } from '../shared/headroom.js';
+import { onHostEvent, setExtensionLabel } from '../shared/host.js';
+import { announceStatus } from '../shared/status.js';
+/** The host's own key in the per-agent Headroom flags. */
+function agentOf(pi) {
+    return pi.hostId ?? 'omp';
+}
+function statusText(agent, status) {
+    const manual = headroomCapability(agent) === 'manual';
+    const port = readHeadroomConfig().port;
+    if (status === 'down')
+        return `Headroom is on for ${agent}${manual ? ' (manual base URL)' : ''}, but the proxy does not answer. Restart it with: headroom proxy --port ${port}`;
+    if (status === 'manual')
+        return `Headroom is on for ${agent} (manual base URL). Point the model base URL at the proxy.`;
+    if (status === 'on')
+        return `Headroom is on for ${agent}.`;
+    return `Headroom is off for ${agent}.`;
+}
+export default function headroomSessionExtension(pi) {
+    setExtensionLabel(pi, 'Headroom session toggle');
+    const agent = agentOf(pi);
+    let shaperWarned = false;
+    // Reads the stored flags, then probes the proxy only when this agent is wired. Off installs never touch the network.
+    async function refresh(ctx) {
+        const config = readHeadroomConfig();
+        const state = headroomAgentState(config, agent);
+        // No segment until the user opts in, so a machine that merely has Headroom installed keeps the old status line.
+        if (!config.support || !state.enabled) {
+            setHeadroomStatus(null);
+            return null;
+        }
+        const up = await headroomProxyUp(config.port);
+        const status = headroomStatusFor(config, agent, up);
+        setHeadroomStatus(status);
+        // Caveman already owns terse output, so two shapers would fight over one prompt.
+        if (!shaperWarned && process.env.HEADROOM_OUTPUT_SHAPER && process.env.HEADROOM_OUTPUT_SHAPER !== '0') {
+            shaperWarned = true;
+            ctx?.ui?.notify?.(`HEADROOM_OUTPUT_SHAPER is set while Caveman is active. Unset it: one prompt owner only.`, 'warning');
+        }
+        return status;
+    }
+    async function runCli(action, ctx) {
+        if (typeof pi.exec !== 'function') {
+            ctx?.ui?.notify?.(`Run in a shell: tersio headroom ${action} --agent ${agent}`, 'warning');
+            return;
+        }
+        try {
+            const result = await pi.exec('tersio', ['headroom', action, '--agent', agent], { cwd: ctx?.cwd ?? pi.cwd });
+            const text = [result.stdout, result.stderr].map((part) => part.trim()).filter(Boolean).join('\n');
+            ctx?.ui?.notify?.(text || `tersio headroom ${action} exited ${result.code}`, result.code === 0 ? 'info' : 'warning');
+        }
+        catch (e) {
+            ctx?.ui?.notify?.(`tersio headroom ${action} failed (${e.message}). Run it in a shell.`, 'warning');
+        }
+        await refresh(ctx);
+        announceStatus(ctx);
+    }
+    pi.registerCommand?.('headroom', {
+        description: 'Toggle the Headroom compression proxy for this agent',
+        handler: async (args, ctx) => {
+            const arg = String(args || '').trim().toLowerCase();
+            if (!arg || arg === 'status') {
+                const status = await refresh(ctx);
+                ctx?.ui?.notify?.(status === null
+                    ? `Headroom is not installed — ${HEADROOM_INSTALL_HINT}`
+                    : statusText(agent, status), 'info');
+                announceStatus(ctx);
+                return;
+            }
+            if (['on', 'enable', 'enabled', 'true'].includes(arg)) {
+                await runCli('enable', ctx);
+                return;
+            }
+            if (['off', 'disable', 'disabled', 'false'].includes(arg)) {
+                await runCli('disable', ctx);
+                return;
+            }
+            ctx?.ui?.notify?.('Usage: /headroom [on|off|status]', 'warning');
+        },
+    });
+    // Start, resume, branch, and compaction all land here, so every session type shows the state.
+    pi.on('session_start', async (_event, ctx) => {
+        await refresh(ctx);
+        announceStatus(ctx);
+    });
+    for (const event of ['session_branch', 'session_tree', 'session_switch', 'session_compact']) {
+        onHostEvent(pi, event, async (_event, ctx) => {
+            await refresh(ctx);
+            announceStatus(ctx);
+        });
+    }
+}

package/{extensions → dist/extensions}/lib/utils.js

@@ -19,7 +19,20 @@ export function homeDir() {
 }
 export const RTK_RELEASE_API = 'https://api.github.com/repos/rtk-ai/rtk/releases/latest';
 export const CAVEMAN_REMOTE_ULTRA = 'https://raw.githubusercontent.com/JuliusBrussee/caveman/main/skills/ultracave/SKILL.md';
-export const CAVEMAN_REMOTE_WENYAN = 'https://raw.githubusercontent.com/JuliusBrussee/caveman/main/skills/megacave/SKILL.md';
+export const CAVEMAN_REMOTE_MEGACAVE = 'https://raw.githubusercontent.com/JuliusBrussee/caveman/main/skills/megacave/SKILL.md';
+// A fetch that returns an error page or a truncated body must not reach the extension tree.
+export function ruleBodyProblem(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return 'empty body';
+    if (/^\s*<(!doctype|html)/i.test(trimmed))
+        return 'HTML page, not markdown';
+    if (/^\s*404\b/im.test(trimmed))
+        return 'upstream 404 page';
+    if (trimmed.length < 800)
+        return `truncated (${trimmed.length} chars)`;
+    return null;
+}
 const RTK_PLATFORM_SPECS = {
     'win32/x64': { triple: 'x86_64-pc-windows-msvc', ext: '.zip', binary: 'rtk.exe' },
     'linux/x64': { triple: 'x86_64-unknown-linux-musl', ext: '.tar.gz', binary: 'rtk' },
@@ -55,6 +68,18 @@ export function resolveHostBinary(name, managedDir = path.join(homeDir(), '.bun'
 export function rtkPlatformSpec(platform = process.platform, arch = process.arch) {
     return RTK_PLATFORM_SPECS[`${platform}/${arch}`] || null;
 }
+// Walk up to the nearest package.json; identical for the source and compiled trees.
+export function findPackageRoot(fromDir) {
+    let dir = fromDir;
+    for (;;) {
+        if (existsSync(path.join(dir, 'package.json')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error('package root not found');
+        dir = parent;
+    }
+}
 // The 3xx+location redirect rule shared by httpsGet/httpsDownload.
 function redirectNext(res, url) {
     if (res.statusCode !== undefined && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {

package/dist/extensions/shared/headroom.js

@@ -0,0 +1,131 @@
+// Headroom is a local proxy that compresses input-side context. Agent-neutral core: one adapter row per agent, no agent name in the logic below.
+import { existsSync, readFileSync } from 'node:fs';
+import { patchPluginSettings, readPluginSettings } from './plugin-settings.js';
+export const HEADROOM_AGENTS = ['omp', 'pi', 'opencode'];
+export const HEADROOM_DEFAULT_PORT = 8787;
+/** Lowest Headroom the spike verified. */
+export const HEADROOM_MIN_VERSION = '0.40.0';
+/** Newest Headroom the spike verified; a newer one only warns. */
+export const HEADROOM_TESTED_VERSION = '0.40.0';
+/** What to say when the binary is absent. Headroom ships with the add-ons, so the fix is a Tersio install, not a hand-run Python tool. */
+export const HEADROOM_INSTALL_HINT = 'run `tersio install` (or `tersio update`) to add the bundled Headroom add-on';
+/** Native or manual, from the spike's `wrap` table. */
+export function headroomCapability(agent) {
+    return agent === 'pi' ? 'manual' : 'native';
+}
+export function isHeadroomAgent(value) {
+    return typeof value === 'string' && HEADROOM_AGENTS.includes(value);
+}
+/** `headroom 0.40.0` and a bare `0.40.0` both parse. */
+export function parseHeadroomVersion(raw) {
+    const match = /\d+\.\d+\.\d+/.exec(String(raw ?? ''));
+    return match ? match[0] : null;
+}
+export function compareVersions(a, b) {
+    const left = a.split('.').map((part) => Number.parseInt(part, 10) || 0);
+    const right = b.split('.').map((part) => Number.parseInt(part, 10) || 0);
+    for (let i = 0; i < 3; i += 1) {
+        const delta = (left[i] ?? 0) - (right[i] ?? 0);
+        if (delta !== 0)
+            return delta > 0 ? 1 : -1;
+    }
+    return 0;
+}
+export function headroomVersionIssue(version) {
+    if (!version)
+        return 'unknown';
+    if (compareVersions(version, HEADROOM_MIN_VERSION) < 0)
+        return 'old';
+    if (compareVersions(version, HEADROOM_TESTED_VERSION) > 0)
+        return 'newer';
+    return 'ok';
+}
+function asAgentState(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const value = raw;
+    return { enabled: value.enabled === true, wrappedByTersio: value.wrappedByTersio === true };
+}
+function asAgentMap(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!isHeadroomAgent(key))
+            continue;
+        const state = asAgentState(value);
+        if (state)
+            out[key] = state;
+    }
+    return out;
+}
+export function readHeadroomConfig() {
+    const settings = readPluginSettings();
+    const port = Number(settings.headroomPort);
+    return {
+        support: settings.headroomSupport === true,
+        port: Number.isInteger(port) && port > 0 && port < 65536 ? port : HEADROOM_DEFAULT_PORT,
+        agents: asAgentMap(settings.headroom),
+    };
+}
+export function headroomAgentState(config, agent) {
+    return config.agents[agent] ?? { enabled: false, wrappedByTersio: false };
+}
+/** The one write path for the kill switch, the port, and the per-agent flags. Keeps unrelated settings keys intact. */
+export function writeHeadroomConfig(config) {
+    return patchPluginSettings({ headroomSupport: config.support, headroomPort: config.port, headroom: config.agents });
+}
+export function headroomProxyUrl(port = HEADROOM_DEFAULT_PORT) {
+    return `http://127.0.0.1:${port}`;
+}
+/** Fails open: a dead or absent proxy reports false, never an exception. */
+export async function headroomProxyUp(port = HEADROOM_DEFAULT_PORT, timeoutMs = 400) {
+    try {
+        const res = await fetch(`${headroomProxyUrl(port)}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export function headroomStatusSegment(state) {
+    if (state === null)
+        return null;
+    if (state === 'on')
+        return '🗜️ headroom=ON';
+    if (state === 'manual')
+        return '🗜️ headroom=ON (manual)';
+    if (state === 'down')
+        return '🗜️ headroom=DOWN';
+    return '🗜️ headroom=OFF';
+}
+// One process paints one status line, so a module mirror is enough. null means "no Headroom in this install".
+let status = null;
+export function getHeadroomStatus() {
+    return status;
+}
+export function setHeadroomStatus(next) {
+    status = next;
+}
+/** The status for one agent, from its stored flags. `off` when support is off or nothing is wired. */
+export function headroomStatusFor(config, agent, proxyUp) {
+    if (!config.support)
+        return 'off';
+    const state = headroomAgentState(config, agent);
+    if (!state.enabled)
+        return 'off';
+    return proxyUp ? (headroomCapability(agent) === 'manual' ? 'manual' : 'on') : 'down';
+}
+/** True when the agent's config file already carries a Headroom marker. */
+export function headroomWiringPresent(files) {
+    for (const file of files) {
+        try {
+            if (!existsSync(file))
+                continue;
+            if (/headroom|127\.0\.0\.1:8787/i.test(readFileSync(file, 'utf8')))
+                return true;
+        }
+        catch { /* unreadable counts as unwired */ }
+    }
+    return false;
+}

package/{extensions → dist/extensions}/shared/plugin-settings.js

@@ -43,7 +43,7 @@ export function readPluginSettings() {
     return readSettingsFile() ?? legacyOmpSettings() ?? {};
 }
 const COMBO_LEVELS = new Set(['off', 'medium', 'balanced', 'max']);
-const CAVEMAN_MODES = new Set(['off', 'lite', 'full', 'ultra', 'wenyan', 'wenyan-lite', 'wenyan-full', 'wenyan-ultra']);
+const CAVEMAN_MODES = new Set(['off', 'lite', 'full', 'ultra', 'megacave', 'megacave-lite', 'megacave-full', 'megacave-ultra', 'wenyan', 'wenyan-lite', 'wenyan-full', 'wenyan-ultra']);
 const PONYTAIL_MODES = new Set(['off', 'lite', 'full', 'ultra']);
 function readStringDefault(key, valid) {
     const raw = readPluginSettings()[key];

package/{extensions → dist/extensions}/shared/session-state.js

@@ -9,10 +9,12 @@ export const COMBO_LEVELS = Object.freeze({
     max: Object.freeze({ level: 'max', caveman: 'ultra', rtk: 'on', ponytail: 'ultra' }),
 });
 const MODE_VALUES = {
-    caveman: new Set(['off', 'lite', 'full', 'ultra', 'wenyan', 'wenyan-lite', 'wenyan-full', 'wenyan-ultra']),
+    caveman: new Set(['off', 'lite', 'full', 'ultra', 'megacave', 'megacave-lite', 'megacave-full', 'megacave-ultra', 'wenyan', 'wenyan-lite', 'wenyan-full', 'wenyan-ultra']),
     rtk: new Set(['off', 'on']),
     ponytail: new Set(['off', 'lite', 'full', 'ultra']),
 };
+// Upstream renamed wenyan to megacave and kept the old spelling as an alias.
+const CAVEMAN_LEGACY_PREFIX = /^wenyan/;
 const MODE_ENTRY_TYPES = {
     'caveman-mode': 'caveman',
     'rtk-mode': 'rtk',
@@ -29,7 +31,10 @@ export function normalizeMode(name, value) {
     const mode = String(value ?? '').trim().toLowerCase();
     if (!MODE_VALUES[name]?.has(mode))
         return null;
-    return name === 'caveman' && mode === 'wenyan' ? 'wenyan-full' : mode;
+    if (name !== 'caveman')
+        return mode;
+    const canonical = mode.replace(CAVEMAN_LEGACY_PREFIX, 'megacave');
+    return canonical === 'megacave' ? 'megacave-full' : canonical;
 }
 export function deriveLevel(modes) {
     for (const level of Object.keys(COMBO_LEVELS)) {
@@ -127,6 +132,13 @@ export function setSharedComboMode(name, value) {
     // Derive the level from the final triplet so a redundant same-value write cannot strand a matching preset at 'custom' and drop the combo bar.
     return publish(normalizedState(modes));
 }
+export function setSharedComboModes(modes) {
+    return publish(normalizedState({
+        caveman: normalizeMode('caveman', modes.caveman) || 'off',
+        rtk: normalizeMode('rtk', modes.rtk) || 'off',
+        ponytail: normalizeMode('ponytail', modes.ponytail) || 'off',
+    }));
+}
 export function reconcileSharedComboEntries(entries) {
     let modes = { ...COMBO_LEVELS.off };
     if (Array.isArray(entries)) {