pi-fold 3.0.0 → 4.0.0

package/extensions/lib/persistence.ts

@@ -22,6 +22,9 @@ import {
   EXPAND_LEASE_GENERATIONS,
   MAX_EXPAND_LEASES,
   MAX_PENDING_MARKS,
+  MEMORY_BODY_CHARS,
+  MEMORY_KEY_CHARS,
+  MEMORY_KEYS_MAX,
 } from "./policy.ts";
 import type {
   ActiveContextCheckpointV2,
@@ -32,6 +35,7 @@ import type {
   AdvisoryMilestone,
   BriefOverride,
   BriefProvenance,
+  ToolClip,
   FoldKind,
   FoldPart,
   FoldRecordEntry,
@@ -167,7 +171,8 @@ export function parseLeases(value: unknown, foldIds?: ReadonlySet<string>): Reco
 
 export function validProvenance(value: unknown): value is BriefProvenance {
   if (exactRecord(value, ["kind"]) &&
-      (ownValue(value, "kind") === "supplied" || ownValue(value, "kind") === "deterministic")) return true;
+      (ownValue(value, "kind") === "supplied" || ownValue(value, "kind") === "deterministic" ||
+       ownValue(value, "kind") === "augmented")) return true;
   const hasDigest = Boolean(value && typeof value === "object" &&
     Object.prototype.hasOwnProperty.call(value, "launchContractDigest"));
   if (!exactRecord(value, ["kind", "provider", "model", "effort", ...(hasDigest ? ["launchContractDigest"] : [])]) ||
@@ -323,6 +328,12 @@ export function parseActiveContextState(
   const hasPendingMarks = recordLike && Object.prototype.hasOwnProperty.call(value, "pendingMarks");
   const hasPinnedPeeks = recordLike && Object.prototype.hasOwnProperty.call(value, "pinnedPeeks");
   const hasBriefs = recordLike && Object.prototype.hasOwnProperty.call(value, "briefs");
+  const hasClips = recordLike && Object.prototype.hasOwnProperty.call(value, "clips");
+  // Read and dropped, never stored (2026-08-28): the working memory is deleted, and a
+  // sealed state that carries it must still load. Tolerating the key while discarding the
+  // value is the legacy-rider treatment, not the retired-field refusal: sol-20260826-full2
+  // reps 4 and 6 ran with it, and a campaign this package still cites has to stay readable.
+  const hasMemory = recordLike && Object.prototype.hasOwnProperty.call(value, "memory");
   // Read and dropped, never stored: see legacyRiderStateSha256. A v1 state has no digest
   // to reproduce, so here the tolerance is the whole of it.
   const hasLegacyRider = recordLike && Object.prototype.hasOwnProperty.call(value, "rider");
@@ -335,6 +346,8 @@ export function parseActiveContextState(
     ...(hasPendingMarks ? ["pendingMarks"] : []),
     ...(hasPinnedPeeks ? ["pinnedPeeks"] : []),
     ...(hasBriefs ? ["briefs"] : []),
+    ...(hasClips ? ["clips"] : []),
+    ...(hasMemory ? ["memory"] : []),
     ...(hasLegacyRider ? ["rider"] : []),
   ];
   if (!exactRecord(value, [...ACTIVE_STATE_KEYS, ...extraKeys])) throw new Error("Invalid active-context state keys");
@@ -366,6 +379,7 @@ export function parseActiveContextState(
     throw new Error("Invalid active-context pending marks");
   }
   const briefs = hasBriefs ? parseBriefOverrides(ownValue(value, "briefs"), ids) : {};
+  const clips = hasClips ? parseToolClips(ownValue(value, "clips")) : [];
   const source = clone(value) as unknown as ActiveContextState;
   return {
     version: 1,
@@ -380,6 +394,7 @@ export function parseActiveContextState(
     leases,
     ...(marks.length ? { pendingMarks: marks } : {}),
     ...(Object.keys(briefs).length ? { briefs } : {}),
+    ...(clips.length ? { clips } : {}),
     ...(hasAdvisory
       ? { advisory: clone(source.advisory!) }
       : defaultAdvisory ? { advisory: { highWater: 0, delivered: {} } } : {}),
@@ -387,6 +402,23 @@ export function parseActiveContextState(
   };
 }
 
+function parseToolClips(value: unknown): ToolClip[] {
+  const entries = denseOwnArrayValues(value);
+  if (!entries) throw new Error("Invalid active-context clips");
+  const clips = entries.map((entry) => {
+    if (!exactRecord(entry, ["callId", "entryId"]) ||
+        typeof ownValue(entry, "callId") !== "string" || !ownValue(entry, "callId") ||
+        typeof ownValue(entry, "entryId") !== "string" || !ownValue(entry, "entryId")) {
+      throw new Error("Invalid active-context clip entry");
+    }
+    return { callId: String(ownValue(entry, "callId")), entryId: String(ownValue(entry, "entryId")) };
+  });
+  if (new Set(clips.map((clip) => clip.callId)).size !== clips.length) {
+    throw new Error("Invalid active-context clips: duplicate call id");
+  }
+  return clips;
+}
+
 export function clearPrepared(state: ActiveContextState): ActiveContextState {
   const next = { ...state };
   delete next.prepared;
@@ -412,8 +444,24 @@ export function validatePreparedShape(value: unknown): asserts value is Prepared
   }
 }
 
+// THE SPREAD IS THE COPY (2026-08-28). Roughly six calls per fold per persist, and only
+// `deriveFoldParents` wants a record it can write to, where it writes the TOP-LEVEL
+// `parentId` that the spread already gives it a fresh slot for. Every other caller hashes
+// and discards: `foldRecordRef`, `sameFoldRecordIdentity`, and `makeFoldRecordEntry`, whose
+// `parseFoldRecordEntry` deep-clones twice on its own.
+//
+// The digest cannot move. `safeJson` emits in `Reflect.ownKeys` order, a spread preserves
+// insertion order, and overwriting an existing key keeps it in its original position, so
+// `{ ...fold, parentId: null }` serializes to the same bytes as the cloned form.
+//
+// THE COST, STATED BECAUSE IT IS NOW LOAD-BEARING: the returned record shares every nested
+// object with its input, so "no caller mutates a canonical record's nested fields" is a rule
+// this function relies on rather than enforces. It holds today (`validateFoldForest` clones
+// at :281, `parseFoldRecordEntry` twice at :567-568, the hashing callers never write), and a
+// future caller that writes through `record.parts` would corrupt the fold it was built from.
+// Write `{ ...record, field: value }` rather than assigning into a nested one.
 export function canonicalFoldRecord(fold: ActiveFold): ActiveFold {
-  return { ...clone(fold), parentId: null };
+  return { ...fold, parentId: null };
 }
 
 export function sameFoldRecordIdentity(left: ActiveFold, right: ActiveFold): boolean {
@@ -475,11 +523,17 @@ export function legacyReplayOrderStateSha256(state: ActiveContextState): string
 
 export function sameStateProjection(left: ActiveContextState, right: ActiveContextState): boolean {
   const normalized = (value: ActiveContextState): Partial<ActiveContextState> => {
-    const normalizedState = { ...clone(value), revision: 0 } as Partial<ActiveContextState>;
+    // A SHALLOW COPY IS ENOUGH TO DELETE TOP-LEVEL KEYS (2026-08-28). `delete` on a shallow
+    // copy cannot reach the original, the normalized object never escapes this function, and
+    // the runtime already stableStringifies live un-cloned state (`semanticStateSha256`), so
+    // un-cloned state is already required to be serializer-safe. Measured 97.6ms to 82.6ms
+    // on the largest real state in the corpus, at about two calls per provider request.
+    const normalizedState = { ...value, revision: 0 } as Partial<ActiveContextState>;
     if (normalizedState.tokensSinceToolFold === 0) delete normalizedState.tokensSinceToolFold;
     if (normalizedState.leases && Object.keys(normalizedState.leases).length === 0) delete normalizedState.leases;
     if (normalizedState.pendingMarks && normalizedState.pendingMarks.length === 0) delete normalizedState.pendingMarks;
     if (normalizedState.briefs && !Object.keys(normalizedState.briefs).length) delete normalizedState.briefs;
+    if (normalizedState.clips && normalizedState.clips.length === 0) delete normalizedState.clips;
     return normalizedState;
   };
   return stableStringify(normalized(left)) === stableStringify(normalized(right));
@@ -586,6 +640,14 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
     Object.prototype.hasOwnProperty.call(value, "addBriefs"));
   const hasRemoveBriefIds = Boolean(value && typeof value === "object" &&
     Object.prototype.hasOwnProperty.call(value, "removeBriefIds"));
+  const hasWireClips = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "clips"));
+  const hasClipBase = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "clipBase"));
+  const hasAddClips = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "addClips"));
+  const hasWireMemory = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "memory"));
   const hasLegacyRider = Boolean(value && typeof value === "object" &&
     Object.prototype.hasOwnProperty.call(value, "rider"));
   refuseRetiredStateFields(value);
