pi-fold 1.0.3 → 2.0.0

package/extensions/lib/scheduling.ts

@@ -35,7 +35,6 @@ import {
 } from "./persistence.ts";
 import { currentTurnRefKeys } from "./transcript.ts";
 import {
-  EPOCH_MAX_TOPUP_MARKS,
   ESTIMATED_BYTES_PER_TOKEN,
   MAX_WEDGE_ABSORB_TOKENS,
   ESTIMATED_PLACEHOLDER_OVERHEAD_BYTES,
@@ -65,60 +64,23 @@ import {
   resultCall,
 } from "./selection.ts";
 
-/**
- * Two-phase fold scheduling.
- *
- * A provider prefix cache is positional: editing the middle of the window
- * invalidates every byte after the edit, so per-turn folding pays a full uncached
- * prefix over and over. Nothing here changes what a fold MEANS. A fold decision
- * becomes a MARK, which moves no projection byte, and a later COMMIT applies every
- * pending mark through the same preparation and commit machinery an immediate fold
- * uses, in one rewrite.
- *
- * Every function is deterministic: transcript ordinals and positions only, never a
- * wall clock and never randomness.
- */
-
-/** The empty read, shared and frozen, so a state with no marks allocates nothing. */
 const NO_PENDING_MARKS: readonly PendingMark[] = Object.freeze([]);
 
-/**
- * The pending marks as a READ VIEW, not a copy.
- *
- * Every caller here reads: membership tests, accounting sums, and filters that build
- * a fresh array anyway. The copy belongs on the WRITE path, and `withPendingMarks`
- * already takes it, so taking a second one on every read bought nothing and cost a
- * great deal: `markSpanRefs` calls this once per mark and is itself called once per
- * mark by the accounting, eligibility, staleness, current-turn and absorption
- * readings, which made a deep clone of the whole array quadratic in the mark count
- * per pass. Profiled at 21 percent of a 120-turn session, the single largest cost in
- * the runtime, ahead of every projection and hash.
- *
- * The view is safe because the state is replaced rather than edited: no code path
- * mutates `state.pendingMarks` in place, and the readonly type is what keeps it so.
- */
 export function pendingMarks(state: Pick<ActiveContextState, "pendingMarks">): readonly PendingMark[] {
   return state.pendingMarks ?? NO_PENDING_MARKS;
 }
 
-/**
- * Property ORDER matters here: the state digest is a stable stringify, so an
- * appended key would replay as digest drift. Rebuild the tail of the record in the
- * same order `parseActiveContextState` produces.
- */
 export function withPendingMarks(
   state: ActiveContextState,
   marks: readonly PendingMark[],
 ): ActiveContextState {
   const next = marks.length ? parsePendingMarks(clone(marks) as PendingMark[]) : [];
   const head = { ...state };
-  delete head.surfacing;
   delete head.pendingMarks;
   delete head.advisory;
   delete head.prepared;
   return {
     ...head,
-    ...(state.surfacing?.length ? { surfacing: clone(state.surfacing) } : {}),
     ...(next.length ? { pendingMarks: next } : {}),
     ...(state.advisory ? { advisory: clone(state.advisory) } : {}),
     ...(state.prepared ? { prepared: clone(state.prepared) } : {}),
@@ -131,7 +93,6 @@ export interface MarkAddition {
   reason: string | null;
 }
 
-/** Idempotent by mark key, bounded, and never silently dropping the oldest mark. */
 export function addPendingMark(state: ActiveContextState, mark: PendingMark): MarkAddition {
   const marks = pendingMarks(state);
   if (marks.some((existing) => pendingMarkKey(existing) === pendingMarkKey(mark))) {
@@ -151,43 +112,15 @@ export function estimatedTokens(sizeInBytes: number): number {
   return Math.max(0, Math.ceil(sizeInBytes / ESTIMATED_BYTES_PER_TOKEN));
 }
 
-/** Transcript-position ordering used for marks; identical to the surfacing ordinal. */
 export function markOrdinal(snapshot: Pick<ActiveContextSnapshot, "mapped">): number {
   return snapshot.mapped.length;
 }
 
 export interface MarkSpanRefs {
-  /** Every evidence ref the mark's parts resolve to against the state in hand. */
   refs: EvidenceRef[];
-  /**
-   * The first part naming a fold the state does not hold, or null when the span reads
-   * in full. `pending` is the difference between a defer and a drop: a mark still
-   * standing carries the id its committed fold will have, so that fold is about to
-   * exist, and where no mark names it nothing ever will.
-   */
   unresolved: { foldId: string; pending: boolean } | null;
 }
 
-/**
- * THE ONE READING OF A MARK'S SPAN, AND IT ANSWERS RATHER THAN THROWS.
- *
- * A mark's parts name folds by id. Between the mark and the commit the state can stop
- * holding one: `reboundary` dissolves a root while consulting only `fold.parentId`, so
- * nothing there consults the pending marks, and the mark is left naming a fold that is
- * gone. `candidateSourceRefs` answers that with `Missing candidate child`, which is
- * right for a candidate being prepared and wrong for every reading that merely reports
- * on a mark: accounting, eligibility, staleness, the current-turn guard, the claimed
- * keys and wedge absorption all ran that throw out of a status call or a commit pass,
- * on state the runtime itself produced (Shane 2026-08-10).
- *
- * So the readings share this, and it is total. Raw parts resolve; a held child is
- * flattened; an unheld child is REPORTED, with the refs either side of it still
- * collected, because a partial span is the honest reading of a partly resolvable mark
- * and a guard that can see half the evidence is better than one that sees none. A
- * repeated fold on the path reads as unresolved and not pending: a corrupt forest costs
- * one mark the ordinary drop rather than hanging the caller, which is the same stop the
- * apply order's `placing` set carries.
- */
 export function markSpanRefs(state: ActiveContextState, mark: PendingMark): MarkSpanRefs {
   const byId = new Map(state.folds.map((fold) => [fold.id, fold] as const));
   const marks = pendingMarks(state);
@@ -230,11 +163,6 @@ export function markSpanRefs(state: ActiveContextState, mark: PendingMark): Mark
   return { refs, unresolved };
 }
 
-/**
- * Estimated bytes a mark would remove from the projection. Fold marks use a
- * placeholder estimate rather than a trial fold: the number is presentational, so
- * paying a full preparation per mark on every status call is not worth exactness.
- */
 export function markFreedBytes(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -257,14 +185,6 @@ export function markFreedBytes(
   return Math.max(0, bytes(source) - placeholder);
 }
 
-/**
- * Whether a pending mark covers any evidence the current excursion just gathered.
- *
- * Read off whatever the span resolves to. A mark naming an unheld fold still answers
- * here, on the parts that DO resolve, so a span holding both fresh raw evidence and a
- * child that has not landed is guarded on the fresh evidence instead of throwing the
- * whole commit.
- */
 export function markTouchesCurrentTurn(
   state: ActiveContextState,
   mark: PendingMark,
@@ -274,24 +194,6 @@ export function markTouchesCurrentTurn(
   return markSpanRefs(state, mark).refs.some((ref) => currentTurn.has(objectRefKey(ref)));
 }
 
-/**
- * The real staleness of a mark: the earliest window index its span covers, in branch
- * order.
- *
- * A mark's `ordinal` is the transcript position at MARK time, so across epochs it
- * carries when the DECISION was made and nothing about the age of what the decision
- * covers, and inside one epoch every mark shares one value. Ordering a release by it
- * therefore fell through to comparing mark ids, which are content hashes. Measured on the
- * sealed rep-3 state 2026-08-10: the bounded release held back the marks covering window
- * indices 101 and 111 and surrendered the one covering 117, the newest material on the
- * table, so the two marks the guard kept were not the two it exists to keep.
- *
- * A span that no longer maps sorts past the newest entry: there is no staleness to read
- * on material that has left the branch, and releasing such a mark frees no window byte.
- * A span that does not resolve in full sorts there too, for the same reason and by the
- * same number: while a named fold is missing there is no start to read, and the apply
- * order places such a mark off its naming rather than off this reading.
- */
 export function markSpanStart(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -308,71 +210,48 @@ export function markSpanStart(
   return indices.length ? Math.min(...indices) : snapshot.mapped.length;
 }
 
-/**
- * How many of the newest guarded marks the pressure waiver still protects. The agent's
- * MOST RECENT reads are the ones an in-flight excursion is about to work from, so they
- * are the last thing surrendered; everything older is fair game once the window is the
- * bigger risk.
- */
 export const GUARD_WAIVER_PROTECTED_MARKS = 2;
 
-/**
- * How many marks the guard must be holding before the pressure waiver releases any.
- * Without a floor the waiver degrades into exactly the per-pass folding epoch
- * scheduling exists to prevent: the batch drains, one new mark is guarded on the next
- * pass, and releasing that one mark buys a whole prefix invalidation. Below the fence
- * the waiver only ever releases a BATCH. The fence itself ignores this floor.
- */
 export const GUARD_WAIVER_MINIMUM_MARKS = 4;
 
-/**
- * Survivability outranks the guard.
- *
- * The current-turn guard is correct while there is room to wait, and fatal once there
- * is not: a workload that never emits a terminal assistant message has ONE turn, so
- * the boundary never advances and every mark is guarded forever. Measured 2026-08-06
- * (rep 11): 58 assistant messages, all stopReason "toolUse", ZERO terminal ones, so
- * the automatic commit applied nothing all run; the only marks that ever landed came
- * from the agent's own two explicit commits. The window reached 359,625 tokens and the
- * next request went out at ~458k estimated and was rejected by the provider.
- *
- * So: the guard holds in full while the commit has other work. It is waived only when
- * it would STARVE the commit -- no other mark could be applied -- and pressure has
- * reached the backstop, and then only for the OLDEST guarded marks. At the hard fence
- * every guarded mark is waived, because the only useful action left is the fold that
- * keeps the request transmissible.
- */
 export function guardWaiverCount(input: {
   snapshot: ActiveContextSnapshot;
   ratio: number | null;
   guardedMarks: number;
-  /** Marks this commit can apply WITHOUT the waiver. While any exist, the guard holds. */
   otherApplicableMarks: number;
+  /**
+   * THE BOUNDARY IS ITS OWN SIGNAL, and a better one than the occupancy anchor.
+   *
+   * The anchor exists to answer "is this session in enough trouble to spend the open
+   * turn's own evidence": a proxy, because nothing else was asking. At a compaction
+   * boundary Pi has already answered it. Cancelling the compaction and then applying
+   * nothing hands Pi's own threshold a byte-identical projection, which is worse than
+   * letting it compact, because compaction would at least have shed something.
+   *
+   * Measured on the sol-20260813 smoke: the boundary fired, cancelled the compaction and
+   * retained all seven marks at 0.20 occupancy, freeing nothing. The full run reaches the
+   * anchor 12,576 tokens past its own trigger, so it self-corrects there and this is
+   * about what happens in between; a smoke, or any session whose budget it never
+   * approaches, never corrects at all.
+   *
+   * Everything else about the waiver is unchanged, and deliberately: the newest marks
+   * still stay raw, a small guarded set still holds whole, and other applicable work
+   * still takes precedence over spending the open turn.
+   */
+  boundary?: boolean;
 }): number {
-  const { snapshot, ratio, guardedMarks, otherApplicableMarks } = input;
+  const { snapshot, ratio, guardedMarks, otherApplicableMarks, boundary } = input;
   if (guardedMarks <= 0 || typeof ratio !== "number" || !Number.isFinite(ratio)) return 0;
   if (ratio >= hardFenceRatio(snapshot)) return guardedMarks;
   const occupancy = budgetOccupancy(snapshot, ratio);
-  if (occupancy === null || occupancy < snapshot.policy.refoldRatio || otherApplicableMarks > 0) return 0;
+  if (occupancy === null || otherApplicableMarks > 0) return 0;
+  if (occupancy < snapshot.policy.refoldRatio && !boundary) return 0;
   if (guardedMarks < GUARD_WAIVER_MINIMUM_MARKS) return 0;
   return Math.max(1, guardedMarks - GUARD_WAIVER_PROTECTED_MARKS);
 }
 
 export type MarkEligibility = "eligible" | "protected" | "unfulfillable";
 
-/**
- * Whether a pending mark can be applied right now.
- *
- * "protected" is a WAITING state, not a failure: the span is fresh or the agent
- * protected it, and both conditions expire. "unfulfillable" is terminal: the evidence
- * or the fold the mark names has left the branch, so no later commit can honour it.
- * Collapsing the two is what made a refusal look like a drop.
- *
- * A mark naming a fold the state does not hold is judged by the same two words, and
- * the classification is the whole answer: a fold another pending mark is about to mint
- * is a span still WAITING to be readable, and a fold nothing will mint has left the
- * branch exactly as lost evidence has. No third word (Shane 2026-08-10).
- */
 export function markEligibility(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -403,25 +282,15 @@ export interface MarkAccounting {
   freedTokens: number;
   freedBudgetShare: number;
   rewriteTokens: number;
-  /** Marks a commit could apply right now. */
   eligibleMarks: number;
-  /** Marks whose span is still fresh or protected, waiting rather than lost. */
   retainedMarks: number;
   eligibleFreedBytes: number;
   eligibleFreedTokens: number;
-  /** The ROI signal: eligible marked mass as a share of the truthful window. */
   eligibleFreedBudgetShare: number;
-  /** Raw peek mass no reclamation can take: pinned reads and protected results. */
   pinnedBytes: number;
-  /** How many peek results that mass is spread over. */
   pinnedResults: number;
 }
 
-/**
- * What a commit of the current marks would cost and free. `rewriteTokens` is the
- * prefix a commit invalidates: everything from the earliest marked message to the
- * end of the window, which is exactly what a positional cache must re-send.
- */
 export function markAccounting(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -474,22 +343,6 @@ export function markAccounting(
   };
 }
 
-/**
- * THE commit trigger. There is exactly one.
- *
- * Occupancy of the serving budget reaches maxTarget and a commit fires. Nothing else
- * fires one automatically: the user command and the fence/recovery lane are the only
- * other paths into a commit, and both are authority rather than economics.
- *
- * Two arms used to sit here. The eligible-share arm asked whether accumulated marks
- * were worth a rewrite and fired 164 commits from ordinal 17 in rep 15, each a fresh
- * cache rebuild bought with marks that had not yet earned one; worse, it could fire
- * BELOW maxTarget, which is the quiet-runtime law it was sitting underneath. The
- * pressure arm read a window ratio against the refold rung, which after
- * re-denomination is simply a second line above this one. Both are gone. Marking is
- * doorless below the commit line and costs nothing, so what a pass accumulates is never a
- * reason to commit; crossing the band top is.
- */
 export function epochCommitDue(snapshot: ActiveContextSnapshot, ratio: number | null): boolean {
   const occupancy = budgetOccupancy(snapshot, ratio);
   return occupancy !== null && occupancy >= snapshot.thresholds.maxTarget;
@@ -505,8 +358,6 @@ export function foldMarkFor(input: {
   const { candidate } = input;
   return {
     mark: "fold",
-    // The same identity the committed fold will get, so a repeated decision is
-    // inert rather than a second fold of the same span.
     id: foldIdFor(candidate.kind, candidate.parts),
     kind: candidate.kind,
     parts: clone(candidate.parts),
@@ -517,25 +368,18 @@ export function foldMarkFor(input: {
   };
 }
 
-/** The deterministic brief a ladder decision would have folded with. */
 export function ladderBrief(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
   candidate: FoldCandidate,
 ): string {
   if (candidate.kind === "tool-result") return automaticToolBrief(snapshot, candidate);
-  if (candidate.kind === "consolidation") return deterministicConsolidationBrief(candidate, state);
+  if (candidate.kind === "consolidation") {
+    return deterministicConsolidationBrief(candidate, state, snapshot.toolName, snapshot);
+  }
   return deterministicChapterCandidateBrief(snapshot, candidate);
 }
 
-/**
- * The brief and provenance an automatic mark carries.
- *
- * A warmed chapter brief the runtime already paid a model call for is REUSED when the
- * prepared fold is exactly this candidate. Under epoch scheduling every automatic fold
- * arrives through a mark, so a preparation whose brief the mark path ignored would be a
- * model call spent on nothing.
- */
 export function automaticMarkBrief(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -548,11 +392,6 @@ export function automaticMarkBrief(
   return { brief: ladderBrief(snapshot, state, candidate), briefProvenance: { kind: "deterministic" } };
 }
 
-/**
- * Turn one automatic rung selection into a mark. Prepared chapters are excluded on
- * purpose: that rung only fires at the hard provider fence, which is already inside
- * a commit epoch, and deferring it would strand a model-generated brief.
- */
 export function ladderSelectionMark(input: {
   snapshot: ActiveContextSnapshot;
   state: ActiveContextState;
@@ -574,24 +413,6 @@ export function ladderSelectionMark(input: {
   });
 }
 
-/**
- * PEEK COPIES ARE EPHEMERAL BY CONTRACT.
- *
- * A peek returns a fold's exact stored source, so the copy sits in the window as raw
- * mass beside that fold's own placeholder: the same bytes held twice, with the second
- * copy re-retrievable forever from the id the agent already used. So a completed peek
- * read is reclaimed at the NEXT commit rather than aging through the ladder, and the
- * window being append-only is why the reclaim can only happen at a commit boundary.
- *
- * Two survival paths, and only two. Expanding the fold it peeked means the agent asked
- * for those bytes in place, and pinning is the veto: a pin holds the copy raw through
- * every commit, exactly as it holds any other evidence, and lifting it hands the copy
- * back to the next commit. Both are read here at marking time, and a pin made AFTER the
- * mark exists still vetoes, because a protected mark waits instead of applying.
- *
- * These marks are minted at the last-call exposure as well as at the commit, so the
- * pending disposal is visible during the gated round the pin has to fit inside.
- */
 export function ephemeralPeekMarks(input: {
   snapshot: ActiveContextSnapshot;
   state: ActiveContextState;
@@ -619,7 +440,6 @@ export function ephemeralPeekMarks(input: {
       .map(({ index }) => snapshot.mapped[index].ref!);
     const peeked = peekedSourceFoldIds(snapshot, refs);
     if (!peeked) continue;
-    // The agent committed to what it peeked: leave the read in the raw window.
     if (peeked.some((id) => state.expanded.includes(id) || peekedFoldProtected(snapshot, state, id))) continue;
     if (refs.some((ref) => claimed.has(objectRefKey(ref))) ||
         refs.length > snapshot.policy.maxFoldSourceRefs ||
@@ -633,8 +453,6 @@ export function ephemeralPeekMarks(input: {
       candidate,
       brief: automaticToolBrief(snapshot, candidate),
       briefProvenance: { kind: "deterministic" },
-      // A peek is an agent-initiated read; attributing its disposal to the ladder
-      // would deflate the agent-vs-ladder mark ratio the adjudication reads.
       origin: "agent",
       ordinal: input.ordinal,
     }));
@@ -655,7 +473,6 @@ function peekedFoldProtected(
     : refsProtected(refs, state, snapshot);
 }
 
-/** Every evidence key already spoken for by a fold or a pending fold mark. */
 export function claimedRefKeys(state: ActiveContextState): Set<string> {
   const keys = new Set<string>();
   for (const fold of state.folds) {
@@ -668,35 +485,13 @@ export function claimedRefKeys(state: ActiveContextState): Set<string> {
   return keys;
 }
 
-/** What is still on the table after the marks in hand: the steering number and its parts. */
 export interface UnmarkedRemainder {
-  /** Tool results in a MEMBER batch that no fold and no pending mark owns. */
   spans: number;
   tokens: number;
-  /** Unmarked member tokens as a share of the member tool mass. The steering number. */
   share: number;
-  /** The largest few, by reclaim value, so the next batch is one read away. */
   candidates: Array<{ id: string; tokens: number }>;
 }
 
-/**
- * The unmarked remainder, as an AGGREGATE plus a bounded head.
- *
- * An exhaustive list is what the status index already is, and re-rendering it is what
- * this build removed from the projection. What an agent needs to decide the NEXT batch
- * is one percentage and the few largest names; everything else is a total.
- *
- * ONE DEFINITION OF STALE, AND IT IS THE SELECTOR'S OWN. The scope is class membership:
- * every result inside a batch `automaticToolBatches` admits, which is the same
- * enumeration `selectAutomaticToolBatch` picks its proposal out of. So the last call and
- * the deferred-commit record announce mass a commit can actually take, by construction
- * rather than by two filters kept in step. Counting whole-window tool results instead
- * announced material no rung could ever propose: rep 3 named 280k tokens while every
- * selector had nothing, which reads as a runtime refusing work it had just described.
- *
- * Membership is not ownership: the denominator is every member result, taken or not, so
- * the share reads as the fraction of reachable tool mass still unspoken for.
- */
 export function unmarkedRemainder(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -729,24 +524,12 @@ export function unmarkedRemainder(
   };
 }
 
-/** Every fold id already spoken for by a pending refold mark. */
 export function markedFoldIds(state: ActiveContextState): Set<string> {
   const ids = new Set<string>();
   for (const mark of pendingMarks(state)) if (mark.mark === "refold") ids.add(mark.id);
   return ids;
 }
 
-/**
- * THE COUNT LAW, AS MARKS. Every parent the eligible-root count owes right now, all of
- * them, in the epoch that notices.
- *
- * Separate from the top-up on purpose. The top-up is pressure arithmetic: it stops the
- * moment the marks in hand reach the freeing target, which is the right rule for how
- * DEEP a commit cuts and the wrong rule entirely for a law that says a count of eligible
- * roots at or above the width is a state that must not persist. So this runs at every
- * commit epoch and it runs first, whatever the pressure and whatever the top-up would
- * have proposed (Shane 2026-08-10).
- */
 export function consolidationMarks(input: {
   snapshot: ActiveContextSnapshot;
   state: ActiveContextState;
@@ -760,22 +543,12 @@ export function consolidationMarks(input: {
   }));
 }
 
-/**
- * Agent judgment leads; automation guarantees the floor. If the marks the agent made
- * would free less than the target share of the window, automation adds the stalest
- * unprotected eligible SPANS until they do: completed tool batches and raw narrative
- * chapters. Placeholders are not on that list any more; a placeholder gets a parent from
- * the count law above, which is not pressure arithmetic and does not stop at a target.
- */
 export function topUpMarks(input: {
   snapshot: ActiveContextSnapshot;
   state: ActiveContextState;
   ordinal: number;
-  /** Freeing target as a share of the SERVING BUDGET. Required: there is no second default. */
   targetShare: number;
-  /** Evidence keys the top-up may never propose, e.g. the current excursion's reads. */
   excludeRefKeys?: ReadonlySet<string>;
-  /** Measure progress against ELIGIBLE mass, so pinned or protected marks never count. */
   eligibleOnly?: boolean;
 }): PendingFoldMark[] {
   const { snapshot } = input;
@@ -789,7 +562,7 @@ export function topUpMarks(input: {
     return input.eligibleOnly ? accounting.eligibleFreedBudgetShare : accounting.freedBudgetShare;
   };
   let share = progress(state);
-  for (let attempt = 0; attempt < EPOCH_MAX_TOPUP_MARKS && share < target; attempt += 1) {
+  while (share < target) {
     const candidate = selectAutomaticSpan(snapshot, state, claimed);
     if (!candidate) break;
     const mark = foldMarkFor({
@@ -808,15 +581,8 @@ export function topUpMarks(input: {
   return marks;
 }
 
-/** One sliver a commit swallowed into its later neighbour, reported never inferred. */
 export interface AbsorbedWedge {
-  /** The mark that grew backward to cover it. */
   intoMarkId: string;
-  /**
-   * The id that mark carried BEFORE it grew. A mark's id is derived from its span, so
-   * growing the span mints a new one; without this the trail from the decision the
-   * agent made to the fold that carries it is broken, and a mark appears to vanish.
-   */
   fromMarkId: string;
   startId: string;
   endId: string;
@@ -824,28 +590,10 @@ export interface AbsorbedWedge {
   tokens: number;
 }
 
-/**
- * Wedge absorption. THE ANTI-LCM PIN LIVES HERE.
- *
- * A sliver of stale raw content hugging a fold boundary is a crumb nothing will ever
- * reclaim: it is below the minimum chapter size, so no chapter rung will take it, and
- * it is not a tool batch, so no tool rung will either. Absorbing it costs nothing
- * because it happens INSIDE a commit the epoch has already paid for -- it grows a
- * pending mark backward rather than performing a mutation of its own.
- *
- * What it must never do is erode deliberate non-sequential curation. An agent holding
- * folds at 10:20, 40:55 and 60:70 with raw spans between them chose that shape, and a
- * mechanism that swallowed those gaps would delete the curation element outright. So
- * the threshold is tiny, measured in the session's own calibrated tokens, and NOT
- * pressure-scaled: above it, a gap stays raw permanently no matter how full the window
- * gets or how ragged the projection looks.
- */
 export function absorbWedgeMarks(input: {
   snapshot: ActiveContextSnapshot;
   state: ActiveContextState;
-  /** The session's measured serialized chars per token; never a fixed constant. */
   charsPerToken: number;
-  /** Evidence absorption may never touch, e.g. the current excursion's own reads. */
   excludeRefKeys?: ReadonlySet<string>;
 }): { state: ActiveContextState; absorbed: AbsorbedWedge[] } {
   const { snapshot } = input;
@@ -863,9 +611,7 @@ export function absorbWedgeMarks(input: {
       .filter((index): index is number => index !== undefined);
     return indices.length ? { start: Math.min(...indices), end: Math.max(...indices) } : null;
   };
-  // One pass, oldest first. Each absorption rewrites exactly one mark, and a mark that
-  // has already grown is not a candidate to grow again in the same commit.
-  for (let guard = 0; guard < MAX_PENDING_MARKS; guard += 1) {
+  for (;;) {
     const marks = pendingMarks(state);
     const occupied = [
       ...orderedRoots(state, snapshot).map((root) => ({ start: root.start, end: root.end })),
@@ -886,7 +632,6 @@ export function absorbWedgeMarks(input: {
       if (gapStart < 0 || gapEnd < gapStart) continue;
       if (absorbed.some((item) => item.intoMarkId === mark.id)) continue;
       const gapTokens = Math.ceil(spanBytes(snapshot, gapStart, gapEnd + 1) / charsPerToken);
-      // The whole discriminator, in one line: above this, the gap is the agent's.
       if (gapTokens > MAX_WEDGE_ABSORB_TOKENS) continue;
       const gapRefs = [];
       let usable = true;
@@ -897,15 +642,19 @@ export function absorbWedgeMarks(input: {
       }
       if (!usable || !gapRefs.length) continue;
       if (refsProtected(gapRefs, state, snapshot)) continue;
-      // Structural safety: the grown span must still be a valid closed chapter, which
-      // is what keeps every tool call paired with its result in the projection.
       if (!chapterRangeIsUnitAligned(snapshot, gapStart, interval.end)) continue;
       const parts = partsForRange(snapshot, state, gapStart, interval.end, new Set<FoldKind>(["tool-result"]));
       if (!parts) continue;
+      // ELIGIBILITY, not truncation (Shane 2026-08-14): the grown fold's brief
+      // must name what it absorbed, and a brief already near the policy cap has
+      // no room for that sentence. Slicing dropped exactly the words that made
+      // the absorption honest, so a wedge whose truthful suffix does not fit is
+      // simply not absorbed; the gap stays raw for a later commit.
+      const absorbSuffix = ` It also holds ${gapRefs.length} short adjacent entry(s) absorbed at commit.`;
+      if (mark.brief.length + absorbSuffix.length > snapshot.policy.maxBriefChars) continue;
       const grown = foldMarkFor({
         candidate: { kind: "chapter", parts, sourceRefs: candidateSourceRefs(parts, state) },
-        brief: `${mark.brief} It also holds ${gapRefs.length} short adjacent entry(s) absorbed at commit.`
-          .slice(0, snapshot.policy.maxBriefChars),
+        brief: `${mark.brief}${absorbSuffix}`,
         briefProvenance: mark.briefProvenance,
         origin: mark.origin,
         ordinal: mark.ordinal,
@@ -941,7 +690,6 @@ export interface RefusedMark {
   id: string;
   origin: MarkOrigin;
   reason: string;
-  /** Whether the mark survives as pending rather than being discarded. */
   retained: boolean;
 }
 
@@ -950,38 +698,16 @@ export interface CommitEpochResult {
   applied: AppliedMark[];
   refused: RefusedMark[];
   retained: PendingMark[];
-  /** Guarded marks the pressure waiver released into this commit, oldest material first. */
   waived: PendingMark[];
 }
 
-/**
- * Apply every pending mark. This is the ONE mutation of the epoch: it reuses
- * prepareFold/commitPreparedFold exactly as the immediate path does, so a committed
- * mark and an immediate fold produce the same fold record.
- */
 export async function commitPendingMarks(input: {
   snapshot: ActiveContextSnapshot;
   state: ActiveContextState;
   generation: number;
   now?: () => number;
-  /**
-   * Keep marks the commit could not apply YET. A mark is a standing decision; dropping
-   * it because the span happened to be fresh at commit time silently discards the
-   * agent's judgment and leaves nothing for the next commit to act on.
-   */
   retainIneligible?: boolean;
-  /**
-   * Never fold evidence the CURRENT excursion gathered. A commit that runs between
-   * an agent's read and its use of that read hands the agent a window where its own
-   * just-gathered evidence is a placeholder. Such marks stay pending for the next
-   * commit rather than being applied or dropped.
-   */
   guardCurrentTurn?: boolean;
-  /**
-   * How many guarded marks the pressure waiver releases anyway, oldest material first. The
-   * guard protects an in-flight excursion; it may never cost the session its ability
-   * to send a request at all. See `guardWaiverCount`.
-   */
   guardWaiver?: number;
 }): Promise<CommitEpochResult> {
   const marks = pendingMarks(input.state);
@@ -990,13 +716,6 @@ export async function commitPendingMarks(input: {
   const guardReasons = new Map<string, string>();
   const held = new Set(input.state.folds.map((fold) => fold.id));
   const deferred: PendingMark[] = [];
-  /**
-   * Whether the mark names a fold some other standing mark is about to mint. Until that
-   * fold exists there is no eligibility worth judging: the question is about material
-   * the child owns, and the apply loop is where it gets asked, after the child has
-   * landed. A mark naming a fold NOBODY will mint is not this case; it is judged
-   * normally, and the apply loop drops it by name.
-   */
   const awaitingMintedChild = (mark: PendingMark): boolean =>
     markSpanRefs(input.state, mark).unresolved?.pending === true;
   const currentTurn = input.guardCurrentTurn
@@ -1009,11 +728,6 @@ export async function commitPendingMarks(input: {
       if (markTouchesCurrentTurn(input.state, mark, currentTurn)) guarded.push(mark);
       else applicable.push(mark);
     }
-    // Oldest MATERIAL first: the newest reads are the ones the excursion is about to
-    // use, so they are the last evidence the waiver surrenders. Staleness is a property
-    // of the span, never of when the mark was proposed; see `markSpanStart`. The id
-    // comparison is the final tiebreak between marks covering the same start, and
-    // nothing else.
     const guardedStart = new Map(guarded.map((mark) =>
       [pendingMarkKey(mark), markSpanStart(input.snapshot, input.state, mark)] as const));
     guarded.sort((left, right) =>
@@ -1038,10 +752,6 @@ export async function commitPendingMarks(input: {
   if (input.retainIneligible) {
     const applicable: PendingMark[] = [];
     for (const mark of marks) {
-      // A mark awaiting a child another mark will mint is not judged here. Its
-      // eligibility is a question about material the child fold owns, and that fold is
-      // what this commit is about to create. The apply loop asks it once the child has
-      // landed, and answers by name when it does not.
       if (!awaitingMintedChild(mark) &&
           markEligibility(input.snapshot, input.state, mark) === "protected") retained.push(mark);
       else applicable.push(mark);
@@ -1059,23 +769,6 @@ export async function commitPendingMarks(input: {
       "span is still fresh or protected; the mark stays pending until it is eligible",
     retained: true,
   }));
-  // CHILDREN BEFORE THE SPANS THAT ABSORB THEM, AND TRANSCRIPT ORDER IS NOT THAT ORDER.
-  //
-  // The invariant is real: a span whose parts name another mark's fold must find that
-  // fold in the forest when it applies. `foldMarkFor` gives a mark the id its committed
-  // fold will carry, so the naming is exact and readable off the parts. What it is NOT is
-  // geometry. A parent CONTAINS its child, so the earliest window index a parent covers
-  // is at or before its child's, and ordering oldest material first applies the parent
-  // FIRST in exactly the case the invariant exists for. The cost is not a reordering:
-  // `candidateSourceRefs` throws `Missing candidate child` on the unresolved part, the
-  // apply loop catches it, and the mark is refused with `retained: false`, so the parent
-  // applied one place too early loses the agent's decision outright rather than waiting.
-  //
-  // So the dependency is the law and the sort key is the tiebreak. Among marks with no
-  // such tie, real transcript order: the earliest window index the span covers, oldest
-  // material first, id last. The `ordinal` this used to sort on is the transcript position
-  // at MARK time, one value shared by every mark an epoch proposes, so within an epoch it
-  // decided nothing and the order fell through to comparing content hashes.
   const minting = new Map(marks.flatMap((mark) =>
     mark.mark === "fold" && !held.has(mark.id) ? [[mark.id, mark] as const] : []));
   const applyStart = new Map(marks.map((mark) =>
@@ -1088,9 +781,6 @@ export async function commitPendingMarks(input: {
   const placing = new Set<string>();
   const place = (mark: PendingMark): void => {
     const key = pendingMarkKey(mark);
-    // `placing` is the cycle stop. Fold ids are hashes OF the parts, so a cycle would
-    // need a hash to name its own ancestor; the guard is here so a corrupt state loses
-    // one mark to the ordinary refusal rather than hanging the commit.
     if (placed.has(key) || placing.has(key)) return;
     placing.add(key);
     if (mark.mark === "fold") {
@@ -1117,15 +807,6 @@ export async function commitPendingMarks(input: {
         continue;
       }
       const parts = clone(mark.parts);
-      // THE ANSWER TO A NAME THE STATE CANNOT RESOLVE, AND IT IS TWO ANSWERS.
-      //
-      // A mark still standing will mint the fold this one names, so the span becomes
-      // readable at the next commit: that is a DEFER, and the mark stays pending. This
-      // is the child a guard held while its parent was applicable, which the epoch used
-      // to discard outright. Nothing standing names it and it is a DROP: `reboundary`
-      // dissolved the fold, or the mark that would have minted it was itself refused,
-      // and no later commit can honour the decision. Same two words the eligibility
-      // reading uses, and the same receipt shape a dropped brief upgrade gets.
       const span = markSpanRefs(state, mark);
       if (span.unresolved) {
         const { foldId, pending } = span.unresolved;
@@ -1169,9 +850,6 @@ export async function commitPendingMarks(input: {
         generation: input.generation,
       });
       applied.push({ mark: "fold", id: mark.id, origin: mark.origin, foldId: prepared.id });
-      // A warmed preparation the commit just materialized through its mark is spent:
-      // leaving it standing would hold a prepared fold whose id already exists in the
-      // forest, and every later drift check would refuse it by name.
       if (state.prepared && state.folds.some((fold) => fold.id === state.prepared!.id)) {
         state = clearPrepared(state);
       }
@@ -1185,9 +863,6 @@ export async function commitPendingMarks(input: {
       });
     }
   }
-  // Deferrals rejoin the pending set. A mark the loop could not read yet is a standing
-  // decision exactly as a guard-held one is, and `retained` is what the commit record
-  // counts as deferred, so both live in the same list.
   if (deferred.length) {
     state = withPendingMarks(state, [...pendingMarks(state), ...deferred]);
     retained.push(...deferred);
@@ -1195,7 +870,6 @@ export async function commitPendingMarks(input: {
   return { state, applied, refused, retained, waived };
 }
 
-/** The scheduling block reported by the status action. */
 export function schedulingStatus(input: {
   snapshot: ActiveContextSnapshot;
   state: ActiveContextState;
@@ -1203,16 +877,11 @@ export function schedulingStatus(input: {
 }): Record<string, unknown> {
   const accounting = markAccounting(input.snapshot, input.state);
   return {
-    // A literal, not a setting: epoch is the only scheduler there is.
     mode: "epoch",
     ...accounting,
-    // The declared policy, reported never mutable.
     thresholds: { ...input.snapshot.thresholds },
     budgetTokens: input.snapshot.budgetTokens,
     commitDue: epochCommitDue(input.snapshot, input.ratio),
-    // One trigger, reported as one line. The eligible share is still reported above in
-    // the accounting because it is what a commit WOULD free; it is no longer a reason
-    // to fire one.
     commitTrigger: {
       mode: "band-top",
       commitOccupancy: input.snapshot.thresholds.maxTarget,