@te-river/opencode-team-mode 1.8.2 → 1.8.4

package/dist/host/v2-prune.d.ts

@@ -21,6 +21,19 @@
  *    protected STRING: the message may be pruned, but the stub must carry the
  *    handle verbatim, which is exactly the "keep the pointer, drop the body"
  *    contract.
+ *  - **Nothing leaves that cannot be recovered.**  A message carrying no handle
+ *    of its own is offloaded to the run store BEFORE its body is replaced, so
+ *    the stub carries a full `tm_fetch` handle (`pruneOffload`, default on).  A
+ *    failed offload falls back to today's echo note, one message at a time —
+ *    losing a body is data loss, losing an offload is a counter.  A stub with no
+ *    handle to offer still carries the ADDRESSES the body named (board paths,
+ *    `file:line`, URLs; at most three, deduplicated, in document order), because a
+ *    pointer the reader can act on is the whole point of keeping one — and that
+ *    scan is SINGLE-PASS and linear in the body length, not three global regexes
+ *    over the whole text (which went quadratic on a long word run).
+ *  - **A user pattern outranks the budget** (`pruneProtectPatterns`): a message
+ *    whose text matches any compiled entry is never pruned, and the matches are
+ *    counted (`protectMatched`) instead of silently changing the saving figure.
  *  - **The threshold is derived, never hard-coded.**  `TM_PRUNE_AT_PERCENT`
  *    (default 70) of `limit.context`, the same denominator the desktop's own
  *    usage meter reads.  No `limit.context` → no prune, counted `no_limit`.
@@ -40,11 +53,24 @@ export interface PruneConfig {
     atPercent: number;
     /** Percent of `limit.context` kept verbatim at the tail (clamped 0–90). */
     keepTailPercent: number;
+    /**
+     * User-supplied protection regexes (`pruneProtectPatterns`, comma separated).
+     * A message whose text matches ANY of them is never pruned.  Empty = off, and
+     * that is the byte-identical path: the list is consulted only when non-empty.
+     */
+    protectPatterns: RegExp[];
 }
+/**
+ * Compile the comma-separated pattern list.  One invalid pattern loses only
+ * itself (a typo must not disable the ones next to it, and must never throw into
+ * the request path); an empty / absent value compiles to `[]` = off.
+ */
+export declare function parseProtectPatterns(raw: unknown): RegExp[];
 export declare function resolvePruneConfig(config?: {
     prune: string;
     pruneAtPercent: number;
     pruneKeepTailPercent: number;
+    pruneProtectPatterns?: string;
 }): PruneConfig;
 interface TextSlot {
     container: Record<string, unknown>;
@@ -86,13 +112,43 @@ export interface PruneHandle {
     ref: string;
     accessToken: string;
     expireAt: number;
+    /** Set when the wiring recognised this body and handed back an EXISTING handle. */
+    reused?: boolean;
 }
+/** 地址行最多留几条——再多就不是「地址」，而是正文摘抄。 */
+export declare const PRUNE_ADDRESS_MAX = 3;
+/** 地址行的前缀；整行只在真的抽到地址时出现。 */
+export declare const PRUNE_ADDRESS_PREFIX = "\u5730\u5740\uFF1A";
+/**
+ * 单个 token 的字符上限。  超过它的不是地址，是正文——这条上限也是性能闸门：
+ * 长词串整段跳过，永远不会进到正则里。
+ */
+export declare const PRUNE_ADDRESS_TOKEN_MAX = 2048;
+/**
+ * The addresses a pruned body carried, in DOCUMENT ORDER, deduplicated, at most
+ * `PRUNE_ADDRESS_MAX`.  Pure, and it only ever yields the address itself — never a
+ * fragment of the body around it, because the stub is a pointer, not a summary.
+ *
+ * LINEAR BY CONSTRUCTION (this is a performance contract, not a style note): the
+ * text is walked ONCE, token by token, and every pattern is anchored to a single
+ * token.  The previous version ran three GLOBAL regexes over the whole body and
+ * blanked each URL match by rebuilding the string — quadratic on a long word run
+ * (`"a".repeat(200000)` was hundreds of seconds) and O(k·n) with many URLs.  A
+ * token longer than `PRUNE_ADDRESS_TOKEN_MAX` is skipped without touching a regex.
+ *
+ * A longer address that CONTAINS a shorter one wins: `…/v2-prune.ts:120` is the
+ * pointer a reader can use, while `…/v2-prune.ts` would send them hunting for the
+ * line the message was about.
+ */
+export declare function extractAddresses(text: string): string[];
 export interface PruneStubInput {
-    kind: "handle" | "child" | "echo";
+    kind: "handle" | "child" | "echo" | "offload";
     originalTokens: number;
     handle?: PruneHandle;
     childId?: string;
     childState?: string;
+    /** Addresses found in the body — rendered as one `地址：` line, or omitted whole. */
+    addresses?: string[];
 }
 /**
  * The replacement text.  It must be self-explanatory: a reader has to know what
@@ -109,6 +165,8 @@ export interface PrunePlanEntry {
 export interface PrunePlan {
     prune: PrunePlanEntry[];
     protectedCount: number;
+    /** Messages a user-supplied `pruneProtectPatterns` entry kept (a subset of the kept ones). */
+    protectMatched: number;
     keptCount: number;
     savedTokens: number;
 }