@@ -600,6 +662,10 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
     ...(hasBriefs ? ["briefs"] : []),
     ...(hasAddBriefs ? ["addBriefs"] : []),
     ...(hasRemoveBriefIds ? ["removeBriefIds"] : []),
+    ...(hasWireClips ? ["clips"] : []),
+    ...(hasClipBase ? ["clipBase"] : []),
+    ...(hasAddClips ? ["addClips"] : []),
+    ...(hasWireMemory ? ["memory"] : []),
     // Carried no further than the digest check in `materializeStatePersistence`, which is
     // the only thing on a load that the rider's absence can change.
     ...(hasLegacyRider ? ["rider"] : []),
@@ -619,6 +685,17 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
     ownValue(value, "advisory"), ownValue(value, "tokensSinceToolFold"), ownValue(value, "leases"),
     ownValue(value, "pendingMarks"), ownValue(value, "briefs"),
   );
+  if (hasWireClips) parseToolClips(ownValue(value, "clips"));
+  if (hasAddClips) parseToolClips(ownValue(value, "addClips"));
+  if (hasClipBase) {
+    const base = ownValue(value, "clipBase");
+    if (!Number.isSafeInteger(base) || Number(base) < 0) throw new Error("Invalid active-context clip base");
+  }
+  // A whole array and a change cannot both be the truth on one wire.
+  if (hasWireClips && (hasClipBase || hasAddClips)) {
+    throw new Error("Invalid active-context clips: whole array beside a change");
+  }
+  if (hasAddClips && !hasClipBase) throw new Error("Invalid active-context clips: change without a base");
   if (checkpoint) {
     const refs = denseOwnArrayValues(ownValue(value, "foldRefs"));
     if (!refs || refs.length > MAX_ACTIVE_FOLD_RECORDS) throw new Error("Invalid active-context checkpoint refs");
@@ -693,7 +770,25 @@ export function normalizeFoldsForPersistedRecords(
   return deriveFoldParents(normalized);
 }
 
-export function deriveFoldParents(records: ActiveFold[]): ActiveFold[] {
+/**
+ * Rebuild the parent links a fold forest's records do not carry.
+ *
+ * THIS DOES NOT VALIDATE THE FOREST, and the split is deliberate. `validateFoldForest` deep
+ * clones the forest, recomputes `foldIdFor` per fold, and calls `flattenFoldRefs` per fold,
+ * which rebuilds `foldMap` over every fold; two of the four callers handed the result
+ * straight to `parseActiveContextState`, whose FIRST act is to validate it again. So a
+ * persist validated the same forest three times. Roughly 12ms saved at 88 folds, 28 at 178,
+ * 55 at 267, plus about 1.6x on the session-start load path.
+ *
+ * The child-record check above stays here, because it is about the ASSIGNMENT rather than
+ * the forest: a child claimed twice, or claimed by a parent that does not hold it, is a
+ * contradiction this loop is the only thing positioned to see.
+ *
+ * Callers that do not parse immediately afterwards want `deriveFoldParents` below. Reaching
+ * for this one is a claim that the very next statement validates the same array; nothing
+ * else makes it safe, and it reads at review as removing validation, which it is not.
+ */
+export function assignFoldParents(records: ActiveFold[]): ActiveFold[] {
   const folds = records.map(canonicalFoldRecord);
   const byId = new Map(folds.map((fold) => [fold.id, fold]));
   const assigned = new Set<string>();
@@ -705,14 +800,19 @@ export function deriveFoldParents(records: ActiveFold[]): ActiveFold[] {
       assigned.add(childId);
     }
   }
-  return validateFoldForest(folds);
+  return folds;
+}
+
+/** Assign the parents and validate the forest, for callers that do not parse next. */
+export function deriveFoldParents(records: ActiveFold[]): ActiveFold[] {
+  return validateFoldForest(assignFoldParents(records));
 }
 
 export function stateFromFoldRefs(
   wire: Pick<
     ActiveContextCheckpointV2,
     "sessionId" | "revision" | "expanded" | "protected" | "prepared" | "advisory" |
-      "tokensSinceToolFold" | "leases" | "pendingMarks" | "briefs"
+      "tokensSinceToolFold" | "leases" | "pendingMarks" | "briefs" | "clips"
   >,
   refs: FoldRecordRef[],
   records: Map<string, FoldRecordEntry>,
@@ -727,13 +827,16 @@ export function stateFromFoldRefs(
     version: 1,
     sessionId: wire.sessionId,
     revision: wire.revision,
-    folds: deriveFoldParents(folds),
+    // `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),
     expanded: clone(wire.expanded),
     protected: clone(wire.protected),
     tokensSinceToolFold: wire.tokensSinceToolFold ?? 0,
     leases: clone(wire.leases ?? {}),
     ...(wire.pendingMarks?.length ? { pendingMarks: clone(wire.pendingMarks) } : {}),
     ...(wire.briefs && Object.keys(wire.briefs).length ? { briefs: clone(wire.briefs) } : {}),
+    ...(wire.clips?.length ? { clips: clone(wire.clips) } : {}),
     ...(wire.advisory === undefined ? {} : { advisory: clone(wire.advisory) }),
     ...(wire.prepared === null || wire.prepared === undefined ? {} : { prepared: clone(wire.prepared) }),
   };
@@ -869,7 +972,16 @@ export function materializeStatePersistence(
           wire.revision <= wire.baseRevision) {
         throw new Error("Broken active-context delta chain");
       }
-      const refs = state.folds.map(foldRecordRef);
+      // THE RECORD MAP ALREADY HOLDS THIS DIGEST (2026-08-28). `foldRecordRef` canonicalizes
+      // and hashes a whole fold, and this ran once per delta entry over every standing fold:
+      // 48,715 calls in ONE load of a real sealed session, 2.6 to 3.7s of a 24 to 33s load.
+      // `records` is built by the same replay and carries the same digest verbatim. The
+      // fallback is unreachable, because the pre-scan raises on a delta before a checkpoint;
+      // it is kept so the change is exactly behaviour-preserving rather than nearly so.
+      const refs = state.folds.map((fold) => {
+        const record = records.get(fold.id);
+        return record ? { id: fold.id, sha256: record.recordSha256 } : foldRecordRef(fold);
+      });
       const byId = new Map(refs.map((ref) => [ref.id, ref]));
       for (const id of wire.removeFoldIds) {
         if (!byId.delete(id)) throw new Error(`Unknown active-context delta removal ${id}`);
@@ -925,11 +1037,25 @@ export function materializeStatePersistence(
           return mark;
         });
       }
+      // The clips replay by the same discriminator rule as the briefs and the marks: the
+      // presence of the CHANGE is what says a wire carries one. A delta written before
+      // 2026-08-24 states the whole array when it has one and states nothing when it does
+      // not, so "no array" means "no clips" there, exactly as it does for the marks.
+      const clips = wire.clipBase === undefined
+        ? (wire.clips !== undefined ? clone(wire.clips) : [])
+        : [...(state.clips ?? []).slice(0, wire.clipBase), ...clone(wire.addClips ?? [])];
+      if (wire.clipBase !== undefined && wire.clipBase > (state.clips ?? []).length) {
+        throw new Error(`Unknown active-context clip base ${wire.clipBase}`);
+      }
+      if (new Set(clips.map((clip) => clip.callId)).size !== clips.length) {
+        throw new Error("Invalid active-context clips: duplicate call id");
+      }
       state = stateFromFoldRefs(
         {
           ...wire,
           briefs: Object.keys(briefs).length ? briefs : undefined,
           pendingMarks: marks.length ? marks : undefined,
+          clips: clips.length ? clips : undefined,
         },
         [...byId.values()],
         records,
@@ -989,6 +1115,7 @@ export function makeStateCheckpoint(state: ActiveContextState): ActiveContextChe
     leases: clone(state.leases),
     ...(state.pendingMarks?.length ? { pendingMarks: clone(state.pendingMarks) } : {}),
     ...(state.briefs && Object.keys(state.briefs).length ? { briefs: clone(state.briefs) } : {}),
+    ...(state.clips?.length ? { clips: clone(state.clips) } : {}),
     ...(state.advisory ? { advisory: clone(state.advisory) } : {}),
     stateSha256: semanticStateSha256(state),
   }, state.sessionId) as ActiveContextCheckpointV2;
