@bglocation/tune-context 2.0.0 → 2.1.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "bglocation",
-  "description": "Context-engineering tooling for Claude Code from bglocation — token-saving doctrine, configurators and semantic-search wiring.",
+  "description": "Context-engineering tooling for Claude Code from bglocation \u2014 token-saving doctrine, configurators and semantic-search wiring.",
   "owner": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"
@@ -10,7 +10,7 @@
       "name": "tune-context",
       "source": "./",
       "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-      "version": "2.0.0",
+      "version": "2.1.0",
       "author": {
         "name": "Szymon Walczak",
         "url": "https://bglocation.dev"

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "tune-context",
   "displayName": "tune-context",
   "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,88 @@ All notable changes to `@bglocation/tune-context` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] — 2026-07-26
+
+### Changed
+
+- **The context reminder no longer goes silent after a badly-timed crossing.**
+  It now fires a second and final time at **twice** the threshold (240k by
+  default, or 2× `TUNE_CONTEXT_REMIND_TOKENS`). The reminder tells Claude to stay
+  quiet mid-task — correctly, since only the model can see whether a refactor is
+  half-finished — but fire-once was consumed the moment the *model* read it, and
+  re-arming required a compaction. Measured on one real session: it fired at
+  ~166k, Claude stayed silent mid-task, and nothing spoke again until ~346k, 2.9×
+  the threshold. There is deliberately no third notice: this is the only hook
+  that *adds* tokens to the context it exists to shrink, so the cost stays
+  bounded at one extra note per cycle.
+- The text sent to the model now states plainly that the user cannot see the
+  reminder, so silence means they never learn about it.
+
+### Added
+
+- A `systemMessage` alongside the existing `additionalContext`, carrying the size
+  and `/compact` in one line. **Best-effort only** — see below.
+
+### Notes on measurement
+
+The intended fix was to show the user a line directly, removing the model's
+monopoly on whether they hear about a heavy session at all. A two-marker probe
+settled what the docs could not:
+
+- `systemMessage` does **not** render for `UserPromptSubmit` (measured in the
+  VSCode extension), despite the settings schema promising "Display a message to
+  the user (all hooks)". The probe's `additionalContext` marker did arrive, which
+  is what makes this a clean negative rather than a probe that failed to load.
+- `systemMessage` does **not** enter the model's context, so it costs no tokens.
+
+It is therefore emitted but depended on by nothing, and other clients were not
+measured. The escalation above is what actually closes the gap.
+
+The same measurement caught a change that would have made things worse: the
+planned model-facing text said "the user has already been shown this, do not
+repeat it". Shipped unmeasured, it would have suppressed the only channel that
+works.
+
+## [2.0.1] — 2026-07-26
+
+### Fixed
+
+- **The npm-installed CLI did nothing at all in 2.0.0.** `npm i -g` puts the
+  `bin` entry on PATH as a symlink named `tune-context`, with no extension, but
+  2.0.0's entry-point guard tested `process.argv[1].endsWith('tune-context.mjs')`.
+  That is false for the symlink, so `main()` never ran: every command —
+  `init`, `--version`, `--help` — exited 0 without printing a byte or touching a
+  file. Now compares resolved real paths, which holds for the npm symlink, a
+  direct `.mjs` invocation, the extensionless `bin/tune-context` wrapper (still
+  exactly one run, not two) and `import` from a test.
+- Only the npm channel was affected. Plugin installs call `bin/tune-context`,
+  which invokes `main()` itself, and the hooks are always registered by literal
+  path — both kept working.
+
+### Testing
+
+- The suite spawned `.../bin/tune-context.mjs` everywhere, which is the one shape
+  no user ever runs; that is why 119 green tests said nothing about a completely
+  dead CLI. Added a test that installs the binary the way npm does — through an
+  extensionless symlink — and asserts a silent exit 0 is a failure.
+
+### Upgrading from 2.0.0 (npm channel)
+
+Upgrading is not enough on its own. If you ran `tune-context init` under 2.0.0
+it exited 0 and looked like it worked, but **nothing was installed** — so
+`~/.claude/hooks/context-reminder.mjs` is missing and the `UserPromptSubmit`
+hook was never registered. Re-run it after upgrading:
+
+```bash
+npm i -g @bglocation/tune-context@2.0.1
+tune-context --version    # must print 2.0.1 — silence means the upgrade did not take
+tune-context init
+```
+
+The `init` is idempotent and additive: it never removes a hook or permission
+entry, and never touches content outside the managed blocks. Plugin-only
+installs were unaffected and need nothing.
+
 ## [2.0.0] — 2026-07-25
 
 Three hardening epics' worth of work plus the first new feature since 1.0: a

package/README.md

@@ -170,15 +170,21 @@ supplies the missing measurement: it reads the tail of the session transcript,
 sums the tokens actually re-sent, and once that passes **120,000** it injects a
 single short note suggesting `/compact`.
 
-- **Once per crossing, not per prompt.** The note itself costs tokens on the turn
-  it appears in, so it re-arms only after a compaction-sized drop. Measured on a
-  12.6-hour session: 4 reminders total.
-- **The model picks the moment.** The reminder tells Claude to stay quiet
-  mid-task and raise it when the thread closes — the hook can measure size, but
-  only the model can see whether you're mid-refactor.
+- **The note goes to Claude, not to your screen.** Hooks can only reach you
+  through the model — a `systemMessage` on this event was measured and does not
+  render — so what you actually see is Claude bringing it up in its reply.
+- **The model picks the moment.** The note tells Claude to stay quiet mid-task
+  and raise it at the first natural break: the hook can measure size, but only
+  the model can see whether you're mid-refactor.
+- **Twice per crossing at most.** Once at the threshold, once more at **240,000**
+  if the context keeps growing — because a note that lands mid-task can be
+  correctly absorbed and then forgotten. Measured on one session: it fired at
+  166k, Claude stayed silent, and nothing spoke again until 346k. The second
+  notice halves that blind spot; there is deliberately no third.
 - **Raise it for a large context window:** `export TUNE_CONTEXT_REMIND_TOKENS=400000`.
   120k is ~60% of a standard 200k window; the transcript doesn't record the window
-  size, so this can't be auto-scaled.
+  size, so this can't be auto-scaled. Both levels scale with the override — the
+  second notice is always at twice the threshold.
 - **Turn it off:** delete the `UserPromptSubmit` entry from `settings.json`.
 
 Depth lives in the `phase-workflow` and `token-efficiency` skills (both installed

package/bin/tune-context.mjs

@@ -16,7 +16,7 @@
 // "No model in the loop" is the feature here, not a gap — but the gap has to be
 // stated, or a CLI user cannot know what they did not get. Run the skill
 // (/tune-context) for the full pass.
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { claudeDirs, detectExistingConfig, detectMcpServers, detectRejectedMcpServers, detectStack } from '../cli/detect.mjs';
@@ -173,11 +173,37 @@ export function main() {
   }
 }
 
-// Guarded so importing this file for parseArgs/main (tests, or the
-// extensionless bin/tune-context wrapper) never runs the CLI as a side
-// effect of the import — only direct invocation of THIS file does. The
-// wrapper has a different argv[1] (its own path), so it calls main()
-// explicitly instead of relying on this check.
-if (process.argv[1] && process.argv[1].endsWith('tune-context.mjs')) {
+/**
+ * True only when THIS file is the process entry point, so importing it for
+ * parseArgs/main (tests, or the extensionless bin/tune-context wrapper) never
+ * runs the CLI as a side effect of the import.
+ *
+ * Deliberately NOT a filename-suffix test on argv[1]. npm installs the
+ * package.json `bin` entry as a symlink named `tune-context` — no extension —
+ * so `argv[1].endsWith('tune-context.mjs')` was false for every real npm-channel
+ * invocation: main() never ran and the CLI exited 0 in total silence. That
+ * shipped in 2.0.0 (see the symlink test in test/bin-tune-context.test.mjs);
+ * the whole suite missed it because tests and smoke:init both spawn the full
+ * `.../bin/tune-context.mjs` path, which is the one shape a user never uses.
+ *
+ * Comparing resolved real paths holds for all four shapes: direct `.mjs`
+ * invocation, the npm symlink (resolves THROUGH the link to this file), the
+ * extensionless wrapper (a different real path, so this stays false and the
+ * wrapper's own main() call is the single entry — no double run), and `import`
+ * from a test (argv[1] is the test runner). realpathSync on both sides also
+ * survives a symlinked package dir, as `npm link` and nvm both produce.
+ */
+function isEntryPoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    // argv[1] can name something unresolvable (deleted, or a bare `-`); a CLI
+    // that cannot identify its own entry point must stay silent, not crash.
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
   main();
 }

package/hooks/context-reminder.mjs

@@ -137,31 +137,94 @@ function pruneState(state, now) {
   return state;
 }
 
+// TASK-080 fallback, chosen by the PO after measurement killed the preferred
+// design (see userNotice()): a SECOND and final notice at twice the threshold.
+//
+// The problem it solves is measured, not hypothetical. Fire-once is consumed
+// when the model reads the reminder, and the reminder itself tells the model to
+// stay quiet mid-task — correctly, since only it can see whether a refactor is
+// half-finished. In session c9329adb that combination cost the user everything
+// between ~166k and ~346k: one firing, silently absorbed, and no re-arm until a
+// compaction that nobody had suggested.
+//
+// Why 2x and not "every +N tokens": periodic nagging would break the rule this
+// hook lives under — it is the only hook that ADDS tokens to the context it
+// exists to shrink. One extra notice per cycle is a bounded, one-off cost that
+// halves the worst-case blind spot; an unbounded series is the feature eating
+// itself. Deliberately NOT a third level.
+const ESCALATION_MULTIPLIER = 2;
+
+/** How many notices this session has earned at `total`: 0, 1 or 2. */
+function levelFor(total, threshold) {
+  if (total >= threshold * ESCALATION_MULTIPLIER) return 2;
+  if (total >= threshold) return 1;
+  return 0;
+}
+
 /**
  * Pure decision: given the previous reading for this session and the current
  * one, should a reminder fire, and what is the session's next state?
  *
- * Fires ONCE per crossing, not on every prompt above the threshold. A reminder
- * costs tokens on the very prompt it appears in, so a context-efficiency tool
- * that nagged every turn would be spending the thing it claims to save.
+ * Fires at most TWICE per crossing (threshold, then 2x threshold), never on
+ * every prompt above the line. A reminder costs tokens on the very prompt it
+ * appears in, so a context-efficiency tool that nagged every turn would be
+ * spending the thing it claims to save.
  */
 export function decide(prev, total, threshold) {
-  let fired = prev?.fired === true;
+  // `fired: true` is how state written before TASK-080 recorded a single
+  // firing; read it as level 1 so an in-flight session whose hook is upgraded
+  // mid-run is not re-notified from scratch.
+  let reached = typeof prev?.levels === 'number' ? prev.levels : prev?.fired === true ? 1 : 0;
   // A large drop means the context was compacted/cleared: arm again so the
   // NEXT time it grows past the threshold the user hears about it.
-  if (prev && typeof prev.last === 'number' && total < prev.last * REARM_DROP_RATIO) fired = false;
+  if (prev && typeof prev.last === 'number' && total < prev.last * REARM_DROP_RATIO) reached = 0;
+
+  const level = levelFor(total, threshold);
+  const remind = level > reached;
+  return { remind, escalated: remind && level === 2, next: { last: total, levels: Math.max(reached, level), ts: Date.now() } };
+}
 
-  const remind = !fired && total >= threshold;
-  return { remind, next: { last: total, fired: fired || remind, ts: Date.now() } };
+/**
+ * BEST-EFFORT user-facing channel (`systemMessage`). Emitted because it is free
+ * and correct per the hook schema — NOT because it is known to be shown.
+ *
+ * Measured 2026-07-26, TASK-080, with a two-marker probe: `systemMessage` does
+ * not reach the model's context (so it costs no tokens), and it did not appear
+ * on screen either, in the VSCode extension, for a UserPromptSubmit hook. The
+ * same probe's `additionalContext` marker arrived, which is what makes that a
+ * clean negative rather than a probe that failed to load. Other clients were
+ * not measured, so this stays: a line that costs nothing and may render
+ * somewhere else. **Nothing may depend on it** — in particular reminderText()
+ * must never tell the model the user has already seen the number.
+ *
+ * One sentence, deliberately: the size is the one fact a user cannot get
+ * anywhere else, and /compact is the one action.
+ */
+export function userNotice(total) {
+  const k = Math.round(total / 1000);
+  return `[tune-context] Context is at ~${k}k tokens — consider /compact when the current thread closes.`;
 }
 
-export function reminderText(total) {
+/**
+ * The channel that actually works (`additionalContext`): the model reads it and
+ * relays it. The timing judgement stays here, because only the model can tell
+ * whether the current thread is finished — but see the second sentence: it must
+ * relay eventually, because staying silent forever means the user never learns.
+ */
+export function reminderText(total, { escalated = false } = {}) {
   const k = Math.round(total / 1000);
   return [
     `[tune-context] This session is now carrying ~${k}k tokens of context, and every further turn re-sends all of it.`,
+    // The measured failure this sentence exists to prevent: at ~166k the model
+    // stayed quiet mid-task and simply never came back to it, so the user first
+    // heard about the cost at ~346k.
+    'The user CANNOT see this reminder — it reaches you alone, so if you never mention it they will never know.',
     'If the current work thread is finished: suggest /compact (or /clear when switching to unrelated work).',
-    'If you are mid-task: say nothing now and raise it when the thread closes.',
+    'If you are mid-task: stay quiet now, but raise it at the first natural break rather than dropping it.',
     'The PreCompact hook preserves branch, dirty files and recent commits across a compaction — judgment calls and open threads are NOT preserved, so write those down first.',
+    // Kept short on purpose: it rides ON TOP of the full reminder, inside the
+    // same <700 char budget.
+    ...(escalated ? ['This is the second and final automatic notice — nothing more fires until a compaction.'] : []),
   ].join(' ');
 }
 
@@ -182,7 +245,7 @@ function main() {
     const session = input.session_id || 'unknown';
     const path = stateFile();
     const state = readState(path);
-    const { remind, next } = decide(state[session], total, thresholdTokens());
+    const { remind, escalated, next } = decide(state[session], total, thresholdTokens());
 
     state[session] = next;
     try {
@@ -194,11 +257,14 @@ function main() {
     }
 
     if (!remind) return;
+    // additionalContext is the channel that is known to arrive; systemMessage
+    // is emitted alongside it as a free best-effort (see userNotice()).
     process.stdout.write(
       JSON.stringify({
+        systemMessage: userNotice(total),
         hookSpecificOutput: {
           hookEventName: 'UserPromptSubmit',
-          additionalContext: reminderText(total),
+          additionalContext: reminderText(total, { escalated }),
         },
       }),
     );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "2.0.0",
-  "description": "Context-efficiency configurator for Claude Code — token-saving doctrine packaged as skills, plus a tune-context configurator that scaffolds a lean CLAUDE.md, doctrine skills, subagents, settings, hooks and MCP wiring.",
+  "version": "2.1.0",
+  "description": "Context-efficiency configurator for Claude Code \u2014 token-saving doctrine packaged as skills, plus a tune-context configurator that scaffolds a lean CLAUDE.md, doctrine skills, subagents, settings, hooks and MCP wiring.",
   "type": "module",
   "license": "MIT",
   "author": "Szymon Walczak",