@@ -117,6 +175,8 @@ export interface PrunePlanOptions {
     budgetTokens?: number;
     /** Newest messages whose cumulative tokens fit here are kept verbatim. */
     keepTailTokens?: number;
+    /** User patterns: any hit keeps that message, whatever the budget says. */
+    protectPatterns?: RegExp[];
 }
 /**
  * Decide which messages to prune, oldest first, until the request fits the
@@ -138,8 +198,22 @@ export interface PruneReport {
     noMessages: number;
     foreignSkipped: number;
     threw: number;
+    /** Bodies stored in the run store before their message was replaced. */
+    offloaded: number;
+    /** Handle reused for a body an earlier request already stored (no second write). */
+    reused: number;
+    /** Messages whose offload failed (or returned no handle) → echo stub. */
+    offloadFailed: number;
+    /** Requests whose post-prune size still exceeds the budget (counted, never re-pruned). */
+    overBudget: number;
+    /** Bodies stored for a request whose plan never landed — payloads with no pointer. */
+    orphans: number;
     /** Parts whose `type` we did not recognise — a renamed shape shows up here. */
     unknownParts: number;
+    /** Compiled `pruneProtectPatterns` entries (a value that failed to parse is not counted here). */
+    protectPatterns: number;
+    /** Messages a protect pattern kept out of the plan this process. */
+    protectMatched: number;
     lastPercent: number;
     lastUsed: number;
     lastLimit: number;
@@ -151,6 +225,12 @@ export interface PruneInput {
     modelLimitOf?: (sessionID: string, messages: unknown[]) => Promise<number | null> | number | null;
     /** Per-decision trajectory line (counters alone are invisible in a CLI run). */
     onEvent?: (row: Record<string, unknown>) => void;
+    /**
+     * Store one message body and hand back its handle.  Absent = today's
+     * behaviour (echo stub, body not kept) — the wiring passes it only while
+     * `pruneOffload` is on.
+     */
+    offload?: (text: string) => Promise<PruneHandle | null>;
 }
 export interface PruneLayer {
     registrations: V2Registration[];

package/dist/host/v2-prune.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v2-prune.d.ts","sourceRoot":"","sources":["../../src/host/v2-prune.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"v2-prune.d.ts","sourceRoot":"","sources":["../../src/host/v2-prune.ts"],"names":[],"mappings":"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"}

package/dist/host/v2-prune.js

@@ -21,6 +21,19 @@
  *    protected STRING: the message may be pruned, but the stub must carry the
  *    handle verbatim, which is exactly the "keep the pointer, drop the body"
  *    contract.
