@aaroncql/pim-agent 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AaronCQL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+<!-- omit in toc -->
+# PIM - Pi IMproved
+
+_**Pim is to Pi what Vim is to Vi.**_
+
+An opinionated yet minimal, Bun-native extension pack for [Pi](https://pi.dev/): revamped tools, ANSI-compatible themes, fzf-style autocompletions, Telegram bot, and more. Scores up to [41.6% on Terminal-Bench 2.0](#terminal-bench-20) with locally hosted Qwen3.6-35B, matching Claude Code + Sonnet 4.5.
+
+- [Quick Start](#quick-start)
+  - [API Keys (Optional)](#api-keys-optional)
+  - [Recommended Settings (Optional)](#recommended-settings-optional)
+- [Agent Tools](#agent-tools)
+- [Terminal UI](#terminal-ui)
+- [Telegram Bot](#telegram-bot)
+  - [Setup](#setup)
+  - [Commands](#commands)
+  - [Features](#features)
+- [Why Pim?](#why-pim)
+  - [Harness Design](#harness-design)
+  - [Terminal-Bench 2.0](#terminal-bench-20)
+- [Developing](#developing)
+
+## Quick Start
+
+> [!IMPORTANT]
+> The following instructions assume you have [Pi](https://pi.dev/docs/latest/quickstart) and [Bun](https://bun.com/docs/installation) already installed. If not, install them first (_or ask your agent to do it for you_). For all things related to Pi, refer to [Pi's comprehensive docs](https://pi.dev/docs/latest).
+
+```sh
+# First, install Pim as a Pi extension:
+pi install npm:@aaroncql/pim-agent
+
+# Then, install the Bun-native `pim` launcher:
+bun install -g @aaroncql/pim-agent
+
+# Finally, launch pim:
+pim
+```
+
+The `pim` command is a [thin Bun launcher](./bin/pim.ts) that wraps around `pi` so that Bun-specific tooling and APIs can be used. Other Pi extensions should continue to work normally.
+
+### API Keys (Optional)
+
+Pim's web tools use [Exa](https://exa.ai) for searching the web and [Jina](https://jina.ai/reader/) for fetching websites as Markdown. Without API keys, the tools are subject to the following rate limits (as of May 2026):
+
+- Exa - 1,000 requests per month
+- Jina - 20 requests per minute
+
+For heavier usage, add API keys to `~/.pim/settings.json`:
+
+```json
+{
+  "exa": {
+    "apiKey": "api_key_here"
+  },
+  "jina": {
+    "apiKey": "api_key_here"
+  }
+}
+```
+
+Environment variables override `settings.json` when present:
+
+```sh
+EXA_API_KEY='api_key_here' JINA_API_KEY='api_key_here' pim
+```
+
+### Recommended Settings (Optional)
+
+Add the following settings to your `~/.pi/agent/settings.json` for the best experience with Pim:
+
+```json
+{
+  "quietStartup": true,
+  "editorPaddingX": 1,
+  "markdown": {
+    "codeBlockIndent": ""
+  }
+}
+```
+
+## Agent Tools
+
+Pim revamps Pi's default tools (`bash`, `read`, `write`, `edit`) and adds the following:
+
+- **`glob`** - file enumeration by glob pattern, sorted newest-first, respects `.gitignore`
+- **`grep`** - regex search across files with context lines, multiline matching, respects `.gitignore`
+- **`web_search`** - search the web via [Exa](https://exa.ai) with ranked results and snippets
+- **`web_fetch`** - fetch websites as Markdown via [Jina](https://jina.ai/reader/), with browser-rendered fallback via [`Bun.WebView`](https://bun.com/docs/runtime/webview)
+- **`subagent`** - delegate complex work to isolated sub-sessions with full tool access
+- **`todo`** - in-session task list with a live widget in the UI footer
+
+## Terminal UI
+
+Pim also ships with quality of life improvements for the TUI:
+
+- **ANSI-compatible themes** - `pim-light` and `pim-dark` themes that match your terminal's colour scheme
+- **fzf-style autocomplete** - `@path` file picker and `/command` picker with fuzzy search
+- **Git-aware powerline footer** - current dir, git branch and states, context usage, model and session cost (toggle with `/powerline`)
+- **TPS reporting** - per-cycle decode/prefill rate, TTFT, and cache read tokens (toggle with `/tps`)
+- **Concise tool headers** - minimal one-liner title across all tool calls, `Ctrl+O` to toggle full details
+
+## Telegram Bot
+
+Run Pim as a Telegram bot with full agent capabilities in your DMs or group chats (supports threads).
+
+### Setup
+
+Create `~/.pim/telegram/config.json` with your bot token (from [@BotFather](https://t.me/BotFather)) and an allowlist of chat IDs the bot will respond to:
+
+```json
+{
+  "token": "YOUR_TELEGRAM_BOT_TOKEN",
+  "allow": [123456789, 987654321]
+}
+```
+
+Then, install and run as a persistent daemon (_recommended_):
+
+```sh
+# Supports Linux (systemd) and macOS (launchd)
+pim --mode telegram --install
+
+# Tear down
+pim --mode telegram --uninstall
+```
+
+The daemon auto-restarts on failure and supports the `/update` command for in-chat updates.
+
+For development, run standalone with `pim --mode telegram` instead.
+
+### Commands
+
+> [!TIP]
+> Use `/commands` on your bot for all commands to show up on your Telegram UI.
+
+| Command      | Description                                        |
+| ------------ | -------------------------------------------------- |
+| `/cancel`    | Cancel the current turn                            |
+| `/cd`        | Show or change the working directory               |
+| `/chatid`    | Show this chat's numeric ID                        |
+| `/clear`     | Reset chat history and context window              |
+| `/commands`  | Register all commands with Telegram                |
+| `/compact`   | Compact the current session context                |
+| `/effort`    | Show or change thinking effort level               |
+| `/logs`      | Show or change log verbosity                       |
+| `/model`     | Show or change the AI model                        |
+| `/temporary` | Toggle temporary chat (fresh session each message) |
+| `/update`    | Update the bot to the latest version               |
+| `/usage`     | Show context window and session cost               |
+
+### Features
+
+- **Scheduled tasks** - your bot can create one-time, interval, or cron-based tasks that fire automatically; ask your bot to schedule something.
+- **Rich media** - send photos, documents, videos, audio, and voice messages directly in chat; your bot can also send files back to you.
+- **Thread-specific prompts** - each chat (or thread) gets its own session and instructions; ask your bot to modify its instructions.
+
+## Why Pim?
+
+### Harness Design
+
+Pim overrides Pi's default tools (`bash`, `read`, `write`, `edit`) so that all tools produce consistent, structured output for the model, cross-reference each other where useful, and render uniformly in the TUI.
+
+The system prompt is also kept as minimal as possible: at just ~3K tokens despite having 10+ tools (vs OpenCode's ~10K, Hermes' ~16K), with tool descriptions focusing on _how_ to use each tool instead of prescribing _when_. The rationale is that models already appear to internally encode when tools are needed, and prompting them to call tools can [suppress both necessary and unnecessary calls](https://arxiv.org/abs/2605.09252).
+
+### Terminal-Bench 2.0
+
+Preliminary results from two full runs:
+
+| ID | Pim Version | LLM / Model | Results |
+| --- | --- | --- | --- |
+| [r1](./benchmarks/terminal_bench_2/results/r1/) | [`21d084d1`](https://github.com/AaronCQL/pim-agent/tree/21d084d1) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **41.6%** (37/89) |
+| [r2](./benchmarks/terminal_bench_2/results/r2/) | [`bfd792cf`](https://github.com/AaronCQL/pim-agent/tree/bfd792cf) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **36.0%** (32/89) |
+
+Comparing against the same Qwen3.6-35B model, Pim solves up to **70% more tasks** than [little-coder](https://github.com/itayinbarr/little-coder) (41.6% vs 24.6%). This puts Pim, with a locally hosted model, in a similar tier to Claude Code + Sonnet 4.5 (40.1%) and above Codex + GPT-5-Mini (31.9%).
+
+The Qwen3.6-35B model is hosted via llama.cpp on an M4 Pro 48GB MacBook, with the following config:
+
+```sh
+llama-server \
+  -c 131072 \
+  -ngl 99 \
+  --slot-save-path /tmp/llama-slots \
+  --flash-attn on \
+  --cache-type-k q8_0 \
+  --cache-type-v q8_0 \
+  --jinja \
+  --temp 0.6 \
+  --top-p 0.95 \
+  --top-k 20 \
+  --min-p 0.0 \
+  --presence-penalty 0.0 \
+  --repeat-penalty 1.0 \
+  --reasoning-budget 16384 \
+  --reasoning-budget-message "Alright, I've thought enough. Let me take the next concrete step now — either a tool call or a final answer — and refine based on what I learn." \
+  -np 1
+```
+
+_Note 1_: results are preliminary as only 2 independent full runs were conducted; Terminal-Bench 2.0 requires 5 independent full runs for an official score.
+
+_Note 2_: the gap with little-coder may be partly explained by different inference configs (128K context vs 32K, Q6_K_XL vs Q4_K_M, higher thinking budget, etc.).
+
+_Note 3_: in r1, the recorded result is actually 1 higher at 38/89. However, the `code-from-image` trial was excluded because Qwen autonomously searched for the answer online after 27 legitimate turns (see line 822 in [trajectory.json](benchmarks/terminal_bench_2/results/r1/code-from-image/trajectory.json)).
+
+_Note 4_: see the [`benchmarks/terminal_bench_2`](./benchmarks/terminal_bench_2/) dir for breakdown of results and reproduction steps.
+
+## Developing
+
+```sh
+# Link locally and launch:
+bun dev
+```
+
+Pim is registered as a project-local Pi package via `.pi/settings.json` and auto-loads when launched from within this repo. Use the built-in `/reload` command to reload after edits without restarting.

package/bin/pim.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env bun
+import { dirname, join } from "node:path";
+
+const PI_PACKAGE = "@earendil-works/pi-coding-agent";
+
+function findPiCli(): string {
+  const globalCli = resolveGlobalPiCli();
+  if (globalCli) {
+    return globalCli;
+  }
+
+  try {
+    const pkgUrl = import.meta.resolve(`${PI_PACKAGE}/package.json`);
+    return join(dirname(Bun.fileURLToPath(pkgUrl)), "dist/cli.js");
+  } catch {
+    throw new Error(
+      `Pim could not locate ${PI_PACKAGE}.\n` +
+        `Install it globally under Bun: bun install -g ${PI_PACKAGE}`
+    );
+  }
+}
+
+function resolveGlobalPiCli(): string | null {
+  const result = Bun.spawnSync({ cmd: ["bun", "pm", "-g", "bin"] });
+  if (result.exitCode !== 0) {
+    return null;
+  }
+  const binDir = result.stdout.toString().trim();
+  if (!binDir) {
+    return null;
+  }
+  const cliPath = join(
+    binDir,
+    "..",
+    "install",
+    "global",
+    "node_modules",
+    PI_PACKAGE,
+    "dist",
+    "cli.js"
+  );
+  return Bun.file(cliPath).size > 0 ? cliPath : null;
+}
+
+const cliArgs = process.argv.slice(2);
+
+// Pi's argparse rejects prompts beginning with `-` and doesn't honour `--`
+// itself; do the split here and forward the prompt via pi's stdin instead.
+const dashDashIdx = cliArgs.indexOf("--");
+let promptViaStdin: string | undefined;
+if (dashDashIdx >= 0) {
+  promptViaStdin = cliArgs.slice(dashDashIdx + 1).join(" ");
+  cliArgs.length = dashDashIdx;
+}
+
+const modeIdx = cliArgs.findIndex(
+  (a) => a === "--mode" || a.startsWith("--mode=")
+);
+const mode =
+  modeIdx >= 0
+    ? cliArgs[modeIdx]!.includes("=")
+      ? cliArgs[modeIdx]!.split("=")[1]
+      : cliArgs[modeIdx + 1]
+    : undefined;
+if (mode === "telegram") {
+  if (cliArgs.includes("--install")) {
+    const { Supervisor } = await import("../src/telegram/Supervisor.ts");
+    await Supervisor.install();
+    process.exit(0);
+  }
+  if (cliArgs.includes("--uninstall")) {
+    const { Supervisor } = await import("../src/telegram/Supervisor.ts");
+    await Supervisor.uninstall();
+    process.exit(0);
+  }
+  const { start } = await import("../src/telegram/index.ts");
+  await start(cliArgs);
+  process.exit(0);
+}
+
+const piCli = findPiCli();
+const proc = Bun.spawn({
+  cmd: [process.execPath, piCli, ...cliArgs],
+  stdio: [
+    promptViaStdin === undefined ? "inherit" : "pipe",
+    "inherit",
+    "inherit",
+  ],
+  env: process.env,
+});
+if (promptViaStdin !== undefined && proc.stdin) {
+  proc.stdin.write(promptViaStdin);
+  proc.stdin.end();
+}
+// Forward shutdown signals so pi's bash subtrees aren't orphaned on the host.
+for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {
+  process.once(sig, () => {
+    try {
+      proc.kill(sig);
+    } catch {}
+  });
+}
+const exitCode = await proc.exited;
+const signalCode = proc.signalCode as NodeJS.Signals | null;
+if (signalCode) {
+  process.kill(process.pid, signalCode);
+} else {
+  process.exit(exitCode ?? 0);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@aaroncql/pim-agent",
+  "version": "0.0.1",
+  "description": "Pim is to Pi what Vim is to Vi.",
+  "type": "module",
+  "bin": {
+    "pim": "bin/pim.ts"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "bun": ">=1.2.7"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extensions"
+    ],
+    "themes": [
+      "./src/themes"
+    ]
+  },
+  "scripts": {
+    "dev": "bun link && pim",
+    "typecheck": "tsgo --noEmit",
+    "test": "bun test src --only-failures",
+    "lint": "oxlint . --fix",
+    "format": "prettier --write --list-different package.json tsconfig.json .oxlintrc.json .prettierrc.json \"src/**/*.ts\" \"bin/**/*.ts\" \"**/*.md\"",
+    "check": "bun run typecheck && bun run test && bun run lint && bun run format"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.76.0",
+    "@types/bun": "latest",
+    "@typescript/native-preview": "^7.0.0-dev.20260505.1",
+    "oxlint": "^1.62.0",
+    "prettier": "^3.8.3"
+  },
+  "dependencies": {
+    "diff": "^9.0.0",
+    "fzf": "^0.5.2",
+    "grammy": "^1.42.0",
+    "ignore": "^7.0.5",
+    "ky": "^2.0.2"
+  }
+}

package/src/extensions/_init/index.ts

@@ -0,0 +1,109 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+const SPLASH_ID = "pim-splash";
+
+const shortcuts = [
+  ["Ctrl+C", "Clear editor (first) / exit (second)"],
+  ["Escape", "Cancel autocomplete / abort streaming"],
+  ["/<command>", "Slash commands", "<command>"],
+  ["/hotkeys", "Show all keyboard shortcuts"],
+  ["/settings", "Open settings menu"],
+  ["/powerline", "Toggle Pim powerline footer"],
+  ["@<path>", "Attach files", "<path>"],
+  ["!<command>", "Run bash command", "<command>"],
+  ["!!<command>", "Run bash command (excluded from context)", "<command>"],
+] as const;
+
+export default async function (pi: ExtensionAPI): Promise<void> {
+  if (typeof Bun === "undefined") {
+    throw new Error(
+      "Pim requires the Bun runtime.\n" +
+        "Install pi via bun: bun install -g @earendil-works/pi-coding-agent\n" +
+        "Then run: pim"
+    );
+  }
+
+  const pkgPath = `${import.meta.dir}/../../../package.json`;
+  const { version } = (await Bun.file(pkgPath).json()) as { version: string };
+
+  const keyCol = Math.max(...shortcuts.map(([k]) => k.length)) + 2;
+
+  let splashShown = false;
+
+  pi.on("session_start", (event, ctx) => {
+    if (event.reason !== "startup" && event.reason !== "new") {
+      return;
+    }
+
+    const theme = ctx.ui.theme;
+    const renderKey = (key: string, muted: string | undefined): string => {
+      const padding = " ".repeat(Math.max(0, keyCol - key.length));
+      if (!muted) {
+        return theme.fg("mdCode", key + padding);
+      }
+      const idx = key.indexOf(muted);
+      if (idx === -1) {
+        return theme.fg("mdCode", key + padding);
+      }
+      return (
+        theme.fg("mdCode", key.slice(0, idx)) +
+        theme.fg("muted", muted) +
+        key.slice(idx + muted.length) +
+        padding
+      );
+    };
+
+    const title =
+      theme.bold(theme.fg("accent", "PIM - Pi IMproved")) +
+      " " +
+      theme.italic(theme.fg("muted", `v${version}`));
+    ctx.ui.setWidget(SPLASH_ID, [
+      title,
+      ...shortcuts.map(
+        ([k, d, muted]) => renderKey(k, muted) + theme.fg("dim", d)
+      ),
+    ]);
+    splashShown = true;
+  });
+
+  const clearSplash = (ctx: ExtensionContext) => {
+    if (splashShown) {
+      ctx.ui.setWidget(SPLASH_ID, undefined);
+      splashShown = false;
+    }
+  };
+
+  pi.on("input", (_event, ctx) => {
+    clearSplash(ctx);
+    return { action: "continue" };
+  });
+  pi.on("user_bash", (_event, ctx) => {
+    clearSplash(ctx);
+  });
+  pi.on("model_select", (_event, ctx) => {
+    clearSplash(ctx);
+  });
+  pi.on("thinking_level_select", (_event, ctx) => {
+    clearSplash(ctx);
+  });
+  pi.on("session_before_fork", (_event, ctx) => {
+    clearSplash(ctx);
+  });
+  pi.on("session_before_tree", (_event, ctx) => {
+    clearSplash(ctx);
+  });
+  pi.on("session_before_compact", (_event, ctx) => {
+    clearSplash(ctx);
+  });
+
+  pi.registerCommand("clear", {
+    description: "Start a new session (alias: /new)",
+    handler: async (_args, ctx) => {
+      await ctx.waitForIdle();
+      await ctx.newSession();
+    },
+  });
+}

package/src/extensions/bash/capture.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import { concat, StreamCapture } from "./capture";
+import { STREAM_HEAD_BYTES, STREAM_TAIL_BYTES } from "./schema";
+
+const enc = new TextEncoder();
+const u8 = (s: string) => enc.encode(s);
+
+describe("concat", () => {
+  test("merges multiple chunks in order", () => {
+    const out = concat([u8("foo"), u8("bar")], 6);
+    expect(new TextDecoder().decode(out)).toBe("foobar");
+  });
+
+  test("returns empty array when total is 0", () => {
+    expect(concat([], 0).byteLength).toBe(0);
+  });
+});
+
+describe("StreamCapture", () => {
+  test("empty capture", () => {
+    const c = new StreamCapture();
+    expect(c.snapshot()).toEqual({
+      text: "",
+      totalBytes: 0,
+      truncated: false,
+      path: null,
+      nextStart: null,
+    });
+  });
+
+  test("ignores zero-byte chunks", () => {
+    const c = new StreamCapture();
+    c.push(new Uint8Array(0));
+    c.push(u8("hi"));
+    expect(c.snapshot()).toEqual({
+      text: "hi",
+      totalBytes: 2,
+      truncated: false,
+      path: null,
+      nextStart: null,
+    });
+  });
+
+  test("does not truncate when within head+tail budget", () => {
+    const c = new StreamCapture();
+    c.push(u8("hello"));
+    c.push(u8(" world"));
+    expect(c.snapshot()).toEqual({
+      text: "hello world",
+      totalBytes: 11,
+      truncated: false,
+      path: null,
+      nextStart: null,
+    });
+  });
+
+  test("truncates middle when over budget", () => {
+    const c = new StreamCapture();
+    const headChunk = "A".repeat(STREAM_HEAD_BYTES);
+    const middleChunk = "X".repeat(1000);
+    const tailChunk = "B".repeat(STREAM_TAIL_BYTES);
+    c.push(u8(headChunk));
+    c.push(u8(middleChunk));
+    c.push(u8(tailChunk));
+
+    const snap = c.snapshot();
+    expect(snap.truncated).toBe(true);
+    expect(snap.totalBytes).toBe(STREAM_HEAD_BYTES + 1000 + STREAM_TAIL_BYTES);
+    expect(snap.text.startsWith(headChunk)).toBe(true);
+    expect(snap.text.endsWith(tailChunk)).toBe(true);
+    expect(snap.text).toContain(`... ${1000} bytes truncated ...`);
+    expect(snap.nextStart).toBe(1);
+  });
+
+  test("reports the resume line at the end of the head when truncated", () => {
+    const c = new StreamCapture();
+    const lineBytes = STREAM_HEAD_BYTES / 4;
+    const headChunk = `${"A".repeat(lineBytes - 1)}\n`.repeat(4);
+    c.push(u8(headChunk));
+    c.push(u8("X".repeat(1000)));
+    c.push(u8("B".repeat(STREAM_TAIL_BYTES)));
+
+    const snap = c.snapshot();
+    expect(snap.truncated).toBe(true);
+    // Head holds exactly 4 newline-terminated lines, so reading resumes at 5.
+    expect(snap.nextStart).toBe(5);
+  });
+
+  test("splits a single chunk between head and tail when needed", () => {
+    const c = new StreamCapture();
+    const big = "Z".repeat(STREAM_HEAD_BYTES + STREAM_TAIL_BYTES + 500);
+    c.push(u8(big));
+
+    const snap = c.snapshot();
+    expect(snap.truncated).toBe(true);
+    expect(snap.totalBytes).toBe(big.length);
+    expect(snap.text.startsWith("Z".repeat(STREAM_HEAD_BYTES))).toBe(true);
+    expect(snap.text.endsWith("Z".repeat(STREAM_TAIL_BYTES))).toBe(true);
+    expect(snap.text).toContain(`... ${500} bytes truncated ...`);
+  });
+
+  test("keeps head and final tail when many middle chunks arrive", () => {
+    const c = new StreamCapture();
+    const HEAD_FILL = "A".repeat(STREAM_HEAD_BYTES);
+    c.push(u8(HEAD_FILL));
+    for (let i = 0; i < 100; i++) {
+      c.push(u8("M".repeat(STREAM_TAIL_BYTES)));
+    }
+    const finalTail = "B".repeat(STREAM_TAIL_BYTES);
+    c.push(u8(finalTail));
+
+    const snap = c.snapshot();
+    expect(snap.truncated).toBe(true);
+    expect(snap.text.startsWith(HEAD_FILL)).toBe(true);
+    expect(snap.text.endsWith(finalTail)).toBe(true);
+  });
+
+  test("at exact head+tail boundary is not truncated", () => {
+    const c = new StreamCapture();
+    c.push(u8("A".repeat(STREAM_HEAD_BYTES)));
+    c.push(u8("B".repeat(STREAM_TAIL_BYTES)));
+    const snap = c.snapshot();
+    expect(snap.truncated).toBe(false);
+    expect(snap.totalBytes).toBe(STREAM_HEAD_BYTES + STREAM_TAIL_BYTES);
+  });
+});