claude-code-infinite 1.0.21 → 1.0.22

package/README.md

@@ -17,10 +17,27 @@ follows it down to the original messages.
 * **Search across every session.** Claude can find what was decided, tried or ruled out in any of
   your past sessions, by exact words or by meaning, filtered by project and date
 * **Browse each session's MemTree** in your browser, from the link `ccc` prints in the terminal
-* **Replaces `/compact` without losing the thread.** In a blind-graded benchmark, MemTree matched
-  full-context Claude Code and beat Claude Code's built-in `/compact` by 20 points
-  ([details](#long-session-benchmark))
+* **Never loses anything vs Claude Code.** Sessions are sent word for word until near the context
+  limit; past it, MemTree matched full context (69 vs 69) and beat `/compact` by 20 ([benchmark](#long-session-benchmark))
 * **Unlimited-length sessions**, with relevant past information recalled automatically
+* **A local proxy, so no slowdown.** Requests go straight from your machine to Anthropic and
+  MemTree indexes in the background; only the occasional compression step, when a session
+  outgrows the context budget, waits on MemTree
+
+The magic starts past the context limit. Keep one session going for days and it learns how you
+work: your priorities, the nuances of your projects, your company and your environment. Where
+`/compact` would wipe that detail, MemTree keeps it, so the thread becomes an expert in you. Let it
+orchestrate dozens of subagents on your behalf.
+
+> [!IMPORTANT]
+> Requires a Claude Pro or Max subscription.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/crizCraig/claude-code-infinite/main/docs/images/benchmark-dark.svg">
+    <img width="600" alt="Long-session benchmark, judged score out of 100: Claude Code Infinite 69, full context 69, /compact 49" src="https://raw.githubusercontent.com/crizCraig/claude-code-infinite/main/docs/images/benchmark-light.svg">
+  </picture>
+</p>
 
 ## Search across sessions
 
@@ -67,14 +84,11 @@ tokens; `/compact`'s exclude the one-time `/compact` step. This is one task fami
 
 * [node.js 20.3 or newer](https://nodejs.org/en/download/)
 * [Claude Code (the terminal version)](https://code.claude.com/docs/en/quickstart)
-* **Claude Subscription** - optional but highly recommended as this offers up to 1000x cost savings vs Anthropic's API pricing
+* **A Claude Pro or Max subscription**
 
-## Setup
+<sub>Also works with an Anthropic API key, but that's far costlier than Pro or Max.</sub>
 
-> [!TIP]
-> No Claude subscription? Use an Anthropic API key exactly as with vanilla Claude Code
-> (`ANTHROPIC_API_KEY` or a Console login). `ccc` forwards it unchanged to api.anthropic.com, and
-> you pay Anthropic per token.
+## Setup
 
 1. Install (Node ≥ 20.3; no git needed)
   ```bash
@@ -96,6 +110,32 @@ The tool supports multiple environments (this selects the MemTree compression AP
 
 Each environment maintains its own separate API key.
 
+## Commands
+
+Type these inside a `ccc` session (the `ccc:` prefix is optional). `ccc` answers them
+locally, so they cost no model turn.
+
+| Command | What it does |
+| --- | --- |
+| `/ccc:memtree` | Lists the MemTree commands and links your usage dashboard. |
+| `/ccc:memtree-view` | Shows the link to this session's MemTree page. |
+| `/ccc:memtree-compact [tokens]` | Compacts the session on your next message (to half the budget, or a target such as `400k`) and keeps the compressed history. |
+| `/ccc:memtree-compact off` | Goes back to sending the conversation whole. |
+
+Environment variables, set when launching `ccc`:
+
+| Variable | What it does |
+| --- | --- |
+| `CCC_COMPACT_TARGET=500k` | Compaction target for every session (useful for headless `-p` runs); `off` starts every session with compaction off. |
+| `CCC_MEMTREE_LINK` | Where the MemTree link appears: `turn` (default, end of a turn with a new page), `message` (under every reply), `stop` (end of every turn), `success` (only after an optimized turn), or `off`. |
+| `CCC_AUTO_COMPACT=1` | Restores Claude Code's own auto-compaction setting ([details](#claude-code-auto-compaction)). |
+| `CCC_NO_UPDATE_CHECK=1` | Turns off the update check, and with it automatic updates ([details](#upgrading)). |
+| `CCC_DISABLE_AUTOUPDATE=1` | Keeps the update notice but never installs ([details](#automatic-updates)). |
+| `CCC_NO_DIAGNOSTICS=1` | Turns off diagnostics ([details](#diagnostics)). So do `DO_NOT_TRACK=1`, Claude Code's `DISABLE_TELEMETRY=1` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`, and `"diagnostics": false` in `~/.claude-code-infinite/config.json`. |
+
+Links are clickable in terminals that support OSC 8 hyperlinks (iTerm2, Ghostty, WezTerm,
+kitty, VS Code, JetBrains, Windows Terminal); elsewhere you get the plain URL.
+
 ## Claude Code auto-compaction
 
 `ccc` disables Claude Code's automatic conversation compaction for the Claude process it launches. MemTree manages the context sent to the model, so letting Claude Code independently summarize the full local transcript can compact a conversation MemTree already reduced. Manual `/compact` remains available.
@@ -105,6 +145,13 @@ above a fixed 100k-token threshold, even when the active model has a 1M window
 and auto-compaction is disabled. `ccc` suppresses that resume-time
 recommendation as well; it does not disable the manual `/compact` command.
 
+With auto-compaction off, Claude Code still refuses a request itself, without
+sending it, once its own estimate reaches the window minus 23k (977k on a 1M
+window). MemTree compresses at 900k, so a single large tool round could reach that
+refusal before `ccc` ever saw the request. `ccc` sets
+`CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE` (unless you exported your own) so such a
+request reaches the proxy, which compresses it mid-turn.
+
 A session whose last response reached the verified local refusal threshold
 (for example one sent whole while MemTree was unavailable) would otherwise be
 refused locally with "Context limit reached" on every prompt after a resume.
@@ -141,24 +188,27 @@ Claude Code ──▶ localhost proxy (ccc)
 - Anthropic requests go directly from the local proxy to api.anthropic.com using the authentication Claude Code supplied. PolyChat never sees that credential or Anthropic traffic.
 - If MemTree is unreachable, slow, or your MemTree plan needs payment, `ccc` degrades to a transparent passthrough so your session is never interrupted.
 
-### Inline notices
-
-In interactive sessions, `ccc` reports these MemTree states as display-only lines in Claude Code:
-
-- `✓ MemTree · conversation optimized · ~813k → 408k tokens`, with the session's newest completed MemTree page on its own line below it and a blank line before the answer, when a compressed turn reflects new indexing (MemTree's index covers more of the conversation than before) or a newly finished MemTree page. The before-count is `ccc`'s size estimate for the request that would otherwise have been sent (MemTree's `usage.raw_prompt_tokens` when `ccc` has none); the after-count is Anthropic's reported compressed input, estimated from bytes until usage arrives. Counts under a million are whole thousands, larger ones one decimal (`1.3m`). Without both counts, or when the result is not smaller, the line reads just `✓ MemTree · conversation optimized`. The line is green when terminal color is available, and plain when `NO_COLOR` or a monochrome terminal is configured. `ccc` uses the standard ANSI green foreground sequence and Node's capability detection, so the same path works in ANSI terminals on macOS/Linux and supported Windows consoles.
-- `⚠ MemTree degraded — this turn ran uncompressed` when a blocking compression call fails or times out.
-- `⚠ MemTree is off — payment required…` once when compression and indexing are disabled for payment.
-- `• MemTree` with the page on its own line below it, once at the end of a user turn, when the turn used a MemTree index whose link has not been shown yet (the first one of the session, then each newly finished index), unless the turn's success line already showed it. The line comes from the `Stop` hook, so it lands after the turn's last message. When MemTree passed the conversation through whole because it already fits the model's budget, the label line reads `• MemTree · /memtree-compact to compact session`. The URL always gets a line to itself, so a long link does not wrap the label or note. The displayed link follows the server's newest completed tree for this session, preserving its pinned namespace and own/served selection. If that lookup is unavailable, it falls back to the compression page; that page can show a completed prefix while its own tree builds. Open it in a browser, read it as JSON with `ccc fetch <url>`, or, from an agent inside the session, `GET $ANTHROPIC_BASE_URL/memtree/<short id>.json` on the loopback proxy without handling the key. Every MemTree call carries Claude Code's session id, so `GET $ANTHROPIC_BASE_URL/memtree/sessions/<session id>.json` lists every page from one session, newest first (the session id is the `--resume` id and the name of the transcript under `~/.claude/projects/`). `/memtree` lists the MemTree commands. Type `/memtree-view` at any time to print the session's latest link. Both also end with a `• Usage` link to your usage dashboard on polychat (`/usage` on the same host as MemTree: `https://app.polychat.co/usage` in production, the staging or local host otherwise); it opens only with your browser signed in to polychat as the same account. `/memtree-compact` is MemTree's replacement for Claude Code's `/compact`: your next message is sent compressed to half the budget (or `/memtree-compact 400k` for another target), and from then on the session follows the compaction rules under [How it works](#how-it-works) with that target. `/memtree-compact off` goes back to sending the conversation whole. `CCC_COMPACT_TARGET=500k` sets the target of every compaction for every session from launch, for benchmarks and headless (`-p`) runs, where the slash command is unavailable; it does not compact by itself, the budget still decides when, and `/memtree-compact off` still turns compaction off for one session. `CCC_COMPACT_TARGET=off` starts every session in the `/memtree-compact off` state instead (`/memtree-compact [N]` still turns it back on). `ccc` answers these commands locally, so they cost no model turn and nothing is added to the conversation; the compaction setting lasts for the life of the `ccc` process. When a session starts and already has a page, which in practice means a resumed one (`ccc --resume`, or `/resume` inside a running session), its latest link is shown right away: `ccc` remembers the newest page per session in `~/.claude-code-infinite/memtree-links.json` (most recent 200 sessions) and a `SessionStart` hook prints it. `CCC_MEMTREE_LINK` changes where the link appears: `turn` (default), `message` (under every finished assistant message, green when the index is new, dim otherwise), `stop` (every turn, on `Stop`), `success` (only on the line below `✓ MemTree · conversation optimized`), or `off`.
-
-The newest-tree lookup runs in the background with a 60-second cache, at most eight outstanding fetches, and one 10-second deadline across at most 32 finder pages. `/memtree-view` and resume hooks wait at most 2.5 seconds. Servers with the finder session-ID search (polychat `0202eaa` and later, including reviewed `c67cadb`) use `/v1/memtree/sessions?q=<id>`, following cursors and accepting only the exact session ID. A missing endpoint falls back to the compression page and is not retried for 30 minutes. The older exact route `/usage/memtree/sessions/<id>.json` accepts the bearer key, but excludes index-only calls and does not report completed trees, so it cannot supply this link. No verified server version provides a suitable exact newest-completed-tree lookup yet.
+### Diagnostics
 
-`/memtree-view` (and the usage link of `/memtree`) emits OSC 8 hyperlinks only when the ccc proxy has a TTY and detects iTerm2 3.1+ (`TERM_PROGRAM=iTerm.app` plus its version), JetBrains (`TERMINAL_EMULATOR=JetBrains-JediTerm`), Ghostty, WezTerm, VS Code, kitty, or Windows Terminal (`WT_SESSION`). Detection happens in the proxy, before hook output is relayed through pipes. `NO_COLOR`, dumb/unknown terminals, tmux/screen, and non-TTY output get a plain URL. Apple Terminal also gets the full visible URL for its normal URL handling. The success and Stop notices retain their visible URLs, and a late lookup cannot repeat the same page already linked by that turn's success notice.
+`ccc` sends a few diagnostics to MemTree so we can see why a session fails to start or stalls:
 
-**The end of a session.** MemTree indexes once about 10k new tokens build up, and each index call carries a request's messages, so a session's last turns, including the reply it ended with (often where a PR was opened), would never be indexed. `ccc` therefore sends one final index call per session: the main conversation plus that last reply, read from Claude Code's transcript, flagged so MemTree indexes the tail even below its minimum (at most once per conversation per 30 minutes; two conversations with an identical first message share that allowance). It goes out 10 minutes after a turn ends with no new request, or at exit for the 3 most recent sessions, inside the 2-second background drain; `-p` and non-TTY runs, which have no `Stop` hook, get it at exit. A failure is logged and never changes `ccc`'s exit code. Until then, `read_lines` with `"tail": true` reads the messages after the tree verbatim. When `ccc` runs inside another Claude Code session, the inner Claude Code writes no transcript unless `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` is set; without it the final index still covers everything through the last request, just not the final reply.
+- versions (ccc, Claude Code, Node), how ccc was installed (npm, npx, linked), OS and CPU
+  architecture, terminal type and locale;
+- lifecycle events (first run, sign-in prompt shown, key accepted or rejected, session start,
+  the MemTree-paused notice shown, update hint or background update result);
+- errors as codes, status numbers, sizes and timings (an Anthropic 401, a MemTree 402, a
+  compression timeout).
 
-`ccc` installs a minimal session-only Claude Code plugin using the repeatable `--plugin-dir` option. Its `MessageDisplay` hook changes only what the terminal renders and never alters stored assistant content; a `Stop` hook supplies a fallback for tool-only responses. That fallback may be saved by Claude Code as non-model hook UI metadata, but it is excluded from resumed model and recap requests. Notices are never added to model context, and Anthropic responses are left untouched with one exception: the hidden recap request Claude Code sends when you come back to an idle session gets a final `• MemTree` / `<url>` text block, so the recap ends with the link (not added when `CCC_MEMTREE_LINK=off`). Claude Code keeps that recap as a UI-only system entry, never as conversation content, and the block is skipped when it would push the recap past Claude Code's 400-character cap, and `-p`/non-TTY output is left unchanged. Legacy marker cleanup remains for transcripts created by older `ccc` releases. The payment state can also produce a separate terminal warning at startup.
+Never sent: your prompts or any conversation content, file paths, project or repository names,
+hostnames, usernames, environment values, keys or tokens, or error message text. Each event is
+checked against a fixed allowlist on your machine before it is queued, and again by the server.
+They are tied to your MemTree key when you have one, otherwise to a random install id in
+`~/.claude-code-infinite/install_id`. Sending is batched in the background and never slows a
+request; a failed send is dropped.
 
-Claude Code currently displays the original assistant text instead of `MessageDisplay` replacements while verbose mode is enabled. Turn verbose mode off to see the inline MemTree line.
+Turn diagnostics off with any of: `CCC_NO_DIAGNOSTICS=1`, `"diagnostics": false` in
+`~/.claude-code-infinite/config.json`, `DO_NOT_TRACK=1`, or Claude Code's own
+`DISABLE_TELEMETRY=1` / `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`.
 
 ### Memory tools
 
@@ -173,7 +223,7 @@ Interactive `ccc` sessions also get a small MCP server, `memtree`, with four rea
 
 When you send a message, we retrieve relevant details and summaries from the prior messages in your thread. These details and summaries populate a **memory message**. Following the memory message, we append a compressed version of your recent message history. The resulting context-window is dramatically smaller, allowing Claude to process your request with much greater efficacy, lower latency, and reduced cost.
 
-**Compaction keeps a stable prefix.** While a conversation fits the model's budget (800k tokens for Opus 5.5), it is sent whole. When a request reaches the budget, `ccc` compresses it once, to half the budget (or your `/memtree-compact N`), and keeps those compressed bytes as the session's prefix. Every later request, human turns included, is that same prefix followed by the messages that came after it, verbatim, with no compression call (MemTree still indexes in the background). Because the prefix does not change, Anthropic reads it from the prompt cache on every turn after the one that compacted, instead of writing the whole compressed context again. `ccc` compresses again only when prefix plus newer turns reach the budget (measured from the size Anthropic reported for the previous request, plus an estimate for what was added), or when the messages the prefix stands for change (rewind, edit, fork, `/clear`). If that recompression fails, the turn is sent on the old prefix rather than the whole history. The prefix is also kept on disk, one file per session under `~/.claude-code-infinite/stable-prefixes/` (mode 600 in a private directory, at most 64 sessions and 256 MB, oldest dropped first), so the first turn after `ccc --resume` rides it instead of waiting on a fresh compression. A stored prefix belongs to the MemTree backend and key that wrote it (identified by a hash, never the key itself) and is never used with another. It is used only if the resumed history still matches what it replaced; a main-thread history that no longer matches discards it, while side requests (such as Claude Code's web-search helper) leave it alone. Only the main thread's prefix is stored, never a subagent's. The budget is the one MemTree reports for the model; until the server reports one, `ccc` uses 80% of the model's context window. `CCC_BUDGET_TOKENS=60k` overrides it for testing. Every `requests.jsonl` line carries the `pid` of the `ccc` process that wrote it, which tells apart concurrent sessions sharing the log. The same rule holds inside a tool loop, so a long single turn (a headless `-p` run, or a long agentic loop) is compacted as it grows rather than only when you next type: each tool request under the budget goes out with no compression call, the one that reaches it is compressed once and becomes the stable prefix, and later tool requests and your next message ride that prefix until it reaches the budget again. `requests.jsonl` shows the `compaction` of each main-thread human turn and of every tool turn (budget, its source, the size estimate, and the reason for a compaction: `budget`, `prefix-mismatch`, `manual` or `target-change`); a human turn sent on the stable prefix is `turnType: "followup-prefix"`, a tool turn `tool-memory` (on its route) or `tool-prefix` (on the prefix directly), and a tool turn that compacted `tool-recompressed`.
+**Compaction keeps a stable prefix.** While a conversation fits the model's budget (900k tokens for Opus 5.5, where plain Claude Code would auto-compact at 967k), it is sent whole. When a request reaches the budget, `ccc` compresses it once, to half the budget (or your `/memtree-compact N`), and keeps those compressed bytes as the session's prefix. Every later request, human turns included, is that same prefix followed by the messages that came after it, verbatim, with no compression call (MemTree still indexes in the background). Because the prefix does not change, Anthropic reads it from the prompt cache on every turn after the one that compacted, instead of writing the whole compressed context again. `ccc` compresses again only when prefix plus newer turns reach the budget (measured from the size Anthropic reported for the previous request, plus an estimate for what was added), or when the messages the prefix stands for change (rewind, edit, fork, `/clear`). If that recompression fails, the turn is sent on the old prefix rather than the whole history. The prefix is also kept on disk, one file per session under `~/.claude-code-infinite/stable-prefixes/` (mode 600 in a private directory, at most 64 sessions and 256 MB, oldest dropped first), so the first turn after `ccc --resume` rides it instead of waiting on a fresh compression. A stored prefix belongs to the MemTree backend and key that wrote it (identified by a hash, never the key itself) and is never used with another. It is used only if the resumed history still matches what it replaced; a main-thread history that no longer matches discards it, while side requests (such as Claude Code's web-search helper) leave it alone. Only the main thread's prefix is stored, never a subagent's. The budget is the one MemTree reports for the model; until the server reports one, `ccc` uses 90% of the context window on Opus 5.5, Opus 5, Opus 4.8 and Fable 5 and 5.1 with a 1M window, and 80% otherwise. `CCC_BUDGET_TOKENS=60k` overrides it for testing. Every `requests.jsonl` line carries the `pid` of the `ccc` process that wrote it, which tells apart concurrent sessions sharing the log. The same rule holds inside a tool loop, so a long single turn (a headless `-p` run, or a long agentic loop) is compacted as it grows rather than only when you next type: each tool request under the budget goes out with no compression call, the one that reaches it is compressed once and becomes the stable prefix, and later tool requests and your next message ride that prefix until it reaches the budget again. `requests.jsonl` shows the `compaction` of each main-thread human turn and of every tool turn (budget, its source, the size estimate, and the reason for a compaction: `budget`, `prefix-mismatch`, `manual` or `target-change`); a human turn sent on the stable prefix is `turnType: "followup-prefix"`, a tool turn `tool-memory` (on its route) or `tool-prefix` (on the prefix directly), and a tool turn that compacted `tool-recompressed`.
 
 That compressed context stays in force for the rest of the turn: the tool loop it kicks off, and the matching Count Tokens calls, are routed through the same compressed prefix. The Count Tokens part matters — Claude Code sizes its context from those replies, so counting the uncompressed history would make it auto-compact a conversation memory had already shrunk. A mismatched or resumed conversation shape drops the route rather than grafting one session's prefix onto another.
 

package/dist/claude-env.d.ts

@@ -17,9 +17,22 @@
  * DISABLE_AUTO_COMPACT. Suppress that ccc-inappropriate recommendation with an
  * effectively unreachable finite threshold; manual `/compact` remains available.
  *
+ * With auto-compaction off, Claude Code still refuses a request itself once
+ * its own estimate (last reported usage plus the new messages) reaches the
+ * window minus 23k (977k on a 1M window; 2.1.302, measured) and never sends
+ * it: "Prompt is too long", and every later message is refused the same way.
+ * MemTree compresses at a budget near the window (900k), so one large tool
+ * round could otherwise strand a session there before ccc sees the request.
+ * CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE lifts that refusal: the request reaches
+ * the proxy, which compresses it mid-turn or, failing that, refuses it with
+ * its own bounded retry/400. A value the user already exported is kept.
+ *
  * `CCC_AUTO_COMPACT=1` is an escape hatch: remove ccc's override and let the
- * user's native Claude Code setting decide whether auto-compaction is enabled.
+ * user's native Claude Code setting decide whether auto-compaction is enabled
+ * (Claude Code's own limits then apply unchanged).
  */
+/** Claude Code's local refusal limit under ccc: effectively never reached. */
+export declare const UNREACHABLE_BLOCKING_LIMIT = "1000000000";
 export declare function claudeChildEnv(parentEnv: NodeJS.ProcessEnv, anthropicBaseUrl: string): NodeJS.ProcessEnv;
 /**
  * Keep the proxy's MemTree budget in lockstep with Claude Code's own context

package/dist/claude-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-env.d.ts","sourceRoot":"","sources":["../src/claude-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,CAAC,UAAU,EAC5B,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAAC,UAAU,CAoBnB;AAOD;;;;GAIG;AACH,wBAAgB,oCAAoC,CAClD,SAAS,EAAE,MAAM,CAAC,UAAU,GAC3B,OAAO,CAET"}
+{"version":3,"file":"claude-env.d.ts","sourceRoot":"","sources":["../src/claude-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,eAAe,CAAC;AAEvD,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,CAAC,UAAU,EAC5B,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAAC,UAAU,CAuBnB;AAOD;;;;GAIG;AACH,wBAAgB,oCAAoC,CAClD,SAAS,EAAE,MAAM,CAAC,UAAU,GAC3B,OAAO,CAET"}

package/dist/claude-env.js

@@ -17,9 +17,22 @@
  * DISABLE_AUTO_COMPACT. Suppress that ccc-inappropriate recommendation with an
  * effectively unreachable finite threshold; manual `/compact` remains available.
  *
+ * With auto-compaction off, Claude Code still refuses a request itself once
+ * its own estimate (last reported usage plus the new messages) reaches the
+ * window minus 23k (977k on a 1M window; 2.1.302, measured) and never sends
+ * it: "Prompt is too long", and every later message is refused the same way.
+ * MemTree compresses at a budget near the window (900k), so one large tool
+ * round could otherwise strand a session there before ccc sees the request.
+ * CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE lifts that refusal: the request reaches
+ * the proxy, which compresses it mid-turn or, failing that, refuses it with
+ * its own bounded retry/400. A value the user already exported is kept.
+ *
  * `CCC_AUTO_COMPACT=1` is an escape hatch: remove ccc's override and let the
- * user's native Claude Code setting decide whether auto-compaction is enabled.
+ * user's native Claude Code setting decide whether auto-compaction is enabled
+ * (Claude Code's own limits then apply unchanged).
  */
+/** Claude Code's local refusal limit under ccc: effectively never reached. */
+export const UNREACHABLE_BLOCKING_LIMIT = "1000000000";
 export function claudeChildEnv(parentEnv, anthropicBaseUrl) {
     const childEnv = {
         ...parentEnv,
@@ -36,6 +49,9 @@ export function claudeChildEnv(parentEnv, anthropicBaseUrl) {
     }
     else {
         childEnv.DISABLE_AUTO_COMPACT = "1";
+        if (!childEnv.CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE) {
+            childEnv.CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE = UNREACHABLE_BLOCKING_LIMIT;
+        }
     }
     return childEnv;
 }

package/dist/claude-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-env.js","sourceRoot":"","sources":["../src/claude-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAC5B,SAA4B,EAC5B,gBAAwB;IAExB,MAAM,QAAQ,GAAsB;QAClC,GAAG,SAAS;QACZ,kBAAkB,EAAE,gBAAgB;QACpC,wCAAwC,EAAE,GAAG;QAC7C,kCAAkC,EAAE,YAAY;KACjD,CAAC;IAEF,gEAAgE;IAChE,OAAO,QAAQ,CAAC,gBAAgB,CAAC;IAEjC,IAAI,SAAS,CAAC,gBAAgB,KAAK,GAAG,EAAE,CAAC;QACvC,oEAAoE;QACpE,iCAAiC;QACjC,OAAO,QAAQ,CAAC,oBAAoB,CAAC;IACvC,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,oBAAoB,GAAG,GAAG,CAAC;IACtC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,cAAc,CAAC,KAAyB;IAC/C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oCAAoC,CAClD,SAA4B;IAE5B,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,8BAA8B,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"claude-env.js","sourceRoot":"","sources":["../src/claude-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,0BAA0B,GAAG,YAAY,CAAC;AAEvD,MAAM,UAAU,cAAc,CAC5B,SAA4B,EAC5B,gBAAwB;IAExB,MAAM,QAAQ,GAAsB;QAClC,GAAG,SAAS;QACZ,kBAAkB,EAAE,gBAAgB;QACpC,wCAAwC,EAAE,GAAG;QAC7C,kCAAkC,EAAE,YAAY;KACjD,CAAC;IAEF,gEAAgE;IAChE,OAAO,QAAQ,CAAC,gBAAgB,CAAC;IAEjC,IAAI,SAAS,CAAC,gBAAgB,KAAK,GAAG,EAAE,CAAC;QACvC,oEAAoE;QACpE,iCAAiC;QACjC,OAAO,QAAQ,CAAC,oBAAoB,CAAC;IACvC,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,oBAAoB,GAAG,GAAG,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,mCAAmC,EAAE,CAAC;YAClD,QAAQ,CAAC,mCAAmC,GAAG,0BAA0B,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,cAAc,CAAC,KAAyB;IAC/C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oCAAoC,CAClD,SAA4B;IAE5B,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,8BAA8B,CAAC,CAAC;AACnE,CAAC"}

package/dist/cli-lifecycle.d.ts

@@ -14,4 +14,8 @@ export interface SignalShutdownActions {
  * Dependencies are injected so this policy can be tested without process.exit.
  */
 export declare function createSignalShutdownHandler(actions: SignalShutdownActions): (signal: ShutdownSignal) => void;
+/** Resolves once `text` is handed to the OS (or the write fails); never rejects. */
+export declare function writeStdout(text: string, stream?: Pick<NodeJS.WriteStream, "write">): Promise<void>;
+/** Waits for `pending` at most `ms`; a bound for cleanup that must not hang exit. */
+export declare function settleWithin(pending: Promise<unknown>, ms: number): Promise<void>;
 //# sourceMappingURL=cli-lifecycle.d.ts.map

package/dist/cli-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-lifecycle.d.ts","sourceRoot":"","sources":["../src/cli-lifecycle.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,CAGhE;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,GAC5B,MAAM,CAGR;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,qBAAqB,GAC7B,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CASlC"}
+{"version":3,"file":"cli-lifecycle.d.ts","sourceRoot":"","sources":["../src/cli-lifecycle.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,CAGhE;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,GAC5B,MAAM,CAGR;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,qBAAqB,GAC7B,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CASlC;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAkB,GACzD,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjF"}

package/dist/cli-lifecycle.js

@@ -27,4 +27,22 @@ export function createSignalShutdownHandler(actions) {
             actions.forceExit(code);
     };
 }
+/** Resolves once `text` is handed to the OS (or the write fails); never rejects. */
+export function writeStdout(text, stream = process.stdout) {
+    return new Promise((resolve) => {
+        try {
+            stream.write(text, () => resolve());
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+/** Waits for `pending` at most `ms`; a bound for cleanup that must not hang exit. */
+export function settleWithin(pending, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        pending.then(() => { clearTimeout(timer); resolve(); }, () => { clearTimeout(timer); resolve(); });
+    });
+}
 //# sourceMappingURL=cli-lifecycle.js.map

package/dist/cli-lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-lifecycle.js","sourceRoot":"","sources":["../src/cli-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AAInD,4EAA4E;AAC5E,MAAM,UAAU,iBAAiB,CAAC,MAAsB;IACtD,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,OAAO,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAC9B,IAAmB,EACnB,MAA6B;IAE7B,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAA8B;IAE9B,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,QAAQ,KAAK,CAAC;YAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;;YACtC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"cli-lifecycle.js","sourceRoot":"","sources":["../src/cli-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AAInD,4EAA4E;AAC5E,MAAM,UAAU,iBAAiB,CAAC,MAAsB;IACtD,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,OAAO,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAC9B,IAAmB,EACnB,MAA6B;IAE7B,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAA8B;IAE9B,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,QAAQ,KAAK,CAAC;YAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;;YACtC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,WAAW,CACzB,IAAY,EACZ,SAA4C,OAAO,CAAC,MAAM;IAE1D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,CAAC;YACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,OAAyB,EAAE,EAAU;IAChE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,OAAO,CAAC,IAAI,CACV,GAAG,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EACzC,GAAG,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAC1C,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli-main.js

@@ -17,6 +17,7 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import { MEMTREE_COMPACT_MIN_TOKENS, parseTokenCount, startProxy } from "./proxy.js";
 import { MemtreeLinkStore } from "./memtree-links.js";
+import { FirstTreeMarker } from "./first-tree.js";
 import { StablePrefixStore } from "./prefix-store.js";
 import { NewestTreeLookup } from "./memtree-newest.js";
 import { ClaudeTranscriptUsage } from "./transcript-usage.js";
@@ -33,9 +34,13 @@ import { runMemtreeMcpServer } from "./memtree-mcp.js";
 import { readProjectMeta } from "./project-meta.js";
 import { argsConfigureMemtreeMcp, MEMTREE_TOOLS_HEADER_VALUE, memtreeMcpEnabledByEnv, withMemtreeMcpArgs, writeMemtreeMcpConfig, } from "./memtree-mcp-config.js";
 import { claudeChildEnv, claudeNativeOneMillionContextEnabled, } from "./claude-env.js";
-import { createSignalShutdownHandler, exitCodeForChild, } from "./cli-lifecycle.js";
+import { createSignalShutdownHandler, exitCodeForChild, settleWithin, writeStdout, } from "./cli-lifecycle.js";
 import { getPolychatApiKey, setPolychatApiKey, getLocalPolychatApiKey, setLocalPolychatApiKey, getStagingPolychatApiKey, setStagingPolychatApiKey, getConfigDir, loadConfig, } from "./config.js";
 import { repairStrandedResume, resumeSessionId } from "./resume-repair.js";
+import { Diagnostics, DiagnosticsRequestSink, recordError } from "./diagnostics.js";
+import { signalName } from "./diagnostics-schema.js";
+import { PACKAGE_DIR, detectInstallMethod } from "./auto-update.js";
+import { exitResumeHint } from "./resume-hint.js";
 // MemTree (polychat) API hosts — /v1/context_memory lives at the app root.
 const POLYCHAT_BASE_URL = "https://api.polychat.co";
 const STAGING_BASE_URL = "https://polychat-staging-421312241218.us-west2.run.app";
@@ -45,10 +50,14 @@ const POLYCHAT_AUTH_URL = "https://polychat.co/auth?memtree=true&utm_source=ccc"
 const SHUTDOWN_PROXY_DRAIN_MS = 5_000;
 const SHUTDOWN_MEMTREE_DRAIN_MS = 2_000;
 const SHUTDOWN_LOG_FLUSH_MS = 2_000;
+/** Shutdown's wait for the child's exit and the resume hint's (asynchronous) write. */
+const SHUTDOWN_OUTPUT_FLUSH_MS = 1_000;
 // Payment gate: how long "subscribe now" waits for the Stripe webhook to flip
 // the key to paid, and how often it re-asks the status probe meanwhile.
 const SUBSCRIBE_WAIT_MS = 180_000;
 const SUBSCRIBE_POLL_MS = 3_000;
+/** This launch's diagnostics, for the top-level error handler. */
+let activeDiagnostics = null;
 function openUrl(url) {
     const platform = process.platform;
     const command = platform === "darwin" ? "open" : platform === "win32" ? "explorer" : "xdg-open";
@@ -85,7 +94,7 @@ async function promptForApiKey(mode) {
  * mean "unknown" (null): the caller stays quiet. Bounded by a short timeout
  * and never throws, so startup is never gated on polychat availability.
  */
-async function fetchPaymentStatus(baseUrl, apiKey, timeoutMs = 2000) {
+async function fetchPaymentStatus(baseUrl, apiKey, timeoutMs = 2000, diagnostics) {
     try {
         const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/context_memory/status`, {
             headers: {
@@ -95,11 +104,23 @@ async function fetchPaymentStatus(baseUrl, apiKey, timeoutMs = 2000) {
             },
             signal: AbortSignal.timeout(timeoutMs),
         });
-        if (!res.ok)
+        if (!res.ok) {
+            diagnostics?.record("key_status", {
+                result: res.status === 401 ? "invalid" : res.status === 402 ? "payment_required" : "unknown",
+                status: res.status,
+            });
             return null;
-        return parsePaymentStatus(await res.json());
+        }
+        const status = parsePaymentStatus(await res.json());
+        diagnostics?.record("key_status", {
+            result: status?.paid === false ? "payment_required" : status ? "ok" : "unknown",
+            status: res.status,
+        });
+        return status;
     }
-    catch {
+    catch (err) {
+        if (diagnostics)
+            recordError(diagnostics, "status_probe_failed", err);
         return null;
     }
 }
@@ -110,13 +131,16 @@ async function fetchPaymentStatus(baseUrl, apiKey, timeoutMs = 2000) {
  * the webhook to flip the key to paid), use claude without MemTree (launch
  * uncompressed, the in-session notice still fires), or quit.
  */
-async function runPaymentGate(status, recheck) {
+async function runPaymentGate(status, recheck, diagnostics) {
     let current = status;
     for (;;) {
         console.warn(`\x1b[1;33m${formatPaymentNotice(current, { hyperlinks: true })}\x1b[0m\n`);
         const choice = parsePaymentChoice(await askLine(PAYMENT_GATE_PROMPT));
-        if (choice === "quit")
+        diagnostics.record("payment_gate", { choice });
+        if (choice === "quit") {
+            await diagnostics.flush();
             process.exit(0);
+        }
         if (choice === "continue") {
             console.log("\nStarting claude without MemTree.\n");
             return;
@@ -124,6 +148,7 @@ async function runPaymentGate(status, recheck) {
         openUrl(current.url ?? FALLBACK_SUBSCRIBE_URL);
         console.log("\nOpened the subscribe page. Waiting for payment to complete…");
         const paid = await waitUntilPaid(recheck, SUBSCRIBE_WAIT_MS, SUBSCRIBE_POLL_MS);
+        diagnostics.record("payment_gate", { choice: paid ? "paid" : "still_unpaid" });
         if (paid) {
             console.log("\x1b[1;32m✓ MemTree is on — thank you.\x1b[0m\n");
             return;
@@ -195,16 +220,28 @@ async function main() {
     else if (mode === "staging") {
         console.log("\x1b[1;35m🚧 STAGING MODE\x1b[0m\n");
     }
+    const memtreeBaseUrl = mode === "local" ? LOCAL_BASE_URL :
+        mode === "staging" ? STAGING_BASE_URL :
+            POLYCHAT_BASE_URL;
     // Get or prompt for the MemTree API key (separate keys per environment)
     let polychatApiKey = mode === "local" ? getLocalPolychatApiKey() :
         mode === "staging" ? getStagingPolychatApiKey() :
             getPolychatApiKey();
+    // Client diagnostics (diagnostics.ts): versions, OS and errors, never content.
+    // Started before the key prompt so a signup that stalls there is visible too.
+    const diagnostics = startDiagnostics(mode, memtreeBaseUrl, polychatApiKey);
     if (!polychatApiKey) {
+        diagnostics.record("sign_in_prompt");
+        // The user may quit at the prompt: send what is known now.
+        diagnostics.flushNow();
         polychatApiKey = await promptForApiKey(mode);
         if (!polychatApiKey) {
             console.error("A MemTree API key is required.");
+            await diagnostics.flush();
             process.exit(1);
         }
+        diagnostics.record("key_saved");
+        diagnostics.setApiKey(polychatApiKey);
         if (mode === "local") {
             setLocalPolychatApiKey(polychatApiKey);
         }
@@ -216,9 +253,6 @@ async function main() {
         }
         console.log("API key saved.\n");
     }
-    const memtreeBaseUrl = mode === "local" ? LOCAL_BASE_URL :
-        mode === "staging" ? STAGING_BASE_URL :
-            POLYCHAT_BASE_URL;
     // Interactive UI only: print/non-TTY invocations are programmatic
     // interfaces whose output must stay byte-for-byte vanilla, and they get no
     // notice plugin to deliver a banner anyway.
@@ -236,7 +270,7 @@ async function main() {
     // call so sessions can be found by project; read once, never fails.
     const config = loadConfig();
     const [paymentStatus, updateAvailable, projectMeta] = await Promise.all([
-        fetchPaymentStatus(memtreeBaseUrl, polychatApiKey),
+        fetchPaymentStatus(memtreeBaseUrl, polychatApiKey, undefined, diagnostics),
         interactiveUi
             ? checkForUpdate({
                 currentVersion: CLIENT_VERSION,
@@ -248,7 +282,7 @@ async function main() {
     ]);
     if (paymentStatus?.paid === false) {
         if (interactiveUi) {
-            await runPaymentGate(paymentStatus, () => fetchPaymentStatus(memtreeBaseUrl, polychatApiKey));
+            await runPaymentGate(paymentStatus, () => fetchPaymentStatus(memtreeBaseUrl, polychatApiKey), diagnostics);
         }
         else {
             console.warn(`\x1b[1;33m${formatPaymentNotice(paymentStatus)}\x1b[0m`);
@@ -269,10 +303,17 @@ async function main() {
         : null;
     if (isDebugMode && autoUpdate)
         console.log(`[DEBUG] ${autoUpdate.debugLine}`);
+    diagnostics.setContext({ interactive: interactiveUi });
+    if (autoUpdate?.bannerUpdate) {
+        diagnostics.record("update_hint", { latest: autoUpdate.bannerUpdate.latest });
+    }
     // Always-on request/timing log (reqlog.ts): messages, MemTree calls, and
     // successful notice claims, so incidents can be reconstructed after the
     // fact without --debug. Never blocks or throws.
     const reqlog = new RequestLogger();
+    // The proxy and MemTree client log through this tee: unchanged lines in the
+    // request log, plus a few allowlisted numbers for diagnostics.
+    const observedLog = new DiagnosticsRequestSink(reqlog, diagnostics);
     // The `memtree` MCP server (memtree-mcp-config.ts): registered by ccc for
     // interactive sessions unless CCC_MEMTREE_MCP=0; print/non-TTY runs have it
     // only when their own --mcp-config names it. Either way MemTree is told
@@ -285,17 +326,19 @@ async function main() {
         baseUrl: memtreeBaseUrl,
         apiKey: polychatApiKey,
         debug: isDebugMode,
-        reqlog,
+        reqlog: observedLog,
         // Mutable below: a failed config write withdraws it before any call.
         memtreeTools: memtreeToolsConfigured ? MEMTREE_TOOLS_HEADER_VALUE : undefined,
     });
     const nativeOneMillionContext = claudeNativeOneMillionContextEnabled(process.env);
     const memtreeLinkPlacement = memtreeLinkPlacementFromEnv(process.env.CCC_MEMTREE_LINK);
+    const memtreeLinkStore = new MemtreeLinkStore();
     const transcriptUsage = new ClaudeTranscriptUsage();
     const proxy = await startProxy({
         memtree,
         debug: isDebugMode,
-        reqlog,
+        reqlog: observedLog,
+        diagnostics,
         nativeOneMillionContext,
         // Kill switch for tool-turn COMPACTION only: CCC_TOOL_ROUTE_RECOVERY=0
         // makes tool turns pure passthrough — no size check, no compress call;
@@ -321,7 +364,9 @@ async function main() {
         // CCC_MEMTREE_LINK=message|stop|success|off picks where the MemTree page
         // link is shown while the placement is being tried out; see ProxyOptions.
         memtreeLinkPlacement,
-        memtreeLinkStore: new MemtreeLinkStore(),
+        memtreeLinkStore,
+        // A session's first tree gets a one-time notice saying what it is.
+        firstTreeIntro: new FirstTreeMarker(memtreeLinkStore),
         // Each session's adopted compressed prefix, so a resumed session's first
         // turn rides it instead of blocking on a fresh compress.
         stablePrefixStore: new StablePrefixStore(),
@@ -401,6 +446,11 @@ async function main() {
         stdio: "inherit",
     });
     let shuttingDown = false;
+    // Settles once the child has exited and the resume hint (if any) is written,
+    // or the child failed to start. Awaited (bounded) just before exiting, so a
+    // signal whose cleanup finishes first still lets the hint print.
+    let markChildDone = () => { };
+    const childDone = new Promise((resolve) => { markChildDone = resolve; });
     const shutdown = async (code) => {
         if (shuttingDown)
             return;
@@ -416,7 +466,9 @@ async function main() {
         // would never fire), inside the same bounded background drain.
         memtree.flushFinalIndexes();
         await memtree.drainBackground(SHUTDOWN_MEMTREE_DRAIN_MS);
-        await reqlog.flush(SHUTDOWN_LOG_FLUSH_MS);
+        // Before the final flushes, so a late child exit's diagnostics event is sent.
+        await settleWithin(childDone, SHUTDOWN_OUTPUT_FLUSH_MS);
+        await Promise.all([reqlog.flush(SHUTDOWN_LOG_FLUSH_MS), diagnostics.flush()]);
         process.exit(code);
     };
     const handleShutdownSignal = createSignalShutdownHandler({
@@ -441,24 +493,72 @@ async function main() {
     process.on("SIGTERM", () => handleShutdownSignal("SIGTERM"));
     // The background install starts once Claude Code is up; it outlives this
     // process if the session ends first.
-    autoUpdate?.scheduleInstall();
+    autoUpdate?.scheduleInstall(undefined, (result) => {
+        diagnostics.record("auto_update", { result });
+        diagnostics.flushNow();
+    });
     child.on("error", (err) => {
         if (err.code === "ENOENT") {
+            diagnostics.record("claude_missing");
             console.error("Could not find 'claude' command. Make sure Claude Code is installed.");
         }
         else {
+            recordError(diagnostics, "spawn_failed", err);
             console.error("Failed to start claude:", err.message);
         }
+        markChildDone();
         void shutdown(1);
     });
     child.on("exit", (code, signal) => {
+        if (code !== 0) {
+            diagnostics.record("claude_exit", { code: code ?? undefined, signal: signalName(signal) });
+        }
+        // Under Claude Code's own "claude --resume <id>", which would skip MemTree.
+        const hint = exitResumeHint({
+            interactive: interactiveUi,
+            sessionId: proxy.mainSessionId(),
+            mode,
+            color: terminalSupportsColor(),
+        });
+        // Writes to a Windows console or a pipe are asynchronous: let it land before exit.
+        void (hint ? writeStdout(hint) : Promise.resolve()).then(markChildDone);
         void shutdown(exitCodeForChild(code, signal));
     });
 }
-main().catch((err) => {
+main().catch(async (err) => {
     console.error(err);
+    if (activeDiagnostics) {
+        recordError(activeDiagnostics, "startup_failed", err);
+        await activeDiagnostics.flush();
+    }
     process.exit(1);
 });
+/**
+ * This launch's diagnostics: environment context, install method, the first
+ * run of this install, and a periodic background flush. Off under any opt-out.
+ */
+function startDiagnostics(mode, baseUrl, apiKey) {
+    const diagnostics = new Diagnostics({
+        baseUrl, configDir: getConfigDir(), clientName: CLIENT_NAME, clientVersion: CLIENT_VERSION,
+        config: loadConfig(), apiKey,
+    });
+    activeDiagnostics = diagnostics;
+    if (!diagnostics.enabled)
+        return diagnostics;
+    try {
+        const method = detectInstallMethod({
+            packageDir: PACKAGE_DIR, env: process.env, uid: process.getuid?.(),
+        });
+        diagnostics.setContext({ mode, install_method: method.kind });
+    }
+    catch {
+        diagnostics.setContext({ mode });
+    }
+    if (diagnostics.firstRun)
+        diagnostics.record("first_run");
+    diagnostics.start();
+    return diagnostics;
+}
 /** `CCC_COMPACT_TARGET` ("500k", "20000", "off"): see cli-args.ts. */
 /**
  * A resumed session whose last response was recorded past Claude Code's limit