@seanhogg/builderforce-memory 2026.10.23 → 2026.10.25

package/dist/handoff/index.d.ts

@@ -14,5 +14,6 @@
 export { packHandoff } from './pack.js';
 export { handoffBudget, defaultEstimateTokens, messageTokens, tokensOf } from './budget.js';
 export { handoffLine, elisionMarker } from './note.js';
+export { VOLATILE_TAIL_TAG, volatileTail, isVolatileTail, isVolatileContent } from './volatile.js';
 export type { HandoffMessage, HandoffPackInput, HandoffPack, HandoffBudgetInput, TokenEstimator, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/handoff/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handoff/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACvD,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handoff/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACnG,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/handoff/index.js

@@ -14,4 +14,5 @@
 export { packHandoff } from './pack.js';
 export { handoffBudget, defaultEstimateTokens, messageTokens, tokensOf } from './budget.js';
 export { handoffLine, elisionMarker } from './note.js';
+export { VOLATILE_TAIL_TAG, volatileTail, isVolatileTail, isVolatileContent } from './volatile.js';
 //# sourceMappingURL=index.js.map

package/dist/handoff/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handoff/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handoff/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/handoff/pack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/handoff/pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAkB,WAAW,EAAE,gBAAgB,EAAkB,MAAM,YAAY,CAAC;AA0FhG,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CA6D/E"}
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/handoff/pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAkB,WAAW,EAAE,gBAAgB,EAAkB,MAAM,YAAY,CAAC;AAkGhG,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAoB/E"}

package/dist/handoff/pack.js

@@ -25,6 +25,7 @@
 import { defaultEstimateTokens, handoffBudget, messageTokens, tokensOf } from './budget.js';
 import { buildNote, composeNote, elisionMarker, handoffLine, noteTokens } from './note.js';
 import { segmentTranscript } from './segments.js';
+import { isVolatileTail } from './volatile.js';
 /** Length of the leading run of `system` messages. */
 function leadingSystemCount(all) {
     let n = 0;
@@ -36,13 +37,20 @@ function leadingSystemCount(all) {
 function noteRole(next) {
     return next === undefined || next.role === 'assistant' ? 'user' : 'assistant';
 }
-/** Index of the last `user` message, or -1. */
+/** Index of the last `user` message that is a real directive (never a volatile tail), or -1. */
 function latestDirectiveIndex(convo) {
     for (let i = convo.length - 1; i >= 0; i--)
-        if (convo[i].role === 'user')
+        if (convo[i].role === 'user' && !isVolatileTail(convo[i]))
             return i;
     return -1;
 }
+/** Where the trailing run of volatile tails begins (`messages.length` when there is none). */
+function trailingVolatileStart(messages) {
+    let i = messages.length;
+    while (i > 0 && isVolatileTail(messages[i - 1]))
+        i -= 1;
+    return i;
+}
 /** Convo indices the caller pinned (pinnable roles only), excluding the directive. */
 function pinnedIndices(convo, prefixLen, directiveIdx, pinned) {
     if (!pinned)
@@ -94,8 +102,27 @@ function result(messages, dropped, estimate, extra = {}) {
 export async function packHandoff(input) {
     const estimate = input.estimateTokens ?? defaultEstimateTokens;
     const budget = handoffBudget(input);
-    const all = input.messages;
     // Under budget: hand the transcript over untouched.
+    if (tokensOf(input.messages, estimate) <= budget)
+        return result(input.messages.slice(), 0, estimate);
+    // The volatile tail (`volatile.ts`) is set aside, the history packed into what is
+    // left, and the tail put back LAST — never the directive, never in the middle. When
+    // the history needs the whole budget, the tail is what goes: it is a per-turn aid,
+    // the history is the work.
+    const cut = trailingVolatileStart(input.messages);
+    const volatile = input.messages.slice(cut);
+    const volatileTokens = tokensOf(volatile, estimate);
+    if (volatile.length > 0) {
+        const history = input.messages.slice(0, cut);
+        const withTail = await packHistory({ ...input, messages: history }, budget - volatileTokens, estimate);
+        if (withTail.fits)
+            return result([...withTail.messages, ...volatile], withTail.dropped, estimate, withTail);
+        return packHistory({ ...input, messages: history }, budget, estimate);
+    }
+    return packHistory(input, budget, estimate);
+}
+async function packHistory(input, budget, estimate) {
+    const all = input.messages;
     if (tokensOf(all, estimate) <= budget)
         return result(all.slice(), 0, estimate);
     const prefixLen = leadingSystemCount(all);

package/dist/handoff/pack.js.map

@@ -1 +1 @@
-{"version":3,"file":"pack.js","sourceRoot":"","sources":["../../src/handoff/pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAgB,MAAM,eAAe,CAAC;AAShE,sDAAsD;AACtD,SAAS,kBAAkB,CAAC,GAA8B;IACxD,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAE,CAAC,IAAI,KAAK,QAAQ;QAAE,CAAC,IAAI,CAAC,CAAC;IAC3D,OAAO,CAAC,CAAC;AACX,CAAC;AAED,0FAA0F;AAC1F,SAAS,QAAQ,CAAC,IAAgC;IAChD,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;AAChF,CAAC;AAED,+CAA+C;AAC/C,SAAS,oBAAoB,CAAC,KAAgC;IAC5D,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;QAAE,IAAI,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,CAAC,CAAC;IACpF,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED,sFAAsF;AACtF,SAAS,aAAa,CACpB,KAAgC,EAChC,SAAiB,EACjB,YAAoB,EACpB,MAAkC;IAElC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACpB,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAChF,IAAI,QAAQ,IAAI,CAAC,KAAK,YAAY,IAAI,MAAM,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CACjB,KAAgC,EAChC,IAAwB,EACxB,YAAoB,EACpB,eAAuB,EACvB,IAAY;IAEZ,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IACzB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;IACxB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACrB,MAAM,gBAAgB,GAAG,YAAY,IAAI,CAAC,IAAI,YAAY,GAAG,GAAG,CAAC,KAAK,CAAC;QACvE,IAAI,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,MAAM;QACjF,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC;QACrB,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QAClB,KAAK,GAAG,CAAC,CAAC;IACZ,CAAC;IACD,gFAAgF;IAChF,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAE,CAAC,KAAK,CAAE,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACzE,MAAM,IAAI,IAAI,CAAC,KAAK,CAAE,CAAC,MAAM,CAAC;QAC9B,KAAK,IAAI,CAAC,CAAC;QACX,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IAClE,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED,SAAS,MAAM,CACb,QAA0B,EAC1B,OAAe,EACf,QAAwB,EACxB,QAAwE,EAAE;IAE1E,OAAO;QACL,QAAQ;QACR,OAAO;QACP,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,KAAK;QACrC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,KAAK;QACjC,eAAe,EAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;QAC7C,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI;KACzB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAuB;IACvD,MAAM,QAAQ,GAAG,KAAK,CAAC,cAAc,IAAI,qBAAqB,CAAC;IAC/D,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC;IAE3B,oDAAoD;IACpD,IAAI,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IAE/E,MAAM,SAAS,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACnC,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAChD,MAAM,YAAY,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,eAAe,GAAG,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,wFAAwF;IACxF,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IACvF,MAAM,UAAU,GAAG,eAAe,GAAG,SAAS,CAAC;IAE/C,gEAAgE;IAChE,IAAI,YAAY,GAAG,UAAU,GAAG,MAAM,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3F,OAAO,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACnG,CAAC;IAED,qFAAqF;IACrF,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACvF,MAAM,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,IAAI,MAAM,CAAC;IAC/D,MAAM,IAAI,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1E,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,eAAe,EAAE,IAAI,CAAC,CAAC;IACxG,MAAM,QAAQ,GAAG,SAAS,KAAK,SAAS,IAAI,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC;IACtE,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,KAAK,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzH,MAAM,IAAI,GAAG,YAAY,GAAG,IAAI,CAAC,MAAM,GAAG,SAAS,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC;QACjC,CAAC,CAAC,MAAM,SAAS,CAAC;YACd,MAAM;YACN,OAAO,EAAE,WAAW;YACpB,SAAS;YACT,IAAI,EAAE,MAAM,GAAG,IAAI;YACnB,QAAQ;YACR,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,SAAS,EAAE,KAAK,CAAC,SAAS;SAC3B,CAAC;QACJ,CAAC,CAAC,IAAI,CAAC;IAET,MAAM,KAAK,GAAqB,QAAQ,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAqB,CAAC,GAAG,MAAM,EAAE,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC;IACtF,IAAI,IAAI;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE;QACpD,UAAU,EAAE,IAAI,EAAE,UAAU,IAAI,KAAK;QACrC,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,KAAK;KAClC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"pack.js","sourceRoot":"","sources":["../../src/handoff/pack.ts"],"names":[],"mappings":"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"}

package/dist/handoff/volatile.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The per-request VOLATILE tail — everything that changes turn to turn (the run's
+ * working-memory brief, the affect block, the budget line, task state) in ONE `user`
+ * message appended AFTER the history and opened by {@link VOLATILE_TAIL_TAG}.
+ *
+ * Two readers depend on that one convention, which is why it lives here and every host
+ * builds its tail with {@link volatileTail}:
+ *
+ *   - The gateway's prompt caching places the history breakpoint BEFORE a tagged block,
+ *     so a tail that changes every turn never becomes the cached prefix. An untagged
+ *     trailing block is where the breakpoint lands — and then every turn re-bills the
+ *     whole transcript.
+ *   - {@link packHandoff} never treats a tagged block as "the latest user directive"
+ *     and keeps it LAST: an untagged one would be protected in place of the user's real
+ *     request, which could then be dropped into the summarised middle.
+ *
+ * A trailing user turn is valid after a tool-result turn on both the OpenAI and the
+ * Anthropic shape (Anthropic merges it into the tool_result user turn). It is built per
+ * request and never persisted into a transcript.
+ */
+import type { HandoffMessage } from './types.js';
+export declare const VOLATILE_TAIL_TAG = "<run-state>";
+/** True when `content` (a string or a content-part array) opens with the tag. */
+export declare function isVolatileContent(content: unknown): boolean;
+/** True for a `user` message that is a volatile tail. */
+export declare function isVolatileTail(message: Pick<HandoffMessage, 'role' | 'content'>): boolean;
+/** The ONE tail message for these sections, or null when every section is empty. */
+export declare function volatileTail(sections: readonly (string | null | undefined)[]): {
+    role: 'user';
+    content: string;
+} | null;
+//# sourceMappingURL=volatile.d.ts.map

package/dist/handoff/volatile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volatile.d.ts","sourceRoot":"","sources":["../../src/handoff/volatile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAG/C,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAO3D;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAEzF;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGvH"}

package/dist/handoff/volatile.js

@@ -0,0 +1,42 @@
+/**
+ * The per-request VOLATILE tail — everything that changes turn to turn (the run's
+ * working-memory brief, the affect block, the budget line, task state) in ONE `user`
+ * message appended AFTER the history and opened by {@link VOLATILE_TAIL_TAG}.
+ *
+ * Two readers depend on that one convention, which is why it lives here and every host
+ * builds its tail with {@link volatileTail}:
+ *
+ *   - The gateway's prompt caching places the history breakpoint BEFORE a tagged block,
+ *     so a tail that changes every turn never becomes the cached prefix. An untagged
+ *     trailing block is where the breakpoint lands — and then every turn re-bills the
+ *     whole transcript.
+ *   - {@link packHandoff} never treats a tagged block as "the latest user directive"
+ *     and keeps it LAST: an untagged one would be protected in place of the user's real
+ *     request, which could then be dropped into the summarised middle.
+ *
+ * A trailing user turn is valid after a tool-result turn on both the OpenAI and the
+ * Anthropic shape (Anthropic merges it into the tool_result user turn). It is built per
+ * request and never persisted into a transcript.
+ */
+export const VOLATILE_TAIL_TAG = '<run-state>';
+const VOLATILE_TAIL_CLOSE = '</run-state>';
+/** True when `content` (a string or a content-part array) opens with the tag. */
+export function isVolatileContent(content) {
+    if (typeof content === 'string')
+        return content.startsWith(VOLATILE_TAIL_TAG);
+    if (Array.isArray(content)) {
+        const first = content[0];
+        return typeof first?.text === 'string' && first.text.startsWith(VOLATILE_TAIL_TAG);
+    }
+    return false;
+}
+/** True for a `user` message that is a volatile tail. */
+export function isVolatileTail(message) {
+    return message.role === 'user' && isVolatileContent(message.content);
+}
+/** The ONE tail message for these sections, or null when every section is empty. */
+export function volatileTail(sections) {
+    const body = sections.map((s) => (s ?? '').trim()).filter(Boolean).join('\n\n');
+    return body ? { role: 'user', content: `${VOLATILE_TAIL_TAG}\n${body}\n${VOLATILE_TAIL_CLOSE}` } : null;
+}
+//# sourceMappingURL=volatile.js.map

package/dist/handoff/volatile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"volatile.js","sourceRoot":"","sources":["../../src/handoff/volatile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAC/C,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAE3C,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAmC,CAAC;QAC3D,OAAO,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAC,OAAiD;IAC9E,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,IAAI,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACvE,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,YAAY,CAAC,QAAgD;IAC3E,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChF,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,iBAAiB,KAAK,IAAI,KAAK,mBAAmB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1G,CAAC"}

package/dist/working/consolidate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Consolidation — what survives a run, as ONE long-term memory per code AREA.
+ *
+ * A run that spends ninety turns locating the code behind a feature leaves with that
+ * knowledge in its transcript and nowhere else, so the next run asked about the same
+ * area repeats the whole search. {@link consolidate} turns the run's working memory
+ * into a map — the files that mattered, changed first, then reads ranked by how much
+ * the run leaned on them — under a key per area (the directory most of them share).
+ * Deterministic: built from what the run actually opened, it cannot invent a path.
+ *
+ * {@link mergeConsolidated} is the WRITE-side rule a keyed store applies, so a small run
+ * ADDS to an area's map instead of overwriting the twelve files an earlier one found,
+ * and a file this run deleted leaves the map.
+ */
+import type { ConsolidateOptions, ConsolidatedMemory, WorkingMemorySnapshot } from './types.js';
+/** Key prefix every consolidated code map carries. */
+export declare const CONSOLIDATED_KEY_PREFIX = "codemap:";
+/** Fewer distinct files than this, with nothing changed, is a lookup — not a map worth keeping. */
+export declare const MIN_CONSOLIDATED_FILES = 3;
+/** The key for an area — stable across runs, so consolidations of one area meet in one memory. */
+export declare function consolidatedKey(area: string): string;
+/**
+ * The long-term memory for one finished run, or `null` when the run touched too little
+ * to be worth keeping. Files the run deleted are carried as `(deleted)` lines, which
+ * {@link mergeConsolidated} applies as removals and never stores.
+ */
+export declare function consolidate(snapshot: WorkingMemorySnapshot, opts?: ConsolidateOptions): ConsolidatedMemory | null;
+/**
+ * The content to STORE when a consolidated map lands on a key that already holds one:
+ * the new run's entries first, then the earlier map's entries it did not touch (an
+ * earlier run's `changed` is restated as `changed earlier`, so this run is not credited
+ * with edits it never made), minus every file this run deleted, capped. Any other key,
+ * or no prior, stores `next` without its `(deleted)` lines.
+ *
+ * The STORE decides whether `prior` is still live — pass it only when the stored memory
+ * has not expired or been superseded, or a retired map comes back to life.
+ */
+export declare function mergeConsolidated(key: string, prior: string | null | undefined, next: string): string;
+//# sourceMappingURL=consolidate.d.ts.map

package/dist/working/consolidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolidate.d.ts","sourceRoot":"","sources":["../../src/working/consolidate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEhG,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,aAAa,CAAC;AAClD,mGAAmG;AACnG,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAoExC,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,qBAAqB,EAAE,IAAI,GAAE,kBAAuB,GAAG,kBAAkB,GAAG,IAAI,CA6BrH;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBrG"}

package/dist/working/consolidate.js

@@ -0,0 +1,179 @@
+/**
+ * Consolidation — what survives a run, as ONE long-term memory per code AREA.
+ *
+ * A run that spends ninety turns locating the code behind a feature leaves with that
+ * knowledge in its transcript and nowhere else, so the next run asked about the same
+ * area repeats the whole search. {@link consolidate} turns the run's working memory
+ * into a map — the files that mattered, changed first, then reads ranked by how much
+ * the run leaned on them — under a key per area (the directory most of them share).
+ * Deterministic: built from what the run actually opened, it cannot invent a path.
+ *
+ * {@link mergeConsolidated} is the WRITE-side rule a keyed store applies, so a small run
+ * ADDS to an area's map instead of overwriting the twelve files an earlier one found,
+ * and a file this run deleted leaves the map.
+ */
+import { rankByCount } from './rank.js';
+/** Key prefix every consolidated code map carries. */
+export const CONSOLIDATED_KEY_PREFIX = 'codemap:';
+/** Fewer distinct files than this, with nothing changed, is a lookup — not a map worth keeping. */
+export const MIN_CONSOLIDATED_FILES = 3;
+const MAX_FILES = 12;
+const MIN_AREA_SEGMENTS = 2;
+const MAX_AREA_SEGMENTS = 4;
+const MAX_TASK_CHARS = 200;
+const MAX_KEY_CHARS = 255;
+/** Dependencies, build output and the knowledge tree itself — never "where the code is". */
+const NOISE_SEGMENTS = new Set(['node_modules', 'dist', '.next', '.turbo', 'coverage', '.git', '.builderforce']);
+const NOISE_FILES = new Set(['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb']);
+const DRIVE = /^[a-z]:\//i;
+/** MSYS / Git-Bash spelling of a drive path: `/c/code/x` ≡ `C:/code/x`. */
+const MSYS_DRIVE = /^\/([a-z])\//i;
+function canonical(raw) {
+    let p = raw.trim().replace(/\\/g, '/');
+    const msys = MSYS_DRIVE.exec(p);
+    if (msys)
+        p = `${msys[1]}:/${p.slice(3)}`;
+    // Collapse `a//b` and `a/./b`; leading `./` too.
+    p = p.replace(/\/{2,}/g, '/').replace(/(^|\/)(\.\/)+/g, '$1');
+    return p;
+}
+/**
+ * A repo-relative path, or undefined when the path is not a repo file worth mapping:
+ * outside the root (or absolute with no root to resolve it against), escaping with
+ * `..`, dependencies or build output, or a lockfile. Drive paths compare
+ * case-insensitively, as the filesystem does.
+ */
+function repoPath(raw, root) {
+    let p = canonical(raw);
+    if (p.startsWith('/') || DRIVE.test(p)) {
+        const base = root ? canonical(root).replace(/\/+$/, '') : '';
+        if (!base || base === '/')
+            return undefined;
+        const under = DRIVE.test(base) ? p.toLowerCase().startsWith(`${base.toLowerCase()}/`) : p.startsWith(`${base}/`);
+        if (!under)
+            return undefined;
+        p = p.slice(base.length + 1);
+    }
+    const segs = p.split('/');
+    if (!p || segs.includes('..'))
+        return undefined;
+    if (segs.some((s) => NOISE_SEGMENTS.has(s)) || NOISE_FILES.has(segs[segs.length - 1]))
+        return undefined;
+    return p;
+}
+function dirSegments(file) {
+    const parts = file.split('/');
+    parts.pop();
+    return parts;
+}
+/**
+ * The area a set of files belongs to: the DEEPEST directory (to a bounded depth, so
+ * keys stay stable from run to run) holding a majority of them, else the depth-2
+ * directory holding the most. Root-level files (DONE.md, package.json — touched by
+ * many unrelated runs) never decide it.
+ */
+function areaOf(files) {
+    const placed = files.map(dirSegments).filter((d) => d.length > 0);
+    if (placed.length === 0)
+        return '(root)';
+    const prefixes = (depth) => rankByCount(placed.filter((d) => d.length >= depth).map((d) => d.slice(0, depth).join('/')));
+    for (let depth = MAX_AREA_SEGMENTS; depth >= MIN_AREA_SEGMENTS; depth--) {
+        const [top] = prefixes(depth);
+        if (top && top[1] * 2 > placed.length)
+            return top[0];
+    }
+    return prefixes(MIN_AREA_SEGMENTS)[0]?.[0] ?? prefixes(1)[0][0];
+}
+/** The key for an area — stable across runs, so consolidations of one area meet in one memory. */
+export function consolidatedKey(area) {
+    return `${CONSOLIDATED_KEY_PREFIX}${area}`.slice(0, MAX_KEY_CHARS);
+}
+/**
+ * The long-term memory for one finished run, or `null` when the run touched too little
+ * to be worth keeping. Files the run deleted are carried as `(deleted)` lines, which
+ * {@link mergeConsolidated} applies as removals and never stores.
+ */
+export function consolidate(snapshot, opts = {}) {
+    const keep = (raw) => repoPath(raw, opts.root);
+    const kept = (list) => list.map(keep).filter((p) => !!p);
+    const deleted = [...new Set(kept(snapshot.deleted))];
+    const deletedSet = new Set(deleted);
+    const changed = [...new Set(kept([...snapshot.created, ...snapshot.edited]))].filter((p) => !deletedSet.has(p));
+    const changedSet = new Set(changed);
+    const reads = rankByCount(kept(snapshot.read)).filter(([p]) => !changedSet.has(p) && !deletedSet.has(p));
+    const readCounts = new Map(reads);
+    const ranked = [...changed, ...reads.map(([p]) => p)];
+    if (ranked.length === 0 && deleted.length === 0)
+        return null;
+    if (changed.length === 0 && deleted.length === 0 && ranked.length < MIN_CONSOLIDATED_FILES)
+        return null;
+    const shown = ranked.slice(0, MAX_FILES);
+    const area = areaOf(ranked.length > 0 ? ranked : deleted);
+    const at = (opts.at ?? new Date()).toISOString().slice(0, 10);
+    const asked = (snapshot.task ?? '').replace(/\s+/g, ' ').trim().slice(0, MAX_TASK_CHARS);
+    const lines = [
+        `Code map for \`${area}\` (mapped ${at}${asked ? ` by a run asked: "${asked}"` : ''}).`,
+        'Open these first instead of searching:',
+        ...shown.map((p) => {
+            if (changedSet.has(p))
+                return `- ${p} (changed)`;
+            const n = readCounts.get(p) ?? 1;
+            return `- ${p}${n > 1 ? ` (read ${n}×)` : ''}`;
+        }),
+        ...deleted.map((p) => `- ${p} (deleted)`),
+    ];
+    if (ranked.length > shown.length)
+        lines.push(`(+${ranked.length - shown.length} more file(s) touched)`);
+    return { key: consolidatedKey(area), content: lines.join('\n') };
+}
+/** `- <path> (<note>)` — the path is everything before the trailing parenthesised note. */
+const ENTRY = /^- (.+?)(?: \(([^()]*)\))?$/;
+const MORE = /^\(\+\d+ more file\(s\) touched\)$/;
+function entriesOf(content) {
+    const out = [];
+    for (const line of content.split('\n')) {
+        const m = ENTRY.exec(line);
+        if (m)
+            out.push({ path: m[1], note: m[2] });
+    }
+    return out;
+}
+function render(e) {
+    return `- ${e.path}${e.note ? ` (${e.note})` : ''}`;
+}
+/**
+ * The content to STORE when a consolidated map lands on a key that already holds one:
+ * the new run's entries first, then the earlier map's entries it did not touch (an
+ * earlier run's `changed` is restated as `changed earlier`, so this run is not credited
+ * with edits it never made), minus every file this run deleted, capped. Any other key,
+ * or no prior, stores `next` without its `(deleted)` lines.
+ *
+ * The STORE decides whether `prior` is still live — pass it only when the stored memory
+ * has not expired or been superseded, or a retired map comes back to life.
+ */
+export function mergeConsolidated(key, prior, next) {
+    if (!key.startsWith(CONSOLIDATED_KEY_PREFIX))
+        return next;
+    const nextLines = next.split('\n');
+    const header = nextLines.filter((l) => !ENTRY.test(l) && !MORE.test(l));
+    const fresh = entriesOf(next);
+    const removed = new Set(fresh.filter((e) => e.note === 'deleted').map((e) => e.path));
+    const seen = new Set(removed);
+    const merged = [];
+    for (const e of fresh) {
+        if (seen.has(e.path))
+            continue;
+        seen.add(e.path);
+        merged.push(render(e));
+    }
+    for (const e of prior?.trim() ? entriesOf(prior) : []) {
+        if (seen.has(e.path) || e.note === 'deleted')
+            continue;
+        seen.add(e.path);
+        merged.push(render(e.note === 'changed' ? { ...e, note: 'changed earlier' } : e));
+    }
+    const shown = merged.slice(0, MAX_FILES);
+    const more = merged.length - shown.length;
+    return [...header, ...shown, ...(more > 0 ? [`(+${more} more file(s) touched)`] : [])].join('\n');
+}
+//# sourceMappingURL=consolidate.js.map

package/dist/working/consolidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolidate.js","sourceRoot":"","sources":["../../src/working/consolidate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAGxC,sDAAsD;AACtD,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC;AAClD,mGAAmG;AACnG,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACxC,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAC5B,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAC5B,MAAM,cAAc,GAAG,GAAG,CAAC;AAC3B,MAAM,aAAa,GAAG,GAAG,CAAC;AAC1B,4FAA4F;AAC5F,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;AACtI,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC,CAAC,gBAAgB,EAAE,mBAAmB,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AAEpH,MAAM,KAAK,GAAG,YAAY,CAAC;AAC3B,2EAA2E;AAC3E,MAAM,UAAU,GAAG,eAAe,CAAC;AAEnC,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChC,IAAI,IAAI;QAAE,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1C,iDAAiD;IACjD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;IAC9D,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,GAAW,EAAE,IAAa;IAC1C,IAAI,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,GAAG;YAAE,OAAO,SAAS,CAAC;QAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;QACjH,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IACzG,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,KAAK,CAAC,GAAG,EAAE,CAAC;IACZ,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,SAAS,MAAM,CAAC,KAAwB;IACtC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzC,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAsB,EAAE,CACrD,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC/F,KAAK,IAAI,KAAK,GAAG,iBAAiB,EAAE,KAAK,IAAI,iBAAiB,EAAE,KAAK,EAAE,EAAE,CAAC;QACxE,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM;YAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,GAAG,uBAAuB,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,QAA+B,EAAE,OAA2B,EAAE;IACxF,MAAM,IAAI,GAAG,CAAC,GAAW,EAAsB,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,MAAM,IAAI,GAAG,CAAC,IAAuB,EAAY,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnG,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAChH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACzG,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,sBAAsB;QAAE,OAAO,IAAI,CAAC;IAExG,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1D,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;IACzF,MAAM,KAAK,GAAG;QACZ,kBAAkB,IAAI,cAAc,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,qBAAqB,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI;QACvF,wCAAwC;QACxC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACjB,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC,YAAY,CAAC;YACjD,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACjD,CAAC,CAAC;QACF,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC;KAC1C,CAAC;IACF,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,wBAAwB,CAAC,CAAC;IACxG,OAAO,EAAE,GAAG,EAAE,eAAe,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACnE,CAAC;AAED,2FAA2F;AAC3F,MAAM,KAAK,GAAG,6BAA6B,CAAC;AAC5C,MAAM,IAAI,GAAG,oCAAoC,CAAC;AAIlD,SAAS,SAAS,CAAC,OAAe;IAChC,MAAM,GAAG,GAAY,EAAE,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,MAAM,CAAC,CAAQ;IACtB,OAAO,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACtD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,KAAgC,EAAE,IAAY;IAC3F,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,uBAAuB,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACtF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,OAAO,CAAC,CAAC;IACtC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACtD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACvD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1C,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,KAAK,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,wBAAwB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpG,CAAC"}

package/dist/working/consolidationMarker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Chat consolidation markers — the durable form of a compressed conversation.
+ *
+ * A long conversation is compressed into ONE summary that becomes the new base context:
+ * everything before the marker stays visible in the transcript, but the next run's model
+ * seed starts from the marker instead of the full history. The marker is a normal
+ * assistant message (so a reader SEES the summary) tagged in its metadata.
+ *
+ * Two writers:
+ *   - MANUAL — "Consolidate" / "Fork": the summary covers everything before the marker.
+ *   - AUTO — a run's working-transcript fold (`transcript.ts`), persisted so the next run
+ *     (after a reload, on another surface) starts from the note instead of summarizing the
+ *     whole history again. A fold covers only the OLDER part of the transcript; its
+ *     `keepFromId` names the first persisted message it did NOT cover, and every message
+ *     from there on stays verbatim in the seed. Nothing is in neither.
+ */
+/** The marker's metadata. `auto` / `keepFromId` / `folded` are set only by a run's fold. */
+export interface ConsolidationMarkerMeta {
+    consolidation: true;
+    /** Written by auto-compaction, not by a person. */
+    auto?: true;
+    /** The first persisted message the note does NOT cover (kept verbatim after the marker). */
+    keepFromId?: number;
+    /** How many transcript messages the fold newly compressed. */
+    folded?: number;
+}
+/** The metadata of a manual marker. */
+export declare const CONSOLIDATION_META: ConsolidationMarkerMeta;
+/** Serialized metadata for a marker message (ready to persist). Manual when no `auto`. */
+export declare function consolidationMetadata(auto?: {
+    keepFromId?: number;
+    folded?: number;
+}): string;
+/** The marker metadata a persisted message carries, or null when it is not a marker. */
+export declare function consolidationMarkerOf(msg: {
+    metadata?: string | null;
+}): ConsolidationMarkerMeta | null;
+/** True when a persisted message is a consolidation marker (by its metadata flag). */
+export declare function isConsolidationMarker(msg: {
+    metadata?: string | null;
+}): boolean;
+/** The index of the LAST consolidation marker in a message list, or -1 if none. */
+export declare function lastConsolidationIndex(messages: ReadonlyArray<{
+    metadata?: string | null;
+}>): number;
+/**
+ * Trim a message list to the compressed context: the last marker, then what it does not
+ * cover. A manual marker covers everything before it (the list from the marker on). An
+ * auto marker covers up to its `keepFromId`: the marker, then every message from that id
+ * on (other markers dropped — an older note is superseded by the newer one). Unchanged
+ * when there is no marker; a `keepFromId` no longer in the list reads as manual.
+ */
+export declare function scopeToConsolidation<T extends {
+    id?: number;
+    metadata?: string | null;
+}>(messages: T[]): T[];
+/**
+ * Where an auto marker's verbatim part begins: given the persisted messages the run's
+ * transcript holds (`anchors`: transcript index → message id) and the index the fold now
+ * covers up to (exclusive), the id of the persisted message the next seed must keep from.
+ *
+ * Exact when a persisted message sits AT `coveredEnd` (the fold ended inside seeded
+ * history). Otherwise the nearest persisted message BEFORE it — conservative: the span
+ * between it and `coveredEnd` is then both in the note and verbatim, never in neither.
+ * Undefined when no persisted message precedes the cut (nothing to keep from).
+ */
+export declare function foldKeepFromId(anchors: ReadonlyArray<{
+    index: number;
+    id: number;
+}>, coveredEnd: number): number | undefined;
+/** The visible header prefixed onto a consolidation summary so a reader recognizes it. */
+export declare const CONSOLIDATION_MARKER_PREFIX = "\uD83D\uDCCC **Consolidated summary** \u2014 context continues from here.\n\n";
+/** Wrap a raw summary as the marker's visible content (prefix + summary). */
+export declare function consolidationMarkerContent(summary: string): string;
+//# sourceMappingURL=consolidationMarker.d.ts.map

package/dist/working/consolidationMarker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolidationMarker.d.ts","sourceRoot":"","sources":["../../src/working/consolidationMarker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,IAAI,CAAC;IACpB,mDAAmD;IACnD,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,EAAE,uBAAiD,CAAC;AAEnF,0FAA0F;AAC1F,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAS7F;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,uBAAuB,GAAG,IAAI,CAcvG;AAED,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,OAAO,CAEhF;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG,MAAM,CAKpG;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAQ5G;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM5H;AAED,0FAA0F;AAC1F,eAAO,MAAM,2BAA2B,kFAAmE,CAAC;AAE5G,6EAA6E;AAC7E,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE"}

package/dist/working/consolidationMarker.js

@@ -0,0 +1,104 @@
+/**
+ * Chat consolidation markers — the durable form of a compressed conversation.
+ *
+ * A long conversation is compressed into ONE summary that becomes the new base context:
+ * everything before the marker stays visible in the transcript, but the next run's model
+ * seed starts from the marker instead of the full history. The marker is a normal
+ * assistant message (so a reader SEES the summary) tagged in its metadata.
+ *
+ * Two writers:
+ *   - MANUAL — "Consolidate" / "Fork": the summary covers everything before the marker.
+ *   - AUTO — a run's working-transcript fold (`transcript.ts`), persisted so the next run
+ *     (after a reload, on another surface) starts from the note instead of summarizing the
+ *     whole history again. A fold covers only the OLDER part of the transcript; its
+ *     `keepFromId` names the first persisted message it did NOT cover, and every message
+ *     from there on stays verbatim in the seed. Nothing is in neither.
+ */
+/** The metadata of a manual marker. */
+export const CONSOLIDATION_META = { consolidation: true };
+/** Serialized metadata for a marker message (ready to persist). Manual when no `auto`. */
+export function consolidationMetadata(auto) {
+    if (!auto)
+        return JSON.stringify(CONSOLIDATION_META);
+    const meta = {
+        consolidation: true,
+        auto: true,
+        ...(auto.keepFromId !== undefined ? { keepFromId: auto.keepFromId } : {}),
+        ...(auto.folded !== undefined ? { folded: auto.folded } : {}),
+    };
+    return JSON.stringify(meta);
+}
+/** The marker metadata a persisted message carries, or null when it is not a marker. */
+export function consolidationMarkerOf(msg) {
+    if (!msg.metadata)
+        return null;
+    try {
+        const m = JSON.parse(msg.metadata);
+        if (m?.consolidation !== true)
+            return null;
+        return {
+            consolidation: true,
+            ...(m.auto === true ? { auto: true } : {}),
+            ...(typeof m.keepFromId === 'number' && Number.isFinite(m.keepFromId) ? { keepFromId: m.keepFromId } : {}),
+            ...(typeof m.folded === 'number' && Number.isFinite(m.folded) && m.folded > 0 ? { folded: m.folded } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** True when a persisted message is a consolidation marker (by its metadata flag). */
+export function isConsolidationMarker(msg) {
+    return consolidationMarkerOf(msg) !== null;
+}
+/** The index of the LAST consolidation marker in a message list, or -1 if none. */
+export function lastConsolidationIndex(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (isConsolidationMarker(messages[i]))
+            return i;
+    }
+    return -1;
+}
+/**
+ * Trim a message list to the compressed context: the last marker, then what it does not
+ * cover. A manual marker covers everything before it (the list from the marker on). An
+ * auto marker covers up to its `keepFromId`: the marker, then every message from that id
+ * on (other markers dropped — an older note is superseded by the newer one). Unchanged
+ * when there is no marker; a `keepFromId` no longer in the list reads as manual.
+ */
+export function scopeToConsolidation(messages) {
+    const idx = lastConsolidationIndex(messages);
+    if (idx < 0)
+        return messages;
+    const marker = messages[idx];
+    const keepFromId = consolidationMarkerOf(marker)?.keepFromId;
+    const from = keepFromId === undefined ? -1 : messages.findIndex((m) => m.id === keepFromId);
+    if (from < 0 || from > idx)
+        return messages.slice(idx);
+    return [marker, ...messages.slice(from).filter((m) => m !== marker && !isConsolidationMarker(m))];
+}
+/**
+ * Where an auto marker's verbatim part begins: given the persisted messages the run's
+ * transcript holds (`anchors`: transcript index → message id) and the index the fold now
+ * covers up to (exclusive), the id of the persisted message the next seed must keep from.
+ *
+ * Exact when a persisted message sits AT `coveredEnd` (the fold ended inside seeded
+ * history). Otherwise the nearest persisted message BEFORE it — conservative: the span
+ * between it and `coveredEnd` is then both in the note and verbatim, never in neither.
+ * Undefined when no persisted message precedes the cut (nothing to keep from).
+ */
+export function foldKeepFromId(anchors, coveredEnd) {
+    let best;
+    for (const a of anchors) {
+        if (a.index <= coveredEnd && (!best || a.index > best.index))
+            best = a;
+    }
+    return best?.id;
+}
+/** The visible header prefixed onto a consolidation summary so a reader recognizes it. */
+export const CONSOLIDATION_MARKER_PREFIX = '📌 **Consolidated summary** — context continues from here.\n\n';
+/** Wrap a raw summary as the marker's visible content (prefix + summary). */
+export function consolidationMarkerContent(summary) {
+    return `${CONSOLIDATION_MARKER_PREFIX}${summary.trim()}`;
+}
+//# sourceMappingURL=consolidationMarker.js.map