pi-fold 2.0.0 → 3.1.0

package/extensions/lib/policy.ts

@@ -5,8 +5,8 @@ export const DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX = "pi-fold-active-context"
 export const DEFAULT_ACTIVE_CONTEXT_TOOL_LABEL = "pi-fold Active Context";
 export const DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN = "pi-fold";
 export const DEFAULT_ACTIVE_CONTEXT_COMMAND_NAMES = Object.freeze({
-  status: "pi-fold-context",
-  fold: "fold-context",
+  status: "fold-status",
+  fold: "fold",
 });
 
 export function entryTypeNamespace(entryTypePrefix: string): string {
@@ -33,11 +33,67 @@ const DEFAULT_ENTRY_NAMESPACE = entryTypeNamespace(DEFAULT_ACTIVE_CONTEXT_ENTRY_
 export const ACTIVE_CONTEXT_STATE_ENTRY = `${DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX}-state`;
 export const ACTIVE_CONTEXT_FOLD_RECORD_ENTRY = `${DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX}-fold-record`;
 export const PROVIDER_CONTEXT_MEASUREMENT_ENTRY = `${DEFAULT_ENTRY_NAMESPACE}-provider-context-measurement`;
+/**
+ * How many unbriefed pending folds stand before the runtime says so.
+ *
+ * A CONSTANT, not a threshold the deployment can turn (Shane's KISS rule): it is a
+ * batching size, and the only thing a knob here would buy is a deployment that never
+ * speaks. Three is the smallest batch that reads as a batch rather than as a running
+ * commentary on every cut.
+ */
+export const UNBRIEFED_FOLDS_BEFORE_NOTICE = 3;
+
+/**
+ * How many spans the frontier cuts on one projection pass.
+ *
+ * A CONSTANT, and a cost bound rather than a policy. Each cut rescans the window for the
+ * next stalest span, so an unbounded loop is quadratic in the number of spans a window
+ * holds: on a 300-turn fixture it took a gate from 2.5 seconds to 152. A frontier does not
+ * need to catch up in one pass, because a pass costs nothing to repeat and the material it
+ * has not reached yet is still raw and still in front of the agent, which is where the
+ * design wants it. Eight is comfortably ahead of any real arrival rate.
+ */
+export const MAX_FRONTIER_CUTS_PER_PASS = 8;
+
 export const ACTIVE_CONTEXT_TOOL_ACTIONS = Object.freeze([
-  "status", "peek", "fold", "expand", "refold", "protect", "unprotect",
-  "rebrief", "reboundary", "unmark",
+  "status", "peek", "brief", "expand", "refold", "pin", "unpin",
+  "reboundary", "unmark",
 ] as const);
-export type ActiveContextToolAction = typeof ACTIVE_CONTEXT_TOOL_ACTIONS[number];
+/**
+ * FOLD IS DELETED AS AN AGENT VERB (Shane, 2026-08-23), and `brief` is what replaced it.
+ *
+ * The agent used to choose spans from nothing. Measured against real compaction
+ * boundaries on 2026-08-23, that produced a projection byte-identical to the same arm
+ * with no agent at all: six marks, 9,450 characters of briefs, same visible count, same
+ * fold count, same aborts. It marks what the ladder would have taken anyway, because at
+ * the moment it is asked the only information available is staleness and the runtime
+ * already has that.
+ *
+ * So the runtime cuts at the frontier and the agent annotates what it cut, while the
+ * material is still in front of it. `brief` attaches or replaces the brief on a PENDING
+ * fold and refuses on a standing one, which is the rebrief deletion above read from the
+ * other side: a pending mark is not in the window, so writing its brief moves no bytes
+ * and costs no cache, and a standing fold's placeholder is in the window, so writing that
+ * one costs the whole prefix from there on. The name `fold` stays spent.
+ */
+/**
+ * REBRIEF IS DELETED (Shane, 2026-08-21). Every rebrief rewrites the projection at its
+ * fold's placeholder, which breaks the prefix cache from that point on: sol-20260820
+ * rep 7's first rebrief hit a front-of-projection fold, identical_share collapsed to
+ * 0.0007, and nine ~185K-token requests ran cacheRead 0 for $8.36 in one burst. The
+ * end block read 10 of 10 in every pifold rep with or without rebriefs, because
+ * lossless peek already carries recall, so the action was paying a full cache break
+ * for something the runtime did not need. The name stays spent.
+ */
+export const RETIRED_TOOL_ACTIONS: Readonly<Record<string, string>> = Object.freeze({
+  rebrief: "rebrief is deleted: rewriting a standing fold's brief rewrites the projection " +
+    "at that fold's placeholder and breaks the prefix cache from there on, for recall that " +
+    "peek already carries losslessly. Write the brief you want when you mark the span, or " +
+    "use reboundary to re-cut it.",
+});
+export type ActiveContextToolAction =
+  | typeof ACTIVE_CONTEXT_TOOL_ACTIONS[number]
+  | typeof WORKING_MEMORY_TOOL_ACTIONS[number];
 export const USER_RESCUE_MAX_SOURCE_CHARS = 512_000;
 export const DEFAULT_CONTEXT_WINDOW = 272_000;
 export const EXPAND_LEASE_GENERATIONS = 8;
@@ -45,38 +101,99 @@ export const MAX_EXPAND_LEASES = 64;
 
 export const COMMIT_RECLAIM_FLOOR_SHARE = 0.02;
 
+/**
+ * How far below the commit trigger the agent is told a commit is coming (Shane,
+ * 2026-08-22: "around 10% from the commit threshold"). A share of the serving budget
+ * rather than a token count, because a token count means a different fraction of every
+ * deployment's window. The advisory takes the wider of this and one worst recent inflow
+ * step, so a single large result cannot step over the whole band unasked.
+ */
 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;
-  freshTail: number;
   consolidateAfter: number;
+  minFoldChars: number;
 }
 
+/**
+ * The floor a fold has to clear to be worth making, in CHARACTERS (Shane, 2026-08-21).
+ *
+ * Characters rather than tokens because characters are provider-agnostic: a token count
+ * means a different amount of text on every wire, and this number exists so a person can
+ * reason about it. It replaces two constants nobody could tell apart, minToolChars at
+ * 2,000 and minChapterChars at 4,000, and it is not specific to tool results or to
+ * chapters: everything in the window costs tokens, so everything counts toward the floor.
+ *
+ * It is a floor, not a cut. The automatic span accumulates whole messages and stops at
+ * the first one that carries it OVER the floor, so a fold is always at least this big
+ * and never cuts a message in half to hit the number exactly. The same floor is what a
+ * gap between two folds has to clear to survive: anything smaller is absorbed by the
+ * fold beside it rather than left as a raw sliver, because a sliver costs its bytes and
+ * buys nothing.
+ *
+ * 8,000 was chosen against the sealed corpus. Rep 1 of sol-20260814-traps folded 89
+ * spans at a median of 57,808 source chars, but nine of them came in under 8,000 and
+ * TWO were net negative, 2,726 chars of source replaced by 5,341 of placeholder (196
+ * percent) and 6,384 replaced by 10,531 (165 percent). A fold that grows the window is
+ * not a fold. The floor sits above every observed inversion with room to spare.
+ */
+export const MINIMUM_FOLD_CHARS_FLOOR = 2_000;
+
 export const DEFAULT_THRESHOLDS: Readonly<ActiveContextThresholds> = Object.freeze({
   maxTarget: 0.80,
-  // 0.20, down from 0.35 (Shane 2026-08-14). The cut depth is what sets the epoch
-  // cadence: every commit rewrites the prefix from the earliest folded byte, so the
-  // cost of an epoch is nearly flat in how deep it cuts, while the relief it buys is
-  // the whole distance to the trigger. sol-20260814-traps rep 1 ran six commits, each
-  // freeing to 0.35 and refilling in two to three stages; at 0.20 the same run shape
-  // owes roughly a quarter fewer epochs, which is a quarter fewer full-prefix
-  // rewrites, the dominant self-inflicted cache break. The floor is a target the
-  // class law outranks, not a guarantee: a session pinned to the 0.25 ceiling
-  // beside the 0.02 fresh tail legally holds 0.27 and lands above this number,
-  // and the epoch receipt reports targetBudgetShare beside actualFreedBudgetShare
-  // so the shortfall is a readable fact per epoch rather than a silent miss. The
-  // validation laws below bind exactly as before.
+  // 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
+  // at a median 237,399, a 0.944 share, p90 247,551, max 257,117: a session runs roughly
+  // 36,000 tokens PAST its own trigger before the commit it fired takes effect, because
+  // the trigger fires at a measurement and inflow continues while the epoch is computed.
+  // 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 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.
+  //
+  // 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 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,
-  freshTail: 0.02,
   consolidateAfter: 10,
+  minFoldChars: 8_000,
 });
 
 export const MINIMUM_SUPPORTED_BUDGET_TOKENS = 10_000;
 
-export const MINIMUM_FRESH_TAIL_TOKENS = 500;
-
 export class ThresholdPolicyError extends Error {
   readonly invariant: string;
   constructor(invariant: string, message: string) {
@@ -99,7 +216,7 @@ export function resolveThresholds(value: unknown): ActiveContextThresholds {
     throw new ThresholdPolicyError("shape", "thresholds must be an object with all four fields");
   }
   const supplied = value as Record<string, unknown>;
-  const fields = ["maxTarget", "minTarget", "freshTail", "consolidateAfter"] as const;
+  const fields = ["maxTarget", "minTarget", "consolidateAfter", "minFoldChars"] as const;
   for (const key of Object.keys(supplied)) {
     if (!(fields as readonly string[]).includes(key)) {
       throw new ThresholdPolicyError("shape", `thresholds has no ${key} field`);
@@ -112,51 +229,31 @@ export function resolveThresholds(value: unknown): ActiveContextThresholds {
   }
   const maxTarget = thresholdProportion(supplied.maxTarget, "maxTarget");
   const minTarget = thresholdProportion(supplied.minTarget, "minTarget");
-  const freshTail = thresholdProportion(supplied.freshTail, "freshTail");
   const consolidateAfter = supplied.consolidateAfter;
   if (typeof consolidateAfter !== "number" || !Number.isInteger(consolidateAfter) || consolidateAfter < 1) {
     throw new ThresholdPolicyError("consolidateAfter", "thresholds.consolidateAfter must be a positive integer count");
   }
+  const minFoldChars = supplied.minFoldChars;
+  if (typeof minFoldChars !== "number" || !Number.isInteger(minFoldChars) ||
+      minFoldChars < MINIMUM_FOLD_CHARS_FLOOR) {
+    throw new ThresholdPolicyError("minFoldChars",
+      "thresholds.minFoldChars must be an integer character count of at least " +
+      `${MINIMUM_FOLD_CHARS_FLOOR}; below that a fold can cost more placeholder than the ` +
+      "source it replaces");
+  }
   if (!(minTarget < maxTarget)) {
     throw new ThresholdPolicyError("minTarget<maxTarget",
       "thresholds.minTarget must sit below thresholds.maxTarget, or a commit has no depth to reach");
   }
-  if (!(freshTail < maxTarget)) {
-    throw new ThresholdPolicyError("freshTail<maxTarget",
-      "thresholds.freshTail must sit below thresholds.maxTarget, or the trigger fires on protected mass alone");
-  }
-  if (!(maxTarget - minTarget >= freshTail)) {
-    throw new ThresholdPolicyError("gap>=freshTail",
-      "the hysteresis gap (maxTarget - minTarget) must be at least thresholds.freshTail, " +
-      "or refilling the protected tail alone re-fires the trigger");
-  }
-  const pinned = Math.ceil(MAX_PINNED_SHARE * MINIMUM_SUPPORTED_BUDGET_TOKENS);
-  const fresh = Math.ceil(freshTail * MINIMUM_SUPPORTED_BUDGET_TOKENS);
-  if (!(pinned + fresh < Math.floor(maxTarget * MINIMUM_SUPPORTED_BUDGET_TOKENS))) {
-    throw new ThresholdPolicyError("pinnedPlusFreshTail<maxTarget",
-      `the pin ceiling (${MAX_PINNED_SHARE}) plus thresholds.freshTail must stay below ` +
-      `thresholds.maxTarget at the ${MINIMUM_SUPPORTED_BUDGET_TOKENS}-token minimum supported budget`);
-  }
-  return { maxTarget, minTarget, freshTail, consolidateAfter };
+  return { maxTarget, minTarget, consolidateAfter, minFoldChars };
 }
 
-export function assertThresholdsServable(thresholds: ActiveContextThresholds, budgetTokens: number): void {
+export function assertThresholdsServable(_thresholds: ActiveContextThresholds, budgetTokens: number): void {
   if (!Number.isFinite(budgetTokens) || budgetTokens < MINIMUM_SUPPORTED_BUDGET_TOKENS) {
     throw new ThresholdPolicyError("minimumBudget",
       `a ${Math.floor(budgetTokens)}-token serving budget is below the ` +
       `${MINIMUM_SUPPORTED_BUDGET_TOKENS}-token minimum this package supports`);
   }
-  const freshTokens = Math.floor(thresholds.freshTail * budgetTokens);
-  if (freshTokens < MINIMUM_FRESH_TAIL_TOKENS) {
-    throw new ThresholdPolicyError("freshTailTokens",
-      `thresholds.freshTail is ${freshTokens} tokens of a ${Math.floor(budgetTokens)}-token serving budget, ` +
-      `below the ${MINIMUM_FRESH_TAIL_TOKENS}-token minimum one foldable unit needs`);
-  }
-}
-
-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 {
@@ -172,54 +269,79 @@ export const PEEK_MIN_SLICE_BYTES = 1_024;
 
 export const STATUS_DIET_INDEX_ROWS = 5;
 
-export interface ActiveContextGuidance {
-  actionResponses: boolean;
-}
-
-export const DEFAULT_GUIDANCE: ActiveContextGuidance = Object.freeze({
-  actionResponses: true,
-});
-
-const GUIDANCE_KEYS: readonly (keyof ActiveContextGuidance)[] = Object.freeze([
-  "actionResponses",
-]);
-
-export function resolveGuidance(value: unknown): ActiveContextGuidance {
-  if (value === undefined) return DEFAULT_GUIDANCE;
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("guidance must be an object of { actionResponses } booleans");
-  }
-  for (const key of Object.keys(value)) {
-    if (!GUIDANCE_KEYS.includes(key as keyof ActiveContextGuidance)) {
-      throw new Error(`guidance has no ${key} setting: the only keys are ` +
-        `${GUIDANCE_KEYS.join(", ")}, and they are booleans`);
-    }
-  }
-  const resolved = { ...DEFAULT_GUIDANCE } as ActiveContextGuidance;
-  for (const key of GUIDANCE_KEYS) {
-    if (!Object.hasOwn(value, key)) continue;
-    const setting = (value as Record<string, unknown>)[key];
-    if (typeof setting !== "boolean") throw new Error(`guidance.${key} must be a boolean`);
-    resolved[key] = setting;
-  }
-  return Object.freeze(resolved);
-}
-
 export const MAX_CONTEXT_RECEIPTS = 3;
 export const CONTEXT_RECEIPT_BLOCK_BYTES = 900;
 
-export const CONTEXT_MARK_RESPONSE_BYTES = 900;
+/**
+ * The post-fold notice's bound, and its own rather than the receipt block's.
+ *
+ * It is larger because it carries a variable-length list the receipt does not: three
+ * fixed sentences of instruction plus one entry per unbriefed fold, and the pending set
+ * grows past MAX_FRONTIER_CUTS_PER_PASS whenever the frontier stages faster than the
+ * 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 = 2_400;
 export const CONTEXT_STATUS_RESPONSE_BYTES = 24_000;
 export const MAX_UNMARKED_CANDIDATES = 3;
 
 export const MAX_FOLD_SPAN_CHARS = 16_000;
-export const MAX_WEDGE_ABSORB_TOKENS = 256;
 export const PEEK_DEFAULT_MAX_BYTES = 16_000;
 export const PEEK_HEAD_SHARE = 0.6;
 
-export const PEEK_READ_ONLY_CONTEXT_ACTIONS: ReadonlySet<string> = new Set(["status", "peek"]);
+/**
+ * A PEEK IS EPHEMERAL UNLESS THE AGENT SAYS OTHERWISE (Shane, 2026-08-22).
+ *
+ * The default follows the measured choice rather than the cautious one. On sealed run
+ * rep 7, six of seven peeks asked for ephemeral at first organic exposure, and the one
+ * durable read was the stage-64 probe, exactly where the bytes were wanted standing.
+ * The economics agree: a peek is a pure append and costs the cache nothing, while the
+ * withdrawal is a tail operation at the withdrawn result's own index, so the cheap read
+ * should be the one you get without asking.
+ *
+ * Only an explicit false is durable. A missing value, and anything the validator has
+ * already rejected, reads as ephemeral, so a host or model that never learned the
+ * argument still gets the cheap behaviour and can still recover the bytes by peeking
+ * again, which is lossless.
+ */
+export function peekIsEphemeral(params: Record<string, unknown> | undefined | null): boolean {
+  return params?.ephemeral !== false;
+}
+
+export const PEEK_READ_ONLY_CONTEXT_ACTIONS: ReadonlySet<string> = new Set(["status", "peek", "recall"]);
+
+/**
+ * THE WORKING MEMORY (Shane, 2026-08-26). A session-scoped ordered dictionary the agent
+ * maintains beside the fold index: keys list in a table of contents the projection
+ * carries, bodies live in state and are read on demand with `recall`. It exists because
+ * the campaign measured a structural gap, not a tuning one: a maintained digest (running
+ * tallies, current totals) is a different operation from a lossless index, and blending
+ * digest prose into the index's briefs was measured making BOTH worse (sol-20260826-full2
+ * rep 4: nine confident wrong end-block answers against the deterministic arm's zero).
+ * The digest gets its own channel and the index stays mechanical.
+ *
+ * Three constants, not knobs. The key cap keeps the table of contents a table of
+ * contents; the body cap is deliberately larger than a brief because a digest is
+ * maintained prose, not an index row; the entry cap bounds the whole store at a size
+ * whose table of contents stays one glance.
+ */
+export const MEMORY_KEY_CHARS = 64;
+export const MEMORY_BODY_CHARS = 4_000;
+export const MEMORY_KEYS_MAX = 24;
+
+export const WORKING_MEMORY_TOOL_ACTIONS = Object.freeze(["remember", "recall"] as const);
+
+export interface WorkingMemoryEntry {
+  key: string;
+  body: string;
+  /** Write counter at last update; the table of contents lists freshest first. */
+  ordinal: number;
+}
 
-export type MarkOrigin = "agent" | "ladder";
+/** "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
+ *  commit's coverage the same way. */
+export type MarkOrigin = "agent" | "ladder" | "user";
 
 export interface PendingFoldMark {
   mark: "fold";
@@ -245,22 +367,37 @@ export const ACTIVE_CONTEXT_POLICY = Object.freeze({
   refoldRatio: 0.85,
   prepareRatio: 0.90,
   responseReserve: 16_384,
-  minToolChars: 2_000,
-  minChapterChars: 4_000,
-  maxChapterChars: 128_000,
-  maxChapterTurns: 4,
+  // The most exact source bytes ONE read may put back in the window, whichever verb
+  // asks: an expand collapses its biggest children until the render fits, and a peek
+  // 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,
-  maxFoldSourceRefs: 256,
+  // 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;
@@ -312,6 +449,7 @@ export interface ActiveContextState {
   pendingMarks?: PendingMark[];
   pinnedPeeks?: never;
   briefs?: Record<string, BriefOverride>;
+  clips?: ToolClip[];
   prepared?: PreparedFold;
   advisory?: {
     highWater: number;
@@ -319,6 +457,8 @@ export interface ActiveContextState {
     armed?: { milestone: AdvisoryMilestone; threshold: number; scheduleKey: string };
   };
   rider?: { epoch: number; text: string };
+  /** The working memory's entries, in write order; absent when empty. */
+  memory?: WorkingMemoryEntry[];
 }
 
 export interface FoldRecordRef {
@@ -347,6 +487,8 @@ export interface ActiveContextCheckpointV2 {
   leases?: Record<string, number>;
   pendingMarks?: PendingMark[];
   briefs?: Record<string, BriefOverride>;
+  clips?: ToolClip[];
+  memory?: WorkingMemoryEntry[];
   advisory?: NonNullable<ActiveContextState["advisory"]>;
   rider?: NonNullable<ActiveContextState["rider"]>;
   lastCall?: NonNullable<ActiveContextState["lastCall"]>;
@@ -378,6 +520,21 @@ 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[];
+  // `memory` on a delta is the WHOLE array. It is bounded by MEMORY_KEYS_MAX entries and
+  // edited in place by key, so a change form would have to restate the key order the way
+  // the marks do while saving at most a handful of bounded bodies: the whole array is the
+  // cheaper wire. Absent means empty, by the same discriminator rule as the marks.
+  memory?: WorkingMemoryEntry[];
   advisory?: NonNullable<ActiveContextState["advisory"]>;
   rider?: NonNullable<ActiveContextState["rider"]>;
   lastCall?: NonNullable<ActiveContextState["lastCall"]>;
@@ -414,7 +571,6 @@ export interface ActiveContextSnapshot {
   thresholds: ActiveContextThresholds;
   budgetTokens: number;
   protectedIndices: Set<number>;
-  toolProtectedIndices: Set<number>;
   policy: typeof ACTIVE_CONTEXT_POLICY;
   toolName: string;
   brandNoun: string;