pi-fold 4.1.6 → 4.2.0

package/extensions/active-context.ts

@@ -85,6 +85,7 @@ import {
   makeStateCheckpoint,
   makeStateDelta,
   MAX_ACTIVE_FOLD_RECORDS,
+  MAX_DELTAS_BETWEEN_CHECKPOINTS,
   materializeStatePersistence,
   foldProvenance,
   normalizeFoldsForPersistedRecords,
@@ -118,7 +119,7 @@ import {
   ESTIMATED_BYTES_PER_TOKEN,
   IMAGE_ESTIMATED_TOKENS,
   entryTypeNamespace,
-  MAX_FOLD_SPAN_CHARS,
+  chapterSpanCap,
   DEFAULT_TOOL_FOLD_THRESHOLD,
   MAX_PINNED_SHARE,
   PEEK_DEFAULT_MAX_BYTES,
@@ -432,6 +433,14 @@ export function registerActiveContext(pi: any, options: {
     state: null as ActiveContextState | null,
     persisted: null as ActiveContextState | null,
     persistedWireVersion: 0 as 0 | 1 | 2,
+    /** Set when the branch HELD durable state this build could not read. Distinct from a
+     *  session that never had any, which is what `persistedWireVersion` 0 also means and
+     *  which legitimately writes the first checkpoint. See `persist`. */
+    lineageUnreadable: false,
+    /** Deltas standing after the newest checkpoint in the branch. See
+     *  `MAX_DELTAS_BETWEEN_CHECKPOINTS`: at the bound, `persist` writes a checkpoint instead
+     *  of a delta, which is what keeps a load's replay bounded. */
+    deltasSinceCheckpoint: 0,
     persistedStateSha256: "",
     persistedFoldRecords: new Map<string, FoldRecordEntry>(),
     persistenceQueue: Promise.resolve<void>(undefined),
@@ -1187,7 +1196,19 @@ export function registerActiveContext(pi: any, options: {
     }
     const durableRestored = restored ?? emptyActiveContextState(sessionId);
     persistence.state = durableRestored.prepared ? clearPrepared(durableRestored) : clone(durableRestored);
+    // AN UNREADABLE LINEAGE IS NOT AN EMPTY ONE (2026-09-07). `persistedWireVersion` reads
+    // 0 for both, and `persist` writes a CHECKPOINT whenever it is not 2, so a restore that
+    // threw put a second checkpoint into a branch that already had one. The reader refuses
+    // exactly that ("Duplicate active-context v2 checkpoint"), so the next load threw too,
+    // and wrote a third. ONE TRANSIENT FAILURE OF ANY CAUSE LATCHED THE SESSION DEAD AND
+    // EVERY RELOAD MADE IT STRICTLY WORSE: a real session reached five checkpoints, four of
+    // them from four /reload presses inside eleven minutes, and grew from 859 entries to
+    // 4,393 because each restart also re-cut the same spans and wrote fold records under
+    // the same ids with drifted bytes, 48 of 85 ids left conflicting. The two states are
+    // told apart here, once, rather than at each of `persist`'s callers.
+    persistence.lineageUnreadable = restoreError !== null;
     persistence.persistedWireVersion = restoredPersistence?.wireVersion ?? 0;
+    persistence.deltasSinceCheckpoint = restoredPersistence?.deltasSinceCheckpoint ?? 0;
     persistence.persistedFoldRecords = restoredPersistence?.records ?? new Map<string, FoldRecordEntry>();
     persistence.persistedStateSha256 = restoredPersistence?.stateSha256 ?? semanticStateSha256(durableRestored);
     const restoredMessages = ctx.sessionManager.buildSessionContext?.()?.messages;
@@ -1205,11 +1226,19 @@ export function registerActiveContext(pi: any, options: {
       try { foldBar.startupSnapshot = snapshotForEvent(ctx, restoredMessages); }
       catch { /* Keep the honest mapping fallback if the host cannot supply a view. */ }
     }
-    if (restoreError) safeNotify(
-      ctx,
-      `Active-context state was ignored; Pi native context remains authoritative: ${String(restoreError)}`,
-      "warning",
-    );
+    // The warning names the CONSEQUENCE and not only the cause: "state was ignored" read as
+    // graceful degradation, and the session it described could no longer fold at all. The
+    // suspension carries no ctx of its own so the canonical `context.suspend` record is
+    // emitted for a headless host without a second UI line saying the same thing twice.
+    if (restoreError) {
+      safeNotify(
+        ctx,
+        "Active-context state could not be read, so folding is suspended for this session and " +
+        `Pi native context remains authoritative: ${String(restoreError)}`,
+        "warning",
+      );
+      suspendAutomatic(restoreError, "restore", undefined);
+    }
     if (measurementRestoreError) safeNotify(
       ctx,
       `Malformed provider measurement receipt was ignored; automatic context remains unmeasured: ${String(measurementRestoreError)}`,
@@ -1220,6 +1249,18 @@ export function registerActiveContext(pi: any, options: {
   const persist = (ctx?: any): Promise<void> => {
     const operation = persistence.persistenceQueue.then(async () => {
       if (!persistence.state || !persistence.persisted) return;
+      // THE ONE WRITE THAT MUST NOT HAPPEN. Folding is suspended the moment a restore fails,
+      // so nothing automatic reaches this; a manual action still can, and one appended state
+      // entry is all it takes to latch the session. Raising rather than returning keeps the
+      // law of the discarded commit: a write that cannot land says so instead of vanishing,
+      // and the manual path already restores the state it entered with and reports.
+      if (persistence.lineageUnreadable) {
+        throw new Error(
+          "Active-context durable state is unreadable for this session, so no state may be " +
+          "written: a checkpoint here would be the second in this branch and would make every " +
+          "later load fail",
+        );
+      }
       let next = clone(persistence.state);
       const persistedFoldIds = new Set(persistence.persisted.folds.map((fold) => fold.id));
       const arrivingFoldIds = next.folds.filter((fold) => !persistedFoldIds.has(fold.id)).map((fold) => fold.id);
@@ -1287,7 +1328,15 @@ export function registerActiveContext(pi: any, options: {
           throw new Error("Active-context session changed after fold-record persistence");
         }
       }
-      const wire = persistence.persistedWireVersion === 2 ? makeStateDelta(persistence.persisted, next) : makeStateCheckpoint(next);
+      // A CHECKPOINT ENDS THE RUN THE READER WOULD OTHERWISE WALK (2026-09-20). A delta is
+      // the cheap write and stays the common one; at the bound the run is closed instead, so
+      // the next load replays at most `MAX_DELTAS_BETWEEN_CHECKPOINTS` deltas however long the
+      // session runs. A session that is already past the bound when this build first reads it
+      // closes its run on this write, so it pays the long load once and never again.
+      const runIsLong = persistence.deltasSinceCheckpoint >= MAX_DELTAS_BETWEEN_CHECKPOINTS;
+      const wire = persistence.persistedWireVersion === 2 && !runIsLong
+        ? makeStateDelta(persistence.persisted, next)
+        : makeStateCheckpoint(next);
       // THE WIRE CARRIES BOTH DIGESTS IT JUST DERIVED (2026-08-28). `makeStateDelta` writes
       // `baseStateSha256` from `persistence.persisted` and `stateSha256` from `next`, and
       // nothing mutates either state between that call and here, so re-hashing two whole
@@ -1301,6 +1350,7 @@ export function registerActiveContext(pi: any, options: {
       await pi.appendEntry(stateEntryType, wire);
       persistence.persisted = clone(next);
       persistence.persistedWireVersion = 2;
+      persistence.deltasSinceCheckpoint = wire.kind === "checkpoint" ? 0 : persistence.deltasSinceCheckpoint + 1;
       persistence.persistedStateSha256 = wire.stateSha256;
       persistence.state = lifecycle.shuttingDown ? null : clone(next);
       if (!sessionIdentityStillValid(ctx, sessionId, generationAtStart)) {
@@ -4147,7 +4197,7 @@ export function registerActiveContext(pi: any, options: {
               last: rollback.last ? clone(rollback.last) : null,
             },
           },
-          foldSpanCap: MAX_FOLD_SPAN_CHARS,
+          foldSpanCap: chapterSpanCap(thresholds.minFoldChars),
           projectionBudgetTokens: currentCapacity(ctx).budgetTokens,
           projectionCharsPerToken: projectionCharsPerToken(),
           projectionEstimatorErrorShare: estimatorErrorShare(),

package/extensions/lib/folding.ts

@@ -51,7 +51,7 @@ import {
   CONTEXT_STATUS_RESPONSE_BYTES,
   EXPAND_LEASE_GENERATIONS,
   MAX_EXPAND_LEASES,
-  MAX_FOLD_SPAN_CHARS,
+  chapterSpanCap,
   PEEK_DEFAULT_MAX_BYTES,
   PEEK_HEAD_SHARE,
   STATUS_DIET_INDEX_ROWS,
@@ -95,6 +95,10 @@ export function selectAutomaticChapter(
   // The maturity floor: a stale span may end only where the batch lane has already had
   // its chance, so a chapter can never claim a tool batch one turn before it qualifies.
   const matureEnd = staleSpanMatureEnd(snapshot.messages);
+  // THE CAP FOLLOWS THE FLOOR: a multi-unit span may not pass it, and it sits at least
+  // one floor above `minFoldChars` so the accumulate-until-over walk below can always
+  // land between the two (policy.ts, chapterSpanCap).
+  const spanCap = chapterSpanCap(snapshot.thresholds.minFoldChars);
   for (let unitIndex = 0; unitIndex < units.length; unitIndex += 1) {
     const first = units[unitIndex];
     if (first.end > matureEnd) break;
@@ -131,12 +135,12 @@ export function selectAutomaticChapter(
       if (claimed.size && refs.some((ref) => claimed.has(objectRefKey(ref)))) break;
       if (refsProtected(refs, state, snapshot)) break;
       const size = bytes(encodedFoldSource(snapshot, state, parts, "chapter"));
-      const biteSized = size <= MAX_FOLD_SPAN_CHARS || endIndex === unitIndex;
+      const biteSized = size <= spanCap || endIndex === unitIndex;
       // ACCUMULATE UNTIL OVER, never cut to hit the number. The walk grows the span one
       // whole unit at a time and records the first one that carries it past the floor,
       // so a fold is always at least minFoldChars and always ends on a message boundary.
       if (size >= snapshot.thresholds.minFoldChars && biteSized) best = { kind: "chapter", parts, sourceRefs: refs };
-      if (size > MAX_FOLD_SPAN_CHARS) break;
+      if (size > spanCap) break;
     }
     if (best) return best;
   }

package/extensions/lib/persistence.ts

@@ -68,6 +68,53 @@ export const STATE_DELTA_V2_KEYS = [
 export const MAX_ACTIVE_FOLD_RECORD_BYTES = 256 * 1024;
 export const MAX_ACTIVE_STATE_EVENT_BYTES = 512 * 1024;
 export const MAX_ACTIVE_FOLD_RECORDS = 4_096;
+
+/**
+ * HOW MANY DELTAS MAY STAND BETWEEN CHECKPOINTS (2026-09-20).
+ *
+ * The v2 ledger was one checkpoint and then deltas for the life of the session, and
+ * `materializeStatePersistence` replays every one of them on every load. Each delta rebuilds
+ * the WHOLE state, so a load costs the delta count times the state size: quadratic in
+ * session length. Shane's noloss session 01a0ad40 reached 2,207 deltas and took 129.6s to
+ * restore, against 0.6s for pi to parse the same 93MB of entries; 01a0ba4e took 56.1s on
+ * 1,147 deltas. Doubling the entries quadrupled the time (3,987 entries 9.3s, 7,974 entries
+ * 38.8s) and the per-delta cost rose with it (7.5ms to 57.0ms), because what each delta
+ * re-walks is the state, not the delta. The load is also not paid once: `session_start`,
+ * `session_tree`, `session_compact` and a branch switch each pay it again, and
+ * `doubleEscapeAction: "tree"` puts it behind a keypress.
+ *
+ * A CHECKPOINT STATES THE WHOLE STATE, so a replay may start at the LAST one rather than the
+ * only one and never walk the run before it. That bounds a load at this many deltas instead
+ * of at the session's lifetime. Nothing is weakened by starting later: a checkpoint carries
+ * its own digest and the deltas after it still chain, so the final state is proven by the
+ * same equalities as before. What a later start gives up is re-proving revisions that were
+ * already proven when they were written, and the fingerprint map loses the revisions before
+ * the checkpoint, which its one reader already treats as absent (see `projectionFingerprints`).
+ *
+ * THE BOUND IS A TRADE, AND 50 IS WHERE IT WAS MEASURED. A checkpoint names every standing
+ * fold by id and digest, so it costs far more bytes than a delta: 237.9KB against a 2.55KB
+ * delta at 375 folds, 248.9KB against 3.34KB at 213. The load after a checkpoint is 0.34s and
+ * 0.20s for those two sessions, and each replayed delta adds about 85ms at 375 folds, so the
+ * bound sets both the worst load and the write overhead:
+ *
+ *   K=100   8.8s worst load   +93% state-ledger bytes   (+5.6% of the session file)
+ *   K= 50   4.4s worst load  +187% state-ledger bytes   (+11% of the session file)
+ *   K= 25   2.2s worst load  +374% state-ledger bytes   (+22% of the session file)
+ *
+ * The state ledger is a small part of a session (5.9MB of 01a0ad40's 93MB), which is why the
+ * percentages look worse against the ledger than against the file. 50 takes the worst load
+ * under five seconds and the average near two, for a tenth of the file, and a session already
+ * past the bound heals itself on its next durable write.
+ *
+ * WHAT WOULD MAKE THE BOUND STOP MATTERING is the per-delta cost itself, which is still the
+ * whole state: 23.8% of a profiled load is `structuredClone` and 34% is `stableStringify`
+ * under `semanticStateSha256`, both walking every standing fold on every delta. Neither is
+ * reachable without giving the reader one canonical fold object per id for the life of a
+ * materialization, so that the clone stops being per-delta and a serializer memo can hit at
+ * all. That is a change to the aliasing barrier gate 158 guards and is deliberately NOT made
+ * here; until it is, this constant is what bounds the load.
+ */
+export const MAX_DELTAS_BETWEEN_CHECKPOINTS = 50;
 export const MAX_ACTIVE_FOLD_PARTS = 1_024;
 export const MAX_ACTIVE_EXPANDED = 1_024;
 export const MAX_ACTIVE_PROTECTED = 1_024;
@@ -269,15 +316,54 @@ export function directFoldOwners(folds: readonly ActiveFold[]): Map<string, stri
   return owner;
 }
 
+/**
+ * A FOLD THIS MATERIALIZATION HAS ALREADY PROVEN, AND WILL NOT PROVE AGAIN (2026-09-20).
+ *
+ * The replay's cost was never the deltas, it was re-proving the whole forest at each one.
+ * `stateFromFoldRefs` runs per delta and ends in `parseActiveContextState`, so a session with
+ * 2,207 deltas and 400 standing folds recomputed 400 content addresses and flattened and
+ * hashed 400 fold subtrees 2,207 times over. Profiling a 1,147-delta load put 48.2% of all
+ * time inside `validateFoldForest` and 14.8% on `foldIdFor` alone.
+ *
+ * WHAT THE MARK ASSERTS, and why each half of it is already true:
+ *
+ *   The content address. `parseFoldRecordEntry` refuses a record unless
+ *   `fold.id === foldIdFor(fold.kind, fold.parts)`, and every fold reaching a marked forest
+ *   came out of `records` past that check, matched to its ref on `recordSha256`. The only
+ *   field `assignFoldParents` writes is `parentId`, which `foldIdFor` does not read. So the
+ *   recomputation could not reach a different verdict. This is the argument the 2026-08-28
+ *   `foldRecordRef` change already made in `persist`, applied on the reading side.
+ *
+ *   The source digest. This one is NOT implied by the record, so it is not skipped: it is
+ *   paid ONCE PER DISTINCT FOLD PER MATERIALIZATION instead of once per delta. A fold's
+ *   flattened refs are a pure function of its id, because the id pins kind and parts and each
+ *   child id pins its own subtree in turn, so a second computation over the same id is
+ *   arithmetic already done. `stateFromFoldRefs` marks only ids already proven against THIS
+ *   records map and leaves a newly arriving fold unmarked, so its digest is still checked, and
+ *   still inside `validateFoldForest` after the ownership loop that proves its children are
+ *   present. Error ordering is unchanged.
+ *
+ * KEYED ON OBJECT IDENTITY, like gate 160's VALIDATED_FORESTS, so nothing outside this module
+ * can present itself as proven. It carries none of gate 160's stated cost: a fold mutated in
+ * place is never marked, because the mark is applied to the objects `assignFoldParents` has
+ * just built and is read before `clone` hands the forest on.
+ */
+const RECORD_PROVEN_FOLDS = new WeakSet<ActiveFold>();
+const PROVEN_SOURCE_DIGESTS = new WeakMap<Map<string, FoldRecordEntry>, Set<string>>();
+
 export function validateFoldForest(folds: ActiveFold[]): ActiveFold[] {
   const rawValues = denseOwnArrayValues(folds);
   if (!rawValues || rawValues.some((fold) => !validFoldShape(fold))) {
     throw new Error("Invalid active-context fold forest shape");
   }
   const values = clone(rawValues) as ActiveFold[];
+  // READ OFF THE CALLER'S OBJECTS, BEFORE THE CLONE ABOVE COSTS US THE IDENTITY. `clone`
+  // preserves order, so the verdict for `values[i]` is the mark on `rawValues[i]`.
+  const proven = rawValues.map((fold) => RECORD_PROVEN_FOLDS.has(fold as ActiveFold));
   const byId = new Map<string, ActiveFold>();
-  for (const fold of values) {
-    if (fold.id !== foldIdFor(fold.kind, fold.parts) || byId.has(fold.id)) {
+  for (let index = 0; index < values.length; index += 1) {
+    const fold = values[index];
+    if ((!proven[index] && fold.id !== foldIdFor(fold.kind, fold.parts)) || byId.has(fold.id)) {
       throw new Error("Invalid active-context fold");
     }
     if (fold.kind === "tool-result" &&
@@ -304,7 +390,9 @@ export function validateFoldForest(folds: ActiveFold[]): ActiveFold[] {
   for (const fold of values) {
     if ((parent.get(fold.id) ?? null) !== fold.parentId) throw new Error(`Fold ${fold.id} parent drift`);
   }
-  for (const fold of values) {
+  for (let index = 0; index < values.length; index += 1) {
+    if (proven[index]) continue;
+    const fold = values[index];
     const refs = flattenFoldRefs(fold, { folds: values });
     if (fold.sourceSha256 !== sha256Value(refs)) throw new Error(`Fold ${fold.id} source digest drift`);
   }
@@ -890,13 +978,28 @@ export function stateFromFoldRefs(
     if (!record || record.recordSha256 !== ref.sha256) throw new Error(`Missing active-context fold record ${ref.id}`);
     return record.fold;
   });
+  const parented = assignFoldParents(folds);
+  // WHAT THIS MATERIALIZATION HAS ALREADY PROVEN IS MARKED; THE REST IS STILL PROVEN BELOW.
+  // See RECORD_PROVEN_FOLDS. A fold standing across deltas is marked from its second
+  // appearance on, so its content address and source digest are computed once for the whole
+  // replay rather than once per delta. A fold arriving now is deliberately left unmarked: its
+  // digest is checked by `validateFoldForest`, after the loop that proves its children are
+  // present, exactly where it was checked before.
+  let provenIds = PROVEN_SOURCE_DIGESTS.get(records);
+  if (!provenIds) {
+    provenIds = new Set<string>();
+    PROVEN_SOURCE_DIGESTS.set(records, provenIds);
+  }
+  for (const fold of parented) {
+    if (provenIds.has(fold.id)) RECORD_PROVEN_FOLDS.add(fold);
+  }
   const state: ActiveContextState = {
     version: 1,
     sessionId: wire.sessionId,
     revision: wire.revision,
     // `parseActiveContextState` at the end of this function validates the forest, so
     // validating it here as well was the same walk twice on one persist.
-    folds: assignFoldParents(folds),
+    folds: parented,
     expanded: clone(wire.expanded),
     protected: clone(wire.protected),
     tokensSinceToolFold: wire.tokensSinceToolFold ?? 0,
@@ -907,7 +1010,10 @@ export function stateFromFoldRefs(
     ...(wire.advisory === undefined ? {} : { advisory: clone(wire.advisory) }),
     ...(wire.prepared === null || wire.prepared === undefined ? {} : { prepared: clone(wire.prepared) }),
   };
-  return parseActiveContextState(state, wire.sessionId, false);
+  const parsed = parseActiveContextState(state, wire.sessionId, false);
+  // RECORDED ONLY ONCE THE FOREST HAS PASSED, so a throw leaves nothing marked as proven.
+  for (const fold of parented) provenIds.add(fold.id);
+  return parsed;
 }
 
 export interface ProjectionFingerprint {
@@ -933,6 +1039,12 @@ export interface MaterializedStatePersistence {
   records: Map<string, FoldRecordEntry>;
   stateSha256: string;
   projectionFingerprints: ProjectionFingerprints;
+  /**
+   * HOW MANY DELTAS STAND AFTER THE LAST CHECKPOINT in the branch just read. `persist` writes
+   * a checkpoint instead of a delta once this reaches `MAX_DELTAS_BETWEEN_CHECKPOINTS`, which
+   * is what stops the run, and therefore the load, from growing without bound.
+   */
+  deltasSinceCheckpoint: number;
 }
 
 export function materializeStatePersistence(
@@ -985,6 +1097,7 @@ export function materializeStatePersistence(
   let stateStart = -1;
   let checkpointIndex = -1;
   let v2Seen = false;
+  let deltasSinceCheckpoint = 0;
   const rememberProjection = (): void => {
     fingerprintSources.set(state.revision, state);
   };
@@ -1001,11 +1114,25 @@ export function materializeStatePersistence(
     if (version !== 2) throw new Error("Invalid active-context persisted state version");
     const kind = ownValue(entry.data, "kind");
     if (kind === "checkpoint") {
-      if (v2Seen || checkpointIndex >= 0) throw new Error("Duplicate active-context v2 checkpoint");
+      // THE LAST CHECKPOINT WINS, AND A SECOND ONE IS NO LONGER FATAL (2026-09-20). This
+      // raised "Duplicate active-context v2 checkpoint" on sight of a second, which made the
+      // ledger append-only in the strongest sense: one checkpoint, then deltas forever, and a
+      // replay that walked all of them on every load. Restarting the replay at the newest
+      // checkpoint is what makes `MAX_DELTAS_BETWEEN_CHECKPOINTS` possible, and it reaches
+      // the same final state by the same digest equalities.
+      //
+      // It also un-latches the failure gate 173 describes. A branch that took a second
+      // checkpoint from a failed restore used to be unreadable forever, and every reload made
+      // it worse; such a branch now reads from its newest checkpoint. That is a second line of
+      // defence, not the first: the `lineageUnreadable` guard in `persist` still refuses to
+      // write the state entry that starts the damage, and gate 173 still pins it.
       checkpointIndex = index;
       stateStart = index;
+      deltasSinceCheckpoint = 0;
     } else if (checkpointIndex < 0) {
       throw new Error("Active-context v2 delta precedes migration checkpoint");
+    } else {
+      deltasSinceCheckpoint += 1;
     }
     v2Seen = true;
   }
@@ -1142,7 +1269,7 @@ export function materializeStatePersistence(
     writtenSha256 = wire.stateSha256 === calculated ? null : wire.stateSha256;
     rememberProjection();
   }
-  return { state, wireVersion, records, stateSha256, projectionFingerprints };
+  return { state, wireVersion, records, stateSha256, projectionFingerprints, deltasSinceCheckpoint };
 }
 
 export function materializeActiveContextState(

package/extensions/lib/policy.ts

@@ -343,6 +343,26 @@ export const CONTEXT_STATUS_RESPONSE_BYTES = 24_000;
 export const MAX_UNMARKED_CANDIDATES = 3;
 
 export const MAX_FOLD_SPAN_CHARS = 16_000;
+
+/**
+ * THE LADDER'S CHAPTER CAP FOLLOWS THE FLOOR (2026-09-07).
+ *
+ * `selectAutomaticChapter` accumulates whole units until a span reaches `minFoldChars` and
+ * refuses a multi-unit span past this cap, so the cap has to sit at least one unit above
+ * the floor or the walk can never satisfy both. At the shipped 8,000 the 16,000 constant
+ * does. /fold-settings offers floors up to 32,000, and at any floor past the constant every
+ * multi-unit chapter was refused by arithmetic: only a single oversized unit or a tool batch
+ * could fold, and a prose session with the floor at 32,000 held its raw material forever
+ * while the status row announced a commit (session 01a07498, 2026-09-07: fourteen sizable
+ * units in view, none over 32,000, the frontier staging nothing). Twice the floor is the
+ * smallest cap under which a walk that crosses the floor by one unit shorter than the floor
+ * always lands inside it; the constant stays as the cap's own floor so every default reads
+ * exactly as before, and a manual span is never bounded by either (Shane, 2026-08-22).
+ */
+export function chapterSpanCap(minFoldChars: number): number {
+  return Math.max(MAX_FOLD_SPAN_CHARS, 2 * minFoldChars);
+}
+
 export const PEEK_DEFAULT_MAX_BYTES = 16_000;
 export const PEEK_HEAD_SHARE = 0.6;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fold",
-  "version": "4.1.6",
+  "version": "4.2.0",
   "description": "Lossless context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
   "keywords": [
     "pi-package",