+ *  - **Nothing leaves that cannot be recovered.**  A message carrying no handle
+ *    of its own is offloaded to the run store BEFORE its body is replaced, so
+ *    the stub carries a full `tm_fetch` handle (`pruneOffload`, default on).  A
+ *    failed offload falls back to today's echo note, one message at a time —
+ *    losing a body is data loss, losing an offload is a counter.  A stub with no
+ *    handle to offer still carries the ADDRESSES the body named (board paths,
+ *    `file:line`, URLs; at most three, deduplicated, in document order), because a
+ *    pointer the reader can act on is the whole point of keeping one — and that
+ *    scan is SINGLE-PASS and linear in the body length, not three global regexes
+ *    over the whole text (which went quadratic on a long word run).
+ *  - **A user pattern outranks the budget** (`pruneProtectPatterns`): a message
+ *    whose text matches any compiled entry is never pruned, and the matches are
+ *    counted (`protectMatched`) instead of silently changing the saving figure.
  *  - **The threshold is derived, never hard-coded.**  `TM_PRUNE_AT_PERCENT`
  *    (default 70) of `limit.context`, the same denominator the desktop's own
  *    usage meter reads.  No `limit.context` → no prune, counted `no_limit`.
@@ -40,6 +53,28 @@ const CHILD_ID_RE = /ses_[A-Za-z0-9]+/;
 const SETTLED_STATE_RE = /state\s*=\s*"(?:completed|error)"/i;
 const RUNNING_STATE_RE = /state\s*=\s*"(?:running|pending|in[_-]?progress)"/i;
 const HANDLE_RE = /ref\s*:\s*"([^"]+)"[\s\S]*?access_token\s*:\s*"([^"]+)"[\s\S]*?expire_at\s*:\s*(\d+)/;
+/**
+ * Compile the comma-separated pattern list.  One invalid pattern loses only
+ * itself (a typo must not disable the ones next to it, and must never throw into
+ * the request path); an empty / absent value compiles to `[]` = off.
+ */
+export function parseProtectPatterns(raw) {
+    if (typeof raw !== "string" || !raw.trim())
+        return [];
+    const out = [];
+    for (const part of raw.split(",")) {
+        const src = part.trim();
+        if (!src)
+            continue;
+        try {
+            out.push(new RegExp(src));
+        }
+        catch {
+            /* an invalid regex is ignored, never fatal */
+        }
+    }
+    return out;
+}
 const isOff = (v) => typeof v === "string" && ["off", "false", "0", "no"].includes(v.trim().toLowerCase());
 export function resolvePruneConfig(config = resolveConfig()) {
     return {
@@ -49,6 +84,7 @@ export function resolvePruneConfig(config = resolveConfig()) {
         // prune is looking at the clamp, not at a broken layer.
         atPercent: config.pruneAtPercent,
         keepTailPercent: config.pruneKeepTailPercent,
+        protectPatterns: parseProtectPatterns(config.pruneProtectPatterns),
     };
 }
 /**
@@ -243,7 +279,142 @@ export function isProtectedMessage(msg) {
         return true;
     return false;
 }
+/** 地址行最多留几条——再多就不是「地址」，而是正文摘抄。 */
+export const PRUNE_ADDRESS_MAX = 3;
+/** 地址行的前缀；整行只在真的抽到地址时出现。 */
+export const PRUNE_ADDRESS_PREFIX = "地址：";
+/**
+ * 单个 token 的字符上限。  超过它的不是地址，是正文——这条上限也是性能闸门：
+ * 长词串整段跳过，永远不会进到正则里。
+ */
+export const PRUNE_ADDRESS_TOKEN_MAX = 2048;
+/**
+ * Token separators.  `<` / `>` are deliberately NOT separators: the board note
+ * publishes `<board-root>/…md`, and splitting on the angle brackets would strip
+ * the placeholder off the address it belongs to.
+ */
+const ADDRESS_SEPARATORS = new Set([" ", "\t", "\n", "\r", "\f", "\v", '"', "'", "|", "`", ";", ",", "(", ")"]);
+/** A cheap anchored pre-filter: only these suffixes can be a path address. */
+const PATH_EXT_RE = /\.(?:md|json|jsonl|txt|log|ts|tsx|js|py|yml|yaml)$/;
+/** `file:line` / `file:line:col`, ANCHORED inside one token (no per-start retry). */
+const FILE_LINE_TOKEN_RE = /^(?:[A-Za-z]:)?[\w./\\-]+:\d+(?::\d+)?$/;
+/**
+ * A path-shaped token with a KNOWN extension: `C:\…\01-team-report.md`,
+ * `/x/y/z.json`, `<board-root>/…md`, `src/host/v2-prune.ts`.  The leading run is
+ * optional (drive letter, an angle-bracket placeholder, a relative first
+ * segment); every further segment must start with a separator, which is what
+ * keeps a bare `v2-prune.ts` from being called an address.  BOTH ENDS ANCHORED:
+ * the engine never re-tries every start position, which is the whole point of
+ * the token pass.
+ */
+const PATH_TOKEN_RE = /^(?:[A-Za-z]:|<[^>\s]+>|[^\s"'<>|`;,():\/\\]+)?(?:[\/\\][^\s"'<>|`;,():\/\\]+)+\.(?:md|json|jsonl|txt|log|ts|tsx|js|py|yml|yaml)$/;
+/** Strip the `<`/`>` a prose writer may have wrapped an address in. */
+const trimAngles = (s) => s.replace(/^</, "").replace(/>+$/, "");
+/**
+ * The first `http(s)://` inside a token, or -1.  `indexOf` is linear, and it is
+ * how an address glued to Chinese text (`看https://…`) is still recovered —
+ * without a cross-text regex that would try every start position.
+ */
+function urlAt(token) {
+    const a = token.indexOf("http://");
+    const b = token.indexOf("https://");
+    if (a < 0)
+        return b;
+    if (b < 0)
+        return a;
+    return Math.min(a, b);
+}
+/** Retry a token from its first path separator: `见：/a/one.md` → `/a/one.md`. */
+function tailFromSeparator(token) {
+    const a = token.indexOf("/");
+    const b = token.indexOf("\\");
+    const cut = a < 0 ? b : b < 0 ? a : Math.min(a, b);
+    return cut > 0 ? token.slice(cut) : null;
+}
+/**
+ * The addresses a pruned body carried, in DOCUMENT ORDER, deduplicated, at most
+ * `PRUNE_ADDRESS_MAX`.  Pure, and it only ever yields the address itself — never a
+ * fragment of the body around it, because the stub is a pointer, not a summary.
+ *
+ * LINEAR BY CONSTRUCTION (this is a performance contract, not a style note): the
+ * text is walked ONCE, token by token, and every pattern is anchored to a single
+ * token.  The previous version ran three GLOBAL regexes over the whole body and
+ * blanked each URL match by rebuilding the string — quadratic on a long word run
+ * (`"a".repeat(200000)` was hundreds of seconds) and O(k·n) with many URLs.  A
+ * token longer than `PRUNE_ADDRESS_TOKEN_MAX` is skipped without touching a regex.
+ *
+ * A longer address that CONTAINS a shorter one wins: `…/v2-prune.ts:120` is the
+ * pointer a reader can use, while `…/v2-prune.ts` would send them hunting for the
+ * line the message was about.
+ */
+export function extractAddresses(text) {
+    if (!text)
+        return [];
+    const found = [];
+    const n = text.length;
+    let i = 0;
+    while (i < n) {
+        while (i < n && ADDRESS_SEPARATORS.has(text[i]))
+            i++;
+        if (i >= n)
+            break;
+        const start = i;
+        while (i < n && !ADDRESS_SEPARATORS.has(text[i]))
+            i++;
+        const token = text.slice(start, i);
+        if (token.length > PRUNE_ADDRESS_TOKEN_MAX)
+            continue;
+        // URL first: its own path must never be counted as a second address.
+        const scheme = urlAt(token);
+        if (scheme >= 0) {
+            const address = trimAngles(token.slice(scheme));
+            if (address.length > 8)
+                found.push({ at: start + scheme, address });
+            continue;
+        }
+        // `file:line` — a prefix with no separator is a word (`expire_at:9`), not a path.
+        if (token.includes(":") && /\d$/.test(token)) {
+            const direct = FILE_LINE_TOKEN_RE.test(token) ? token : null;
+            const candidate = direct ?? tailFromSeparator(token);
+            if (candidate && FILE_LINE_TOKEN_RE.test(candidate)) {
+                const cut = candidate.lastIndexOf(":");
+                if (/[\/\\]/.test(candidate.slice(0, cut))) {
+                    found.push({ at: start, address: candidate });
+                    continue;
+                }
+            }
+        }
+        if (PATH_EXT_RE.test(token)) {
+            const direct = PATH_TOKEN_RE.test(token) ? token : null;
+            const tail = direct ? null : tailFromSeparator(token);
+            const candidate = direct ?? (tail && PATH_EXT_RE.test(tail) && PATH_TOKEN_RE.test(tail) ? tail : null);
+            if (candidate)
+                found.push({ at: start, address: candidate });
+        }
+    }
+    // Tokens are already in document order; the sort stays because an embedded URL
+    // reports an offset inside its token, and "document order" is what the reader
+    // expects either way.
+    found.sort((a, b) => a.at - b.at);
+    const out = [];
+    for (const { address } of found) {
+        if (out.some((kept) => kept.includes(address)))
+            continue;
+        if (found.some((o) => o.address !== address && o.address.includes(address)))
+            continue;
+        out.push(address);
+        if (out.length >= PRUNE_ADDRESS_MAX)
+            break;
+    }
+    return out;
+}
 const withCommas = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+/** One trailing line carrying the recoverable addresses; "" when none were found. */
+function addressLine(addresses) {
+    if (!addresses || !addresses.length)
+        return "";
+    return `\n${PRUNE_ADDRESS_PREFIX}${addresses.join(" · ")}`;
+}
 /**
  * The replacement text.  It must be self-explanatory: a reader has to know what
  * used to be here and where to get it back.  The handle / child id is copied
@@ -257,7 +428,15 @@ export function renderPruneStub(entry) {
     if (entry.kind === "child" && entry.childId) {
         return `${head} 子代理 ${entry.childId} 的报告已结算（state=${entry.childState ?? "completed"}）；需要原文用 tm_join { ids:["${entry.childId}"] } 取回。`;
     }
-    return `${head} 已结算的工具输出/命令回显，正文已裁剪；如需重看请重跑原命令，或从轨迹（tm_stats { recent: N }）取回。`;
+    if (entry.kind === "offload" && entry.handle) {
+        // Deliberately different wording from the tool-result stub above: this body
+        // had NO handle until the prune created one, so "re-run the command" would
+        // be wrong advice — the bytes are in the store, not behind a command.
+        return `${head} 本条消息已卸载：tm_fetch { ref:"${entry.handle.ref}", access_token:"${entry.handle.accessToken}", expire_at:${entry.handle.expireAt} }。原文可回取（TTL 由 blackboardTtlDays 决定），不要重跑。${addressLine(entry.addresses)}`;
+    }
+    // The echo stub is the one that keeps NO copy of the body, so the addresses it
+    // reports are the only thing the next round can still act on.
+    return `${head} 已结算的工具输出/命令回显，正文已裁剪；如需重看请重跑原命令，或从轨迹（tm_stats { recent: N }）取回。${addressLine(entry.addresses)}`;
 }
 function extractHandle(text) {
     const m = HANDLE_RE.exec(text);
@@ -279,18 +458,21 @@ function buildStub(text, tokens) {
     const child = extractChild(text);
     if (child)
         return { kind: "child", stub: renderPruneStub({ kind: "child", originalTokens: tokens, childId: child.id, childState: child.state }) };
-    return { kind: "echo", stub: renderPruneStub({ kind: "echo", originalTokens: tokens }) };
+    // Only the branches that carry no recoverable pointer get the address line: a
+    // handle already says where the bytes are, and a child id where the report is.
+    return { kind: "echo", stub: renderPruneStub({ kind: "echo", originalTokens: tokens, addresses: extractAddresses(text) }) };
 }
 /**
  * Decide which messages to prune, oldest first, until the request fits the
  * budget.  Pure: it reads the messages and returns a plan; nothing is mutated.
  */
 export function prunePlan(messages, opts = {}) {
-    const plan = { prune: [], protectedCount: 0, keptCount: 0, savedTokens: 0 };
+    const plan = { prune: [], protectedCount: 0, protectMatched: 0, keptCount: 0, savedTokens: 0 };
     if (!Array.isArray(messages) || messages.length === 0)
         return plan;
     const keepTailTokens = Math.max(0, opts.keepTailTokens ?? 0);
     const budgetTokens = opts.budgetTokens ?? Number.POSITIVE_INFINITY;
+    const protectPatterns = opts.protectPatterns ?? [];
     // The tail boundary: walk from the newest message until the cumulative token
     // count would exceed the tail budget.  The newest message is ALWAYS protected.
     let acc = 0;
@@ -307,6 +489,13 @@ export function prunePlan(messages, opts = {}) {
     let saved = 0;
     for (let i = 0; i < tailStart; i++) {
         const msg = messages[i];
+        if (protectPatterns.length) {
+            const body = messageText(msg);
+            if (body && protectPatterns.some((re) => re.test(body))) {
+                plan.protectMatched++;
+                continue;
+            }
+        }
         if (isProtectedMessage(msg)) {
             plan.protectedCount++;
             continue;
@@ -342,6 +531,63 @@ export function applyPrunePlan(messages, plan) {
             slots[i].container[slots[i].key] = "";
     }
 }
+/**
+ * Offload a planned body BEFORE its message is rewritten, so the stub can carry
+ * a real `tm_fetch` handle.  Only `echo` entries are offloaded: a `handle` entry
+ * already points at a payload (offloading it again would duplicate the bytes) and
+ * a `child` entry points at a session (its body lives in the child, not here).
+ *
+ * Failure is BOUNDED and per message: one throw degrades that one stub to today's
+ * echo note and increments a counter — the remaining plan still runs, and the
+ * caller's hook never sees an exception.  `savedTokens` is recomputed afterwards
+ * because a handle stub is longer than an echo note, and a reported saving that
+ * did not happen is exactly the kind of claim this product refuses.
+ */
+async function offloadPlannedBodies(messages, plan, offload, onFailure, report, sessionID) {
+    if (!offload || plan.prune.length === 0)
+        return;
+    let saved = 0;
+    for (const entry of plan.prune) {
+        const text = entry.kind === "echo" ? messageText(messages[entry.index]) : "";
+        if (entry.kind === "echo" && text) {
+            let handle = null;
+            let failure = null;
+            try {
+                handle = await offload(text);
+                if (!handle || !handle.ref || !handle.accessToken || !Number.isFinite(handle.expireAt)) {
+                    failure = { reason: handle ? "invalid" : "empty" };
+                }
+            }
+            catch (err) {
+                failure = { reason: "threw", error: String(err?.message ?? err).slice(0, 120) };
+            }
+            if (handle && !failure) {
+                entry.kind = "offload";
+                entry.stub = renderPruneStub({
+                    kind: "offload",
+                    originalTokens: entry.originalTokens,
+                    handle,
+                    // The offload stub points at bytes a reader may not want to page
+                    // through; the addresses are what they can act on in one round.
+                    addresses: extractAddresses(text),
+                });
+                // A dedupe hit means these bytes are ALREADY in the store — counting it as
+                // a fresh offload would report a saving that was not made, and would make
+                // the card's "上轮修剪" line grow on a replayed request.
+                if (handle.reused)
+                    report.reused++;
+                else
+                    report.offloaded++;
+            }
+            else {
+                report.offloadFailed++;
+                onFailure({ sessionID, index: entry.index, ...(failure ?? {}) });
+            }
+        }
+        saved += Math.max(0, entry.originalTokens - estimateTokens(entry.stub));
+    }
+    plan.savedTokens = saved;
+}
 /** The default denominator: `ctx.model.list()` keyed by the session's model,
  *  the same lookup the desktop's usage meter and this package's usage readers use. */
 function defaultModelLimitOf(ctx) {
@@ -409,6 +655,9 @@ function defaultModelLimitOf(ctx) {
 }
 export async function applyV2ContextPrune(ctx, input = {}) {
     const config = input.config ?? resolvePruneConfig();
+    // A hand-built config (a test, an embedder) may predate the pattern list; `[]` is
+    // the "off" path, so tolerating it changes no behaviour and throws nothing.
+    const protectPatterns = config.protectPatterns ?? [];
     const report = {
         enabled: config.enabled,
         atPercent: config.atPercent,
@@ -422,7 +671,14 @@ export async function applyV2ContextPrune(ctx, input = {}) {
         noMessages: 0,
         foreignSkipped: 0,
         threw: 0,
+        offloaded: 0,
+        reused: 0,
+        offloadFailed: 0,
+        overBudget: 0,
+        orphans: 0,
         unknownParts: 0,
+        protectPatterns: protectPatterns.length,
+        protectMatched: 0,
         lastPercent: 0,
         lastUsed: 0,
         lastLimit: 0,
@@ -475,21 +731,50 @@ export async function applyV2ContextPrune(ctx, input = {}) {
             }
             const budgetTokens = Math.floor((limit * config.atPercent) / 100);
             const keepTailTokens = Math.floor((limit * config.keepTailPercent) / 100);
-            const plan = prunePlan(messages, { budgetTokens, keepTailTokens });
-            applyPrunePlan(messages, plan);
-            report.prunedMessages += plan.prune.length;
-            report.prunedTokens += plan.savedTokens;
-            report.skippedProtected += plan.protectedCount;
-            emit("prune", {
-                sessionID,
-                percent: pct,
-                used,
-                limit,
-                pruned: plan.prune.length,
-                saved: plan.savedTokens,
-                protected: plan.protectedCount,
-                unknown: report.unknownParts,
-            });
+            const plan = prunePlan(messages, { budgetTokens, keepTailTokens, protectPatterns });
+            const freshBefore = report.offloaded;
+            await offloadPlannedBodies(messages, plan, input.offload, (row) => emit("prune_offload_failed", row), report, sessionID);
+            try {
+                applyPrunePlan(messages, plan);
+                // A handle stub is longer than the echo note it replaced, so the plan's
+                // own arithmetic can land ABOVE the budget.  Counted, never silently
+                // re-pruned: a second pass would have to offload again to be lossless.
+                const overBudget = messagesTokens(messages) > budgetTokens;
+                if (overBudget)
+                    report.overBudget++;
+                report.prunedMessages += plan.prune.length;
+                report.prunedTokens += plan.savedTokens;
+                report.skippedProtected += plan.protectedCount;
+                report.protectMatched += plan.protectMatched;
+                emit("prune", {
+                    sessionID,
+                    percent: pct,
+                    used,
+                    limit,
+                    pruned: plan.prune.length,
+                    saved: plan.savedTokens,
+                    protected: plan.protectedCount,
+                    protect_matched: plan.protectMatched,
+                    protect_patterns: protectPatterns.length,
+                    unknown: report.unknownParts,
+                    over_budget: overBudget,
+                    reused: report.reused,
+                });
+            }
+            catch (err) {
+                // Bodies stored for THIS request but never pointed at by a message are
+                // orphans: counted, and named on their own trajectory row — a payload
+                // nobody can reach is otherwise invisible until the TTL sweep.
+                // R4: only the FRESH writes of this request count.  A reused handle points
+                // at a payload an earlier request already stored, so calling it an orphan
+                // would invent garbage — and deleting nothing would be the fix anyway.
+                const freshThisRequest = Math.max(0, report.offloaded - freshBefore);
+                if (freshThisRequest > 0) {
+                    report.orphans += freshThisRequest;
+                    emit("prune_offload_failed", { sessionID, reason: "orphaned", orphan: freshThisRequest });
+                }
+                throw err;
+            }
         }
         catch (err) {
             report.threw++;