pi-fold 4.1.6 → 4.2.1

package/README.md

@@ -14,7 +14,7 @@
 pi install npm:pi-fold
 ```
 
-Node 22 or later, Pi 0.83 or later. MIT licensed.
+Node 22 or later and Pi 0.83 or later. Pi 1.0 is supported and requires Node 22.19 or later. MIT licensed. Pi supplies the extension's runtime packages; they are declared as host-provided peers, not private dependencies.
 
 Folding does not require a memory store, but every best result measured came from pairing it with one. The campaigns used [pi-canon](https://github.com/shaneconner/canon), installed separately. The two began as a single working setup and were split into separate extensions for modularity, and the experiments are what established that they work better as complements than either does alone. Only that pairing has been measured. Any durable long-term memory store is expected to compose the same way, though that is a suspicion rather than a result.
 

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.1",
   "description": "Lossless context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
   "keywords": [
     "pi-package",
@@ -37,7 +37,8 @@
     "test": "node tests/verify.mjs"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.83.0 <1"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -52,8 +53,5 @@
     "extensions": [
       "./extensions"
     ]
-  },
-  "dependencies": {
-    "@earendil-works/pi-tui": "^0.84.2"
   }
 }