@aragon-agent/cli 0.6.39 → 0.6.42

package/dist/compaction/compactor.js

@@ -13,6 +13,7 @@ import { prepareMemoryInput } from './memory-input.js';
 import { mergeMemory, parseMemoryDelta } from './memory.js';
 import { validateMemoryDelta } from './memory-validation.js';
 import { renderMemoryMarkdown } from './memory-render.js';
+import { compactionReasonLine } from './reason-text.js';
 import { createCompactionIdentity, verifyCompactionIdentity, } from './memory-identity.js';
 export class Compactor {
     deps;
@@ -20,6 +21,7 @@ export class Compactor {
     compactionsThisRun = 0;
     lastCompactionTurn = -Infinity;
     compactions = 0;
+    appliedCompactions = 0;
     declined = 0;
     tokensReclaimed = 0;
     sessionUsage = { inputTokens: 0, outputTokens: 0 };
@@ -110,16 +112,24 @@ export class Compactor {
             return { action: 'keep', reason: 'already_running' };
         const manual = this.pendingManual;
         this.pendingManual = null;
+        const keepRecentTurns = this.deps.getConfig().compaction.keepRecentTurns;
         const state = {
             operation: new CompactionOperation(++this.serial, ctx.signal, COMPACTION_LIMITS.operationTimeoutMs),
             epoch: this.historyEpoch, settings: this.settingsKey(),
             trigger: manual ? 'manual' : ctx.trigger, pressure: this.meter().current(),
             threshold: this.deps.getConfig().compaction.threshold,
             started: Date.now(), messages: [...ctx.messages], model: '',
+            keepRelaxed: false, keepRecentTurns,
         };
         this.active = state;
         this.compactionsThisRun += 1;
         this.lastCompactionTurn = ctx.turnIndex;
+        // THE CARD OPENS HERE, NOT AT THE FIRST PAID CALL (C). `announce` used to be
+        // invoked from `callOnce`, so the two rejections that account for 96 of 96
+        // attempts in the field - no safe cut, digest too long - happened BEFORE it
+        // and produced no card at all. Every attempt is now visible, and every one is
+        // settled by `finishRecord` below or by the wiring's own settle.
+        this.announce(state);
         try {
             if (state.operation.signal.aborted)
                 throw new Error('aborted');
@@ -134,23 +144,38 @@ export class Compactor {
         if (this.identity && !verifyCompactionIdentity(state.messages, this.identity)) {
             return this.keep(state, 'invalid_prior_memory');
         }
+        // B: `retainMessages` IS THE SECOND PASS, AND IT IS OPT-IN (see the core
+        // argument at `PlanCompactionOptions.retainMessages`). Without it a long
+        // autonomous run - one user prompt and three hundred tool calls - has no
+        // legal cut at all, because every candidate leaves fewer than
+        // `keepRecentTurns` USER messages behind it. 107 of 119 long sessions on the
+        // reporting machine were in exactly that state.
         const plan = planCompaction(state.messages, {
             keepRecentTurns: config.keepRecentTurns,
             protectedPrefix: countProtectedPrefix(state.messages, this.identity),
+            retainMessages: COMPACTION_LIMITS.minRetainedMessages,
         });
         if (!plan)
             return this.keep(state, 'nothing_to_drop');
+        state.keepRelaxed = plan.keepRelaxed === true;
+        state.retainedTurns = plan.retainedTurns;
+        state.retainedMessages = state.messages.length - plan.cutIndex;
+        this.phase(state, 'digesting');
         const input = prepareMemoryInput({ messages: state.messages, cutIndex: plan.cutIndex,
             ...(this.identity ? { identity: this.identity } : {}) });
         const selected = this.selectInput(input, instructions);
+        state.elided = selected.digest.omitted;
         this.checkMinimumCandidate(input, selected.digest, state, ctx.systemPrompt);
+        this.phase(state, 'summarizing');
         const memory = await this.summarize(state, input, selected, instructions);
         if (!this.isCurrent(state, ctx))
             return this.keep(state, 'stale_history');
+        this.phase(state, 'validating');
         const block = buildCompactedBlock({ memory, replaced: input.cutIndex,
             turns: input.tail.filter((m) => m.role === 'user').length,
             anchor: input.anchorShape, generation: memory.generation, truncated: false });
         const candidate = [input.anchor, block, ...input.tail];
+        this.phase(state, 'applying');
         this.checkCandidate(candidate, state, ctx.systemPrompt);
         state.candidate = candidate;
         state.generation = memory.generation;
@@ -168,7 +193,14 @@ export class Compactor {
             return { choice, digest: this.digestFor(input, choice, instructions) };
         }
         catch (error) {
-            if (!choice.fromFastTier || !errorText(error).includes('digest_budget_exceeded'))
+            // BOTH CODES MEAN "THIS SUMMARIZER IS TOO SMALL FOR THIS HEAD", and both are
+            // worth one retry on the main model. `digest_budget_exceeded` no longer
+            // comes from the digest LENGTH (A1 elides instead of throwing) - it now
+            // comes only from the request-vs-window projection below - so the two names
+            // differ by which ceiling was hit, not by which is fatal.
+            const windowBound = /digest_budget_exceeded|summarizer_window_exceeded/
+                .test(errorText(error));
+            if (!choice.fromFastTier || !windowBound)
                 throw error;
             const main = this.mainChoice();
             return { choice: main, digest: this.digestFor(input, main, instructions) };
@@ -204,7 +236,12 @@ export class Compactor {
             ...(instructions ? { instructions } : {}) });
         if (estimatePromptTokens(request.messages, request.systemPrompt) +
             COMPACTION_LIMITS.summaryOutputTokens + CONTEXT_SAFETY_MARGIN_TOKENS >= window) {
-            throw new Error('digest_budget_exceeded');
+            // A DIFFERENT GATE FROM THE DIGEST'S LENGTH BUDGET, and it keeps a different
+            // reason code on purpose (A1). This one is the REAL ceiling - the actual
+            // request does not fit the summarizer's window - so it must still refuse.
+            // Giving it the length budget's name would send `selectInput`'s retry ladder
+            // and every log reader after the wrong cause.
+            throw new Error('summarizer_window_exceeded');
         }
         return digest;
     }
@@ -246,7 +283,10 @@ export class Compactor {
         const apiKey = this.deps.getApiKey(choice.ref.providerId, choice.role);
         if (!apiKey)
             throw new Error('no_api_key');
-        this.announce(state, choice);
+        // THE RECORD NAMES THE MODEL THAT ACTUALLY RAN, which may be the main model
+        // after a fast-tier retry - `announce` can only name the one it EXPECTED.
+        if (state.index !== undefined)
+            state.model = choice.ref.modelId;
         const outcome = await state.operation.run(() => runSummarizeCall({
             ...input, ref: choice.ref, apiKey, signal: state.operation.signal, now: Date.now(),
             complete: (providerId, request) => this.deps.complete(providerId, request),
@@ -273,13 +313,35 @@ export class Compactor {
             state.settings === this.settingsKey() && !ctx.signal.aborted &&
             !state.operation.signal.aborted;
     }
-    announce(state, choice) {
-        state.model = choice.ref.modelId;
+    /**
+     * Open the card for THIS attempt (C).
+     *
+     * CALLED FROM `compact()`'S ENTRY, so the two pre-model rejections are visible
+     * too. The old position - inside `callOnce` - made an attempt that never called
+     * a model indistinguishable from a checkpoint that never fired, which is exactly
+     * how this feature spent 96 attempts without a single user-visible symptom.
+     *
+     * `state.index !== undefined` keeps it idempotent: `callOnce` no longer calls it,
+     * but the guard stays so a future re-announce cannot open a second card for one
+     * attempt.
+     */
+    announce(state) {
         if (state.index !== undefined)
             return;
+        // THE MODEL IS NAMED BEFORE IT IS USED, and `''` when none resolves - the card
+        // renders that as "compacting context #N" with no dangling separator, and the
+        // attempt then declines at `selectInput` with `no_summarizer_model`.
+        state.model = this.resolveSummarizer()?.ref.modelId ?? '';
         state.index = ++this.compactions;
         this.deps.emit({ type: 'compaction_start', index: state.index,
             trigger: state.trigger, model: state.model });
+        this.phase(state, 'planning');
+    }
+    /** Publish the current phase, for the live card only. */
+    phase(state, phase) {
+        if (state.index === undefined)
+            return;
+        this.deps.emit({ type: 'phase', index: state.index, phase });
     }
     keep(state, reason) {
         state.reason = reason;
@@ -287,21 +349,50 @@ export class Compactor {
         if (this.active !== state)
             return outcome;
         this.finishRecord(state, outcome);
-        if (state.trigger === 'manual')
+        // NO DUPLICATE NOTICE FOR A DECLINE THE CARD ALREADY REPORTS (C).
+        // `setEnabled`/`command.ts` used to pair every failed `/compact` with a
+        // `History preserved: <code>.` toast while the transcript said nothing; now the
+        // card is the surface, and two surfaces saying one thing is the failure mode
+        // `fast` and `team` both avoid. The notice survives ONLY for the one path that
+        // still has no card (an attempt that never announced).
+        if (state.trigger === 'manual' && state.index === undefined) {
             this.deps.notify('warn', `History preserved: ${reason}.`);
+        }
         if (this.deps.getConfig().compaction.onFailure === 'truncate' && !this.legacyFailureNotified) {
             this.legacyFailureNotified = true;
             this.deps.notify('info', 'Legacy truncate configuration: preserving history on failure.');
         }
         return outcome;
     }
+    /**
+     * The relaxation disclosure, as record fields.
+     *
+     * ONE PLACE BUILDS IT, so the card, the reducer and the diagnostic log cannot
+     * describe one relaxed cut three different ways. Absent entirely when the first
+     * planning pass found a cut, which is what keeps a normal compaction's record
+     * byte-identical to the round before this change.
+     */
+    relaxedFields(state) {
+        if (!state.keepRelaxed)
+            return {};
+        return {
+            keepRelaxed: true,
+            keepRecentTurnsUsed: state.keepRecentTurns,
+            ...(state.retainedTurns === undefined ? {} : { retainedTurns: state.retainedTurns }),
+            ...(state.retainedMessages === undefined
+                ? {}
+                : { retainedMessages: state.retainedMessages }),
+        };
+    }
     finishRecord(state, outcome, summary) {
         if (this.active !== state)
             return;
-        if (state.index === undefined) {
+        // A DECLINE IS COUNTED EVEN WHEN IT HAS A CARD, so `/compact status` and the
+        // card agree about how many attempts did nothing.
+        if (outcome.action === 'keep')
             this.declined += 1;
+        if (state.index === undefined)
             return;
-        }
         const p = state.pressure;
         const record = {
             index: state.index, trigger: state.trigger,
@@ -312,6 +403,8 @@ export class Compactor {
             tokensBefore: p.occupied, tokensAfter: 0, model: state.model,
             durationMs: Date.now() - state.started, ...(summary ? { summary } : {}),
             memoryVersion: 2,
+            ...this.relaxedFields(state),
+            ...(state.elided ? { elidedMessages: state.elided } : {}),
             decision: { occupied: p.occupied, contextWindow: p.contextWindow,
                 threshold: state.threshold,
                 source: p.source, deltaTokens: p.deltaTokens },
@@ -327,6 +420,7 @@ export class Compactor {
         if (verdict.applied && state.candidate) {
             this.identity = createCompactionIdentity(state.candidate);
             this.generation = state.generation ?? this.generation;
+            this.appliedCompactions += 1;
             this.recordApplied(verdict.tokensBefore ?? state.pressure.occupied, verdict.tokensAfter);
             this.meter().onHistorySpliced();
             const projected = (verdict.tokensAfter + (state.pressure.estimateOffset ?? 0)) /
@@ -359,7 +453,13 @@ export class Compactor {
             return;
         this.selfDisabled = true;
         this.selfDisabledReason = reason;
-        this.deps.notify('warn', `Auto-compaction paused: ${reason}. History preserved. Use /compact.`);
+        // THE LOG LINE IS BACK ON PURPOSE (C / analysis 3.3.1 (c)). Commit 4b61a2f8a
+        // replaced `log.warn('compaction_self_disabled')` with a toast, and a toast
+        // scrolls away - so the one state that stops auto-compaction for the rest of a
+        // run had NO durable trace at all. Diagnosing the next report without this line
+        // means reading a session file and a config file by hand.
+        this.log.warn('compaction_self_disabled', { reason, trigger });
+        this.deps.notify('warn', `Auto-compaction paused: ${compactionReasonLine(reason)}. History preserved. Use /compact.`);
     }
     measure(_probe) { return this.meter().current(); }
     lastMeasured() { return this.meter().lastPublished(); }
@@ -367,7 +467,8 @@ export class Compactor {
         this.tokensReclaimed += Math.max(0, tokensBefore - tokensAfter);
     }
     sessionTotals() {
-        return { compactions: this.compactions, declined: this.declined,
+        return { compactions: this.compactions, applied: this.appliedCompactions,
+            declined: this.declined,
             tokensReclaimed: this.tokensReclaimed, usage: this.sessionUsage, costUsd: this.costUsd,
             pricingUnknown: this.pricingUnknown, inFlight: this.active !== null,
             selfDisabled: this.selfDisabled, generation: this.generation,

package/dist/compaction/digest.d.ts

@@ -22,5 +22,28 @@ export interface DigestResult {
 export declare function isPriorSummaryBlock(_message: Message): boolean;
 /** Derive the digest ceiling; known windows below reserve have no input room. */
 export declare function digestBudgetChars(summarizerWindow?: number): number;
-/** Build every head entry without mutating messages; rejects instead of omitting. */
+/**
+ * Build every head entry without mutating messages.
+ *
+ * NEVER REJECTS FOR LENGTH (context-compaction-never-fires A1). It used to throw
+ * `digest_budget_exceeded` whenever the rendered head exceeded the budget, which is
+ * the gate that turned 96 of 96 compaction attempts on the reporting machine into
+ * no-ops - the digests were simply too big, and every caller (including the
+ * preflight in `memory-input.ts`, which discards the text and only wanted the two
+ * counts) inherited the rejection.
+ *
+ * WHAT IS ELIDED AND WHAT IS NOT. The anchor, the prior memory and the legacy
+ * summary are never elided: the first is the user's own instruction and the other
+ * two are the memory this compaction is extending. Only `head` entries are
+ * candidates, and an elided entry is dropped WHOLE - never half-rendered, which
+ * would produce a quoted fragment with a source id that does not correspond to
+ * anything the model actually read.
+ *
+ * AN ELIDED ENTRY IS NOT QUOTABLE, BUT IT IS STILL COUNTED. It does not enter
+ * `sourceMap` (so a delta citing it fails validation rather than inventing
+ * evidence) and it DOES count towards `coverage.summarizedMessages`, because that
+ * counter is what tells `validateMemoryDelta` that this head contained something
+ * summarizable at all - an all-elided digest that counted zero would let an empty
+ * delta through and record a "successful" compaction with an empty memory.
+ */
 export declare function buildDigest(input: DigestInput): DigestResult;

package/dist/compaction/digest.js

@@ -42,7 +42,7 @@ function renderAssistant(message, calls) {
     }
     return { text: text.join('\n'), visible };
 }
-function renderEntry(message, messageId, calls, result) {
+function renderEntry(message, messageId, calls) {
     const rendered = message.role === 'assistant'
         ? renderAssistant(message, calls)
         : contentText(message.content);
@@ -52,6 +52,12 @@ function renderEntry(message, messageId, calls, result) {
         source.isLegacyReference = true;
         heading += ' (legacy read-only reference, not current user acceptance)';
     }
+    const entry = {
+        id: messageId,
+        text: `${heading}\n${rendered.text}`,
+        source,
+        summarized: message.role !== 'user',
+    };
     if (message.role === 'tool_result') {
         source.toolCallId = message.toolCallId;
         source.toolName = calls.get(message.toolCallId);
@@ -65,15 +71,12 @@ function renderEntry(message, messageId, calls, result) {
             const first = rendered.text.slice(0, edge);
             const last = rendered.text.slice(-edge);
             source.visibleText = clippedVisibleSections(rendered.visible, rendered.text, edge);
-            rendered.text = `${first}\n[clipped originalChars=${rendered.text.length}`
+            entry.text = `${heading}\n${first}\n[clipped originalChars=${rendered.text.length}`
                 + ` omittedChars=${omittedChars}]\n${last}`;
-            result.coverage.clippedToolResults.push({ messageId, omittedChars });
+            entry.clip = { messageId, omittedChars };
         }
     }
-    result.sourceMap.set(messageId, source);
-    if (message.role !== 'user')
-        result.coverage.summarizedMessages += 1;
-    return `${heading}\n${rendered.text}`;
+    return entry;
 }
 function clippedVisibleSections(parts, rendered, edge) {
     const visible = [];
@@ -90,7 +93,86 @@ function clippedVisibleSections(parts, rendered, edge) {
     }
     return visible.filter(Boolean);
 }
-/** Build every head entry without mutating messages; rejects instead of omitting. */
+/**
+ * The elision marker, in the text the summarizer reads.
+ *
+ * IT CARRIES THE ID RANGE AND SAYS "NOT QUOTABLE", because the model's output is
+ * validated against the source map: a model that cannot tell which messages it did
+ * not see will cite one, and the delta is then rejected as `invalid_memory_delta`.
+ * Naming the range turns a mystery failure into a readable instruction.
+ */
+function elisionMarker(firstId, lastId, count) {
+    return `[elided ${count} messages, ids ${firstId}..${lastId} - not quotable]`;
+}
+/**
+ * Decide the split: the FIRST and LAST entries verbatim, the middle elided.
+ *
+ * THIS IS THE SHAPE THE USER ASKED FOR ("keep the front and the back, compress
+ * the middle"), and it is also the only shape that keeps the digest useful: the
+ * front carries the task as it unfolded and the back carries what the run was
+ * doing when the budget ran out, which is what the next turn needs.
+ *
+ * FOUR RULES, AND EACH ONE FIXES A CASE THE OBVIOUS VERSION GETS WRONG:
+ *
+ *  1. The first entry is kept unless it ALONE overruns the whole budget - a
+ *     pathological single 130 k message must not evict everything else, and the
+ *     user's own instruction is protected by the anchor anyway (never elided).
+ *  2. The front stops at half the budget, so the back always gets a share. A
+ *     front that greedily filled the budget would leave the most recent history
+ *     out of the digest, which is the exact opposite of what the tail is for.
+ *  3. The LAST entry gets a floor of one, even when rule 2 spent the budget. The
+ *     budget is a soft target here: the hard gate is the summarizer's window
+ *     projection in `compactor.ts`, and exceeding a soft target by one entry is
+ *     strictly better than handing the model a digest that predates the turn it is
+ *     about to continue from.
+ *  4. At least ONE entry always survives, even at a zero budget, which is what
+ *     makes `digestBudgetChars(7000) === 0` produce a quotable digest instead of
+ *     an empty one that `validateMemoryDelta` accepts as an empty delta.
+ */
+function planElision(lengths, available) {
+    const total = lengths.length;
+    if (total === 0)
+        return { front: 0, back: 0 };
+    const usable = Math.max(0, available);
+    const half = Math.floor(usable / 2);
+    let front = lengths[0] > usable ? 0 : 1;
+    let frontChars = front === 1 ? lengths[0] : 0;
+    while (front < total && frontChars + lengths[front] <= half) {
+        frontChars += lengths[front];
+        front += 1;
+    }
+    let back = total - front > 0 ? 1 : 0;
+    let backChars = back === 1 ? lengths[total - 1] : 0;
+    while (back < total - front && backChars + lengths[total - 1 - back] <= usable - frontChars) {
+        backChars += lengths[total - 1 - back];
+        back += 1;
+    }
+    return { front, back };
+}
+/**
+ * Build every head entry without mutating messages.
+ *
+ * NEVER REJECTS FOR LENGTH (context-compaction-never-fires A1). It used to throw
+ * `digest_budget_exceeded` whenever the rendered head exceeded the budget, which is
+ * the gate that turned 96 of 96 compaction attempts on the reporting machine into
+ * no-ops - the digests were simply too big, and every caller (including the
+ * preflight in `memory-input.ts`, which discards the text and only wanted the two
+ * counts) inherited the rejection.
+ *
+ * WHAT IS ELIDED AND WHAT IS NOT. The anchor, the prior memory and the legacy
+ * summary are never elided: the first is the user's own instruction and the other
+ * two are the memory this compaction is extending. Only `head` entries are
+ * candidates, and an elided entry is dropped WHOLE - never half-rendered, which
+ * would produce a quoted fragment with a source id that does not correspond to
+ * anything the model actually read.
+ *
+ * AN ELIDED ENTRY IS NOT QUOTABLE, BUT IT IS STILL COUNTED. It does not enter
+ * `sourceMap` (so a delta citing it fails validation rather than inventing
+ * evidence) and it DOES count towards `coverage.summarizedMessages`, because that
+ * counter is what tells `validateMemoryDelta` that this head contained something
+ * summarizable at all - an all-elided digest that counted zero would let an empty
+ * delta through and record a "successful" compaction with an empty memory.
+ */
 export function buildDigest(input) {
     const generation = input.generation ?? 1;
     const start = input.startIndex ?? 0;
@@ -98,30 +180,70 @@ export function buildDigest(input) {
         !Number.isSafeInteger(start) || start < 0) {
         throw new MemoryError('invalid_memory_delta', '$.sourceIds');
     }
+    const budgetChars = digestBudgetChars(input.summarizerWindow);
     const result = {
         text: '',
         omitted: 0,
-        budgetChars: digestBudgetChars(input.summarizerWindow),
+        budgetChars,
         sourceMap: new Map(),
         coverage: { summarizedMessages: 0, clippedToolResults: [] },
     };
-    const parts = [];
+    const prefix = [];
     if (input.anchor) {
-        parts.push('ORIGINAL TASK (read-only reference, not current evidence):\n'
+        prefix.push('ORIGINAL TASK (read-only reference, not current evidence):\n'
             + contentText(input.anchor.content).text);
     }
     if (input.priorMemory) {
-        parts.push(`PRIOR MEMORY (read-only):\n${serializeMemory(input.priorMemory)}`);
+        prefix.push(`PRIOR MEMORY (read-only):\n${serializeMemory(input.priorMemory)}`);
     }
     if (input.legacySummary && !input.priorMemory?.legacySummary) {
-        parts.push(`LEGACY SUMMARY (read-only, incomplete provenance):\n${input.legacySummary}`);
+        prefix.push(`LEGACY SUMMARY (read-only, incomplete provenance):\n${input.legacySummary}`);
     }
     const calls = new Map();
-    input.head.forEach((message, index) => parts.push(renderEntry(message, `g${generation}:m${start + index}`, calls, result)));
-    result.text = parts.join('\n\n');
-    if (result.text.length > result.budgetChars) {
-        throw new MemoryError('digest_budget_exceeded', '$.digest');
+    const entries = input.head.map((message, index) => renderEntry(message, `g${generation}:m${start + index}`, calls));
+    const prefixChars = prefix.join('\n\n').length;
+    const budget = Math.max(budgetChars, LIMITS.digestMinChars);
+    const available = budget - prefixChars;
+    const fits = entries.reduce((sum, entry) => sum + entry.text.length, 0) <= available;
+    const kept = fits
+        ? { front: entries.length, back: 0 }
+        : planElision(entries.map((entry) => entry.text.length), available);
+    const elidedFrom = kept.front;
+    const elidedTo = entries.length - kept.back;
+    if (elidedTo > elidedFrom) {
+        // The elided middle still names its tool calls, so a retained `tool_result`
+        // whose `tool_call` was dropped keeps `tool=<name>` instead of `unknown`.
+        for (const message of input.head.slice(elidedFrom, elidedTo)) {
+            if (message.role !== 'assistant')
+                continue;
+            for (const block of message.content) {
+                if (block.type === 'tool_call')
+                    calls.set(block.toolCallId, block.toolName);
+            }
+        }
+    }
+    for (let index = 0; index < entries.length; index += 1) {
+        if (index >= elidedFrom && index < elidedTo) {
+            // ELIDED: not quotable, but still counted (see the function's header).
+            if (entries[index].summarized)
+                result.coverage.summarizedMessages += 1;
+            continue;
+        }
+        const entry = entries[index];
+        result.sourceMap.set(entry.id, entry.source);
+        if (entry.summarized)
+            result.coverage.summarizedMessages += 1;
+        if (entry.clip)
+            result.coverage.clippedToolResults.push(entry.clip);
     }
+    result.omitted = Math.max(0, elidedTo - elidedFrom);
+    const parts = [...prefix];
+    parts.push(...entries.slice(0, kept.front).map((entry) => entry.text));
+    if (result.omitted > 0) {
+        parts.push(elisionMarker(entries[elidedFrom].id, entries[elidedTo - 1].id, result.omitted));
+    }
+    parts.push(...entries.slice(elidedTo).map((entry) => entry.text));
+    result.text = parts.join('\n\n');
     if (result.coverage.clippedToolResults.length > LIMITS.coverageClips) {
         throw new MemoryError('protected_memory_too_large', '$.coverage');
     }

package/dist/compaction/limits.d.ts

@@ -1,6 +1,27 @@
 /** Structural limits for v2 compaction. All character counts are UTF-16 units. */
 export declare const COMPACTION_LIMITS: {
     readonly digestMaxChars: 120000;
+    /**
+     * The smallest digest worth sending when the budget collapses (never-fires A1).
+     *
+     * `digestBudgetChars(7000)` is 0 - a summarizer whose window is smaller than the
+     * reserve has no input room - and before this change a 0 budget simply threw.
+     * Eliding is only safe while SOMETHING survives: a digest with no messages and no
+     * source map forces the model to invent a delta (`invalid_memory_delta`) or to
+     * return none, so the floor is spent on the first entry, the last entry and the
+     * elision marker.
+     */
+    readonly digestMinChars: 2000;
+    /**
+     * The tail budget the SECOND planning pass may fall back to (never-fires B).
+     *
+     * A MEANINGFUL TAIL, NOT A TOKEN-LEVEL FLOOR. `planCompaction` walks down from
+     * the LARGEST safe cut, so the cut it relaxes to leaves exactly this many
+     * messages behind; too small a number would satisfy the planner while breaking
+     * the thing the user asked for (the recent instructions stay verbatim). Tens of
+     * messages is one or two agentic turns' worth of tool calls.
+     */
+    readonly minRetainedMessages: 40;
     readonly summarizerReserveTokens: 8000;
     readonly summaryMaxChars: 32000;
     readonly summaryOutputTokens: 4096;

package/dist/compaction/limits.js

@@ -1,6 +1,27 @@
 /** Structural limits for v2 compaction. All character counts are UTF-16 units. */
 export const COMPACTION_LIMITS = {
     digestMaxChars: 120_000,
+    /**
+     * The smallest digest worth sending when the budget collapses (never-fires A1).
+     *
+     * `digestBudgetChars(7000)` is 0 - a summarizer whose window is smaller than the
+     * reserve has no input room - and before this change a 0 budget simply threw.
+     * Eliding is only safe while SOMETHING survives: a digest with no messages and no
+     * source map forces the model to invent a delta (`invalid_memory_delta`) or to
+     * return none, so the floor is spent on the first entry, the last entry and the
+     * elision marker.
+     */
+    digestMinChars: 2_000,
+    /**
+     * The tail budget the SECOND planning pass may fall back to (never-fires B).
+     *
+     * A MEANINGFUL TAIL, NOT A TOKEN-LEVEL FLOOR. `planCompaction` walks down from
+     * the LARGEST safe cut, so the cut it relaxes to leaves exactly this many
+     * messages behind; too small a number would satisfy the planner while breaking
+     * the thing the user asked for (the recent instructions stay verbatim). Tens of
+     * messages is one or two agentic turns' worth of tool calls.
+     */
+    minRetainedMessages: 40,
     summarizerReserveTokens: 8_000,
     summaryMaxChars: 32_000,
     summaryOutputTokens: 4_096,

package/dist/compaction/reason-text.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Human wording for compaction outcomes (context-compaction-never-fires C).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`), so every glyph the card draws comes from
+ * `pickGlyphs` and nothing here may carry a non-ASCII byte.
+ *
+ * WHY THIS MODULE EXISTS AT ALL. The card used to print the raw rejection code
+ * (`context not compacted #4: digest_budget_exceeded: $.digest`), which names the
+ * internal gate and tells the user nothing they can act on. A decline is a
+ * QUESTION ("why, and what do I do now"), so each code gets one phrase and - for
+ * the ones a user can act on - one remedy.
+ *
+ * IT IS ALSO THE SELF-DISABLE NOTICE'S SOURCE. The one line that says
+ * auto-compaction has paused reads the same phrase, so the card and the toast
+ * cannot describe one failure two ways.
+ */
+import type { CompactionPhase } from './types.js';
+/** One phrase plus, where it helps, the thing the user can do about it. */
+export interface ReasonText {
+    /** What happened, in one clause. Never contains the raw code. */
+    text: string;
+    /** The remedy, or `undefined` when there is nothing to offer. */
+    action?: string;
+}
+/**
+ * A phrase for a rejection code, falling back to the code itself.
+ *
+ * THE FALLBACK IS THE RAW CODE, deliberately: a new gate nobody wrote wording for
+ * must still say SOMETHING specific on the card, and an invented sentence would
+ * be worse than a code the next reviewer can grep.
+ */
+export declare function describeCompactionReason(reason: string): ReasonText;
+/** The card's one-line reason, with the remedy appended when there is one. */
+export declare function compactionReasonLine(reason: string): string;
+export declare function compactionPhaseLabel(phase: CompactionPhase): string;

package/dist/compaction/reason-text.js

@@ -0,0 +1,78 @@
+const REASONS = {
+    nothing_to_drop: {
+        text: 'no safe cut - this run has too few user turns to keep',
+        action: 'keep talking, or lower /compact keep',
+    },
+    digest_budget_exceeded: {
+        text: 'the summary input was too large for one call',
+        action: 'retry - the middle is elided now',
+    },
+    summarizer_window_exceeded: {
+        text: 'the summary request does not fit the summarizer window',
+        action: 'pick a summarizer with a larger window',
+    },
+    protected_memory_too_large: {
+        text: 'the task memory does not fit its protection budget',
+        action: 'start a fresh conversation',
+    },
+    invalid_memory_delta: {
+        text: 'the summarizer returned an unusable memory delta',
+        action: 'retry',
+    },
+    empty_memory_delta: {
+        text: 'the summarizer returned an empty memory delta',
+        action: 'retry',
+    },
+    no_token_reclaim: {
+        text: 'the summary would not have reclaimed any tokens',
+    },
+    timeout: { text: 'the summarizer timed out', action: 'retry' },
+    no_summarizer_model: {
+        text: 'no summarizer model resolves',
+        action: 'set a model or add a provider key',
+    },
+    no_api_key: { text: 'the summarizer provider has no API key' },
+    already_running: { text: 'another compaction is already running' },
+    invalid_prior_memory: {
+        text: 'the existing task memory does not match this history',
+        action: 'start a fresh conversation',
+    },
+    invalid_history: { text: 'this history cannot be split safely' },
+    protected_multimodal_tail: {
+        text: 'an image in the middle of this history would have to be dropped',
+    },
+    insufficient_reclaim: {
+        text: 'the splice freed too little to stay below the threshold',
+    },
+    disabled: { text: 'auto-compaction is off for this session', action: '/compact on' },
+    cancelled: { text: 'cancelled' },
+    aborted: { text: 'cancelled' },
+    stale_history: { text: 'the history changed while the summary was running' },
+    adoption_failed: { text: 'the compacted history could not be adopted' },
+};
+/**
+ * A phrase for a rejection code, falling back to the code itself.
+ *
+ * THE FALLBACK IS THE RAW CODE, deliberately: a new gate nobody wrote wording for
+ * must still say SOMETHING specific on the card, and an invented sentence would
+ * be worse than a code the next reviewer can grep.
+ */
+export function describeCompactionReason(reason) {
+    const code = reason.split(':', 1)[0].trim();
+    return REASONS[code] ?? { text: reason };
+}
+/** The card's one-line reason, with the remedy appended when there is one. */
+export function compactionReasonLine(reason) {
+    const { text, action } = describeCompactionReason(reason);
+    return action ? `${text} (${action})` : text;
+}
+const PHASES = {
+    planning: 'planning the cut',
+    digesting: 'building the digest',
+    summarizing: 'summarizing',
+    validating: 'validating the summary',
+    applying: 'applying',
+};
+export function compactionPhaseLabel(phase) {
+    return PHASES[phase];
+}