@@ -1036,6 +1163,23 @@ export function makeStateDelta(previous: ActiveContextState, next: ActiveContext
     return !held || sha256Value(held) !== sha256Value(mark);
   });
   const marksTravel = previousMarks.length > 0 || nextMarks.length > 0;
+  // THE CLIPS ARE THE SAME RULE A THIRD TIME (2026-08-24). They shipped whole on every
+  // delta, which was 50.1 percent of all state bytes on sol-20260823-live rep 11, 472,750
+  // of 942,902, for an array that never held more than 34 entries: the same defect the two
+  // comments above were written about, arriving with a feature that did not inherit their
+  // encoding. Clips are APPENDED and never edited, so the change is a count of what the
+  // base already holds plus the ones that are new, and a rollback that shortens the array
+  // states a lower count. The marks' order list would be worse than the bug here: a callId
+  // is about a hundred characters, so re-listing them all on every delta costs more than
+  // the array it replaces.
+  const previousClips = previous.clips ?? [];
+  const nextClips = next.clips ?? [];
+  let clipBase = 0;
+  while (clipBase < previousClips.length && clipBase < nextClips.length &&
+    previousClips[clipBase].callId === nextClips[clipBase].callId &&
+    previousClips[clipBase].entryId === nextClips[clipBase].entryId) clipBase += 1;
+  const addClips = nextClips.slice(clipBase);
+  const clipsTravel = previousClips.length > 0 || nextClips.length > 0;
   // The rest travel whole and stay that way. Measured on the same run, the two that were
   // worth a diff were 20.0 MB of the 21.6 MB ledger; what remained were bounded objects
   // with their own caps rather than collections that grow with the epoch (the largest,
@@ -1061,13 +1205,41 @@ export function makeStateDelta(previous: ActiveContextState, next: ActiveContext
     ...(addPendingMarks.length ? { addPendingMarks: clone(addPendingMarks) } : {}),
     ...(Object.keys(addBriefs).length ? { addBriefs } : {}),
     ...(removeBriefIds.length ? { removeBriefIds } : {}),
+    ...(clipsTravel ? { clipBase: clipBase, ...(addClips.length ? { addClips: clone(addClips) } : {}) } : {}),
     ...(next.advisory ? { advisory: clone(next.advisory) } : {}),
     stateSha256: semanticStateSha256(next),
   }, next.sessionId) as ActiveContextDeltaV2;
 }
 
+// THE FOREST IS HASHED ONCE PER STATE OBJECT (2026-08-28). Nine call-site pairs reach this,
+// and the one that scales is the per-mark loop in `commitPendingMarks`: `prepareFold` hashes
+// `state`, and the `commitPreparedFold` on the very next statement re-hashes the SAME object
+// through `preparedFoldError`. So every applied mark paid one avoidable whole-forest hash,
+// and `state` grows by a fold each iteration, making a commit epoch O(marks x folds).
+// Instrumented across the suite: 6,363 calls, 63.8 percent of them repeats on an object
+// already hashed, peaking at 198 in a single context event.
+//
+// It is gate 113's rule, gate 120's and gate 121's, at a fourth address: kept against the
+// state OBJECT rather than its contents, because state is REPLACED on every change rather
+// than mutated, so a replaced one misses and hashes again instead of serving something
+// stale. Every transition in the runtime is a spread; nothing writes `state.folds`,
+// `state.expanded` or a fold in place.
+//
+// The accepted cost, which is the same one gate 121 accepted: a state mutated in place keeps
+// its first digest, and this digest is persisted into `PreparedFold.topologySha256`.
+//
+// NOT memoized beside it: `protectionSha256`, measured at 0.037 to 0.061ms on real states
+// because `state.protected` is empty in every sealed run, so a memo there buys about 3
+// percent and adds a second retained map for nothing.
+const TOPOLOGY_SHA256 = new WeakMap<object, string>();
+
 export function topologySha256(state: Pick<ActiveContextState, "folds" | "expanded">): string {
-  return sha256Value({ folds: state.folds, expanded: [...state.expanded].sort() });
+  const key = state as unknown as object;
+  const memoized = TOPOLOGY_SHA256.get(key);
+  if (memoized !== undefined) return memoized;
+  const digest = sha256Value({ folds: state.folds, expanded: [...state.expanded].sort() });
+  TOPOLOGY_SHA256.set(key, digest);
+  return digest;
 }
 
 export function protectionSha256(state: Pick<ActiveContextState, "protected">): string {

package/extensions/lib/policy.ts

@@ -108,6 +108,16 @@ export const COMMIT_RECLAIM_FLOOR_SHARE = 0.02;
  */
 export const MAX_PINNED_SHARE = 0.25;
 
+/**
+ * THE TOOL-CALL DIET's default share (Shane 2026-08-28, on the sol-20260826-full2
+ * verdict). Every fold repetition from 3 onward ran 0.50 and the campaign's headline
+ * results are all from that shape, so the shipped default is the measured value rather
+ * than the absence of one. A deployment turns the diet off with an explicit 0, which is
+ * why the option's range is [0, 1) instead of the open interval it shipped with: one
+ * meaning per value, and no absent-means-off special case.
+ */
+export const DEFAULT_TOOL_FOLD_THRESHOLD = 0.50;
+
 export interface ActiveContextThresholds {
   maxTarget: number;
   minTarget: number;
@@ -141,9 +151,10 @@ export const MINIMUM_FOLD_CHARS_FLOOR = 2_000;
 
 export const DEFAULT_THRESHOLDS: Readonly<ActiveContextThresholds> = Object.freeze({
   maxTarget: 0.80,
-  // 0.40, up from 0.20 (Shane 2026-08-23: "we change the thresholds to what hits that
-  // 100k/250k or so"). This is the only threshold that moved, because the corpus says
-  // the top of the band was already where he wants it and only the floor was wrong.
+  // 0.20 (Shane 2026-08-28, on the sol-20260826-full2 verdict). This number went 0.20 ->
+  // 0.40 on 2026-08-23 and came back on the campaign that was still running when it
+  // moved, so both readings are recorded here rather than one quietly replacing the
+  // other. The top of the band is not in question and never was.
   //
   // Read against the 19 mature sealed pifold runs that share a 251,520-token budget,
   // where the trigger sat at 0.80 of it, 201,216 tokens. Peak occupancy per run came in
@@ -153,26 +164,28 @@ export const DEFAULT_THRESHOLDS: Readonly<ActiveContextThresholds> = Object.free
   // So 0.80 already delivers a 250k top, and raising it toward 250k directly would put
   // the median peak over the budget and into the fence.
   //
-  // The floor was the miss. Across 206 commit landings the session came to rest at a
-  // median 79,034 tokens, and 153 of the 206 landed below 100,000. Landings sit ABOVE
-  // the aim rather than at it, since the class law and the available material both
-  // outrank it, so moving the aim to 0.40 sets a floor near where it lands rather than
-  // far under it: 102,246 tokens against a default 272,000-token descriptor, 100,608
-  // against the harness budget.
+  // The 2026-08-23 case for 0.40 was that it seats the floor near where commits actually
+  // land: across 206 commit landings the session came to rest at a median 79,034 tokens,
+  // 153 of the 206 below 100,000, and landings sit ABOVE the aim rather than at it, since
+  // the class law and the available material both outrank it. That was bought knowing the
+  // price, about a fifth more epochs and so a fifth more full-prefix rewrites, to hold
+  // 100k of raw context across the whole cycle.
   //
-  // 0.40 also makes the aim reachable for the first time. MAX_PINNED_SHARE is 0.25, so a
-  // fully pinned session legally holds more than a 0.20 aim asks for and the target was
-  // a number the class law outranked by construction. The epoch receipt still reports
-  // targetBudgetShare beside actualFreedBudgetShare, so any remaining shortfall stays a
-  // readable fact per epoch rather than a silent miss.
+  // The campaign priced the trade and it went the other way. The commit rewrite tax is
+  // minTarget / (maxTarget - minTarget), because every commit re-reads roughly
+  // minTarget x budget of prefix uncached and a shallower cut buys less runway for nearly
+  // the same bill: 1.0 at 0.80/0.40 against 0.33 at 0.80/0.20. Every sol-20260826-full2
+  // fold repetition from 3 onward ran 0.80/0.20, including the fold-plus-canon rep 5 that
+  // answered 14 of 16 with nothing wrong at $100.85 against native-plus-canon's $201.70.
+  // The shipped default is now the configuration that was measured.
   //
-  // The cost is paid in cadence and it is the 2026-08-14 argument running backwards: a
-  // shallower cut buys less runway for nearly the same commit, so the refill distance
-  // goes from the observed 0.314 -> 0.80 to 0.40 -> 0.80 and the same session shape owes
-  // about a fifth more epochs, which is a fifth more full-prefix rewrites. Shane bought
-  // that deliberately: 100k of raw context held across the whole cycle is what he is
-  // paying for. The validation laws below bind exactly as before.
-  minTarget: 0.40,
+  // THE KNOWN LIMIT, unchanged and still true: MAX_PINNED_SHARE is 0.25, so a fully
+  // pinned session legally holds more than a 0.20 aim asks for, and there the commit
+  // stops short of its target by construction rather than by fault. The epoch receipt
+  // reports targetBudgetShare beside actualFreedBudgetShare, so the shortfall stays a
+  // readable fact per epoch rather than a silent miss. The validation laws below bind
+  // exactly as before.
+  minTarget: 0.20,
   consolidateAfter: 10,
   minFoldChars: 8_000,
 });
@@ -241,11 +254,6 @@ export function assertThresholdsServable(_thresholds: ActiveContextThresholds, b
   }
 }
 
-export function zoneBytes(share: number, budgetTokens: number): number {
-  if (!Number.isFinite(share) || share <= 0 || !Number.isFinite(budgetTokens) || budgetTokens <= 0) return 0;
-  return Math.floor(share * budgetTokens * ESTIMATED_BYTES_PER_TOKEN);
-}
-
 export function servingBudgetTokens(window: number): number {
   const resolved = Number.isFinite(window) && window > 0 ? window : DEFAULT_CONTEXT_WINDOW;
   return resolved - Math.min(ACTIVE_CONTEXT_POLICY.responseReserve, Math.floor(resolved * 0.1));
@@ -253,6 +261,22 @@ export function servingBudgetTokens(window: number): number {
 
 export const MAX_PENDING_MARKS = 256;
 export const ESTIMATED_BYTES_PER_TOKEN = 4;
+
+/**
+ * What one image in the window is worth, in tokens, for estimation only.
+ *
+ * A provider prices an image from its DIMENSIONS, not its byte size: Anthropic bills
+ * about width x height / 750, which puts a 2000x563 screenshot near 1,500 tokens, and a
+ * large image caps close to this number once the long edge is scaled to the 1568px limit.
+ * The exact figure differs per provider and cannot be known from the base64 alone.
+ *
+ * It does not need to be exact. The value it replaces was the image's base64 length
+ * divided by a prose chars-per-token ratio, which read one screenshot as 110,000 tokens
+ * against a true cost near 1,500. Being within an order of magnitude ends the failure;
+ * the provider anchor corrects the rest as soon as a real measurement lands. A constant
+ * rather than an option, because nobody can tune this better than the anchor can.
+ */
+export const IMAGE_ESTIMATED_TOKENS = 1_600;
 export const ESTIMATED_PLACEHOLDER_OVERHEAD_BYTES = 240;
 
 export const PEEK_MIN_SLICE_BYTES = 1_024;
@@ -271,7 +295,7 @@ export const CONTEXT_RECEIPT_BLOCK_BYTES = 900;
  * agent answers. 1,200 seats the instruction and roughly eight folds; past that the list
  * gives way and states how many it could not name.
  */
-export const FOLD_NOTICE_BYTES = 1_200;
+export const FOLD_NOTICE_BYTES = 2_400;
 export const CONTEXT_STATUS_RESPONSE_BYTES = 24_000;
 export const MAX_UNMARKED_CANDIDATES = 3;
 
@@ -298,7 +322,7 @@ export function peekIsEphemeral(params: Record<string, unknown> | undefined | nu
   return params?.ephemeral !== false;
 }
 
-export const PEEK_READ_ONLY_CONTEXT_ACTIONS: ReadonlySet<string> = new Set(["status", "peek"]);
+export const PEEK_READ_ONLY_CONTEXT_ACTIONS: ReadonlySet<string> = new Set(["status", "peek", "recall"]);
 
 /** "user" is a mark laid down by the human through /fold-editor; it stages and
  *  commits through the same validated path as an agent mark and counts toward the
@@ -334,16 +358,32 @@ export const ACTIVE_CONTEXT_POLICY = Object.freeze({
   // clamps its `bytes` to it. Was two numbers until 2026-08-22, when the peek ceiling
   // was `maxChapterChars` 128,000 and that constant also claimed to cap a chapter.
   maxSourceChars: 200_000,
+  // THE TOOL-CALL DIET (2026-08-24): at COMMIT TIME ONLY, a stale tool result inside
+  // the configured toolFoldThreshold share of the projected window is clipped IN VIEW
+  // to an identified head, the full bytes staying peek-recoverable behind its entry id.
+  // The head keeps the leading paragraph up to its cap (gate 134's rule); results at or
+  // under the floor stay whole, because clipping a small result buys almost nothing and
+  // adds a peek indirection. Constants, not options, for v1: the share point is the one
+  // public knob.
+  toolClipHeadChars: 500,
+  toolClipFloorChars: 2_000,
   maxBriefChars: 2_000,
+  // The agent's share of maxBriefChars when a supplied brief augments the deterministic
+  // head (sol-20260823-live rep 7: supplied briefs REPLACED the fact-carrying head and
+  // 74 of 95 peeks recovered values the run's own briefs dropped). The head keeps the
+  // remainder, so identification can never be displaced by a long agent clause.
+  agentBriefReserve: 600,
   orientationMessages: 2,
   maxOrientationChars: 12_000,
 });
 
 export type FoldKind = "tool-result" | "chapter" | "consolidation";
+export type ToolClip = { callId: string; entryId: string };
 export type FoldPart = { kind: "raw"; ref: EvidenceRef } | { kind: "fold"; foldId: string };
 export type BriefProvenance =
   | { kind: "supplied" }
   | { kind: "deterministic" }
+  | { kind: "augmented" }
   | {
       kind: "model" | "luna";
       provider: string;
@@ -395,6 +435,7 @@ export interface ActiveContextState {
   pendingMarks?: PendingMark[];
   pinnedPeeks?: never;
   briefs?: Record<string, BriefOverride>;
+  clips?: ToolClip[];
   prepared?: PreparedFold;
   advisory?: {
     highWater: number;
@@ -430,6 +471,7 @@ export interface ActiveContextCheckpointV2 {
   leases?: Record<string, number>;
   pendingMarks?: PendingMark[];
   briefs?: Record<string, BriefOverride>;
+  clips?: ToolClip[];
   advisory?: NonNullable<ActiveContextState["advisory"]>;
   rider?: NonNullable<ActiveContextState["rider"]>;
   lastCall?: NonNullable<ActiveContextState["lastCall"]>;
@@ -461,6 +503,16 @@ export interface ActiveContextDeltaV2 {
   briefs?: Record<string, BriefOverride>;
   addBriefs?: Record<string, BriefOverride>;
   removeBriefIds?: string[];
+  // `clips` on a delta is the WHOLE array: what every delta written before 2026-08-24
+  // carries, and what sealed sessions replay. New deltas carry the change instead. Clips
+  // are appended and never edited, so the change is a count of what the base already holds
+  // plus the ones that are new; a rollback that shortens the array states a lower count.
+  // The order list the marks use would be WORSE than the bug here, because a callId is
+  // about a hundred characters and re-listing thirty of them on every delta costs more
+  // than the array it replaces.
+  clips?: ToolClip[];
+  clipBase?: number;
+  addClips?: ToolClip[];
   advisory?: NonNullable<ActiveContextState["advisory"]>;
   rider?: NonNullable<ActiveContextState["rider"]>;
   lastCall?: NonNullable<ActiveContextState["lastCall"]>;