pi-fold 2.0.0 → 3.0.0

package/extensions/active-context.ts

@@ -22,6 +22,7 @@ import {
   descendantIds,
   encodedFoldSource,
   foldCandidatesDetail,
+  foldIndexRow,
   foldTreeDetail,
   peekFoldSource,
   prepareFold,
@@ -29,7 +30,6 @@ import {
   projectionSlateCandidates,
   protectEvidence,
   requireActiveFold,
-  selectAutomaticChapter,
   selectAutomaticRung,
   setFoldProjectionState,
   withExpandLease,
@@ -56,7 +56,6 @@ import {
   providerTokens,
   refsProtected,
   stringIds,
-  toolRefsProtected,
   toolPayload,
 } from "./lib/measurement.ts";
 import type {
@@ -70,7 +69,6 @@ import {
   clearPrepared,
   deriveFoldParents,
   flattenFoldRefs,
-  foldBrief,
   foldIdFor,
   makeFoldRecordEntry,
   makeStateCheckpoint,
@@ -90,6 +88,7 @@ import {
   activeContextSource,
   ACTIVE_CONTEXT_POLICY,
   ACTIVE_CONTEXT_TOOL_ACTIONS,
+  UNBRIEFED_FOLDS_BEFORE_NOTICE,
   contextBrand,
   DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
   DEFAULT_ACTIVE_CONTEXT_COMMAND_NAMES,
@@ -99,7 +98,6 @@ import {
   COMMIT_RECLAIM_FLOOR_SHARE,
   CONTEXT_RECEIPT_BLOCK_BYTES,
   DEFAULT_CONTEXT_WINDOW,
-  resolveGuidance,
   assertThresholdsServable,
   resolveThresholds,
   servingBudgetTokens,
@@ -107,15 +105,15 @@ import {
   entryTypeNamespace,
   MAX_FOLD_SPAN_CHARS,
   MAX_PINNED_SHARE,
-  MAX_WEDGE_ABSORB_TOKENS,
   PEEK_DEFAULT_MAX_BYTES,
+  peekIsEphemeral,
   PEEK_MIN_SLICE_BYTES,
   PEEK_READ_ONLY_CONTEXT_ACTIONS,
+  RETIRED_TOOL_ACTIONS,
   AUTO_FOLD_BLACKLIST_DEFAULT,
   USER_RESCUE_MAX_SOURCE_CHARS,
 } from "./lib/policy.ts";
 import type {
-  ActiveContextGuidance,
   ActiveContextSnapshot,
   ActiveContextState,
   ActiveContextThresholds,
@@ -123,15 +121,16 @@ import type {
   FoldCandidate,
   FoldKind,
   FoldRecordEntry,
+  MarkOrigin,
   PreparedFold,
 } from "./lib/policy.ts";
 import {
   absorbWedgeMarks,
+  markSpanRefs,
 } from "./lib/scheduling.ts";
 import {
   contextReceipt,
-  contextRiderText,
-  markAwarenessText,
+  foldNoticeText,
   receiptBlockText,
   withReceipt,
 } from "./lib/curation.ts";
@@ -140,35 +139,33 @@ import type {
 } from "./lib/curation.ts";
 import {
   addPendingMark,
-  claimedRefKeys,
+  commitCoverage,
+  windowClaims,
   commitPendingMarks,
   consolidationMarks,
   ephemeralPeekMarks,
+  epochCommitDue,
   estimatedTokens,
   foldMarkFor,
-  ladderSelectionMark,
   ladderBrief,
   markAccounting,
-  markEligibility,
   markFreedBytes,
   unmarkedRemainder,
-  guardWaiverCount,
-  markedFoldIds,
+  markClaimingRef,
   markOrdinal,
   pendingMarks,
-  markTouchesCurrentTurn,
+  refoldMarks,
   schedulingStatus,
   topUpMarks,
+  frontierMarks,
   withPendingMarks,
 } from "./lib/scheduling.ts";
 import {
-  candidateSpanChars,
   manualFoldCandidate,
   peekedSourceFoldIds,
-  selectAutomaticToolBatch,
   snapFoldCandidate,
   snapToFoldBoundaries,
-  splitCandidateBySize,
+  spanBytes,
 } from "./lib/selection.ts";
 import type { SpanCorrection } from "./lib/selection.ts";
 import {
@@ -187,8 +184,8 @@ import type {
   ProjectionChange,
 } from "./lib/instrumentation.ts";
 import { buildActiveContextCommands, buildActiveContextTool } from "./lib/tool-surface.ts";
+import { buildFoldEditorData, FoldEditorView } from "./lib/editor-ui.ts";
 import {
-  currentTurnRefKeys,
   mapActiveContext,
 } from "./lib/transcript.ts";
 import {
@@ -255,7 +252,6 @@ export function registerActiveContext(pi: any, options: {
   blacklistAutoFoldTools?: ReadonlySet<string>;
   providerInputBudget?: number;
   thresholds?: ActiveContextThresholds;
-  guidance?: Partial<ActiveContextGuidance>;
 }): {
   projectionCandidates: (ctx: any) => Array<Record<string, unknown>>;
 } {
@@ -288,6 +284,13 @@ export function registerActiveContext(pi: any, options: {
         "tools it meant to permit");
     }
   }
+  if (Object.hasOwn(options, "guidance")) {
+    throw new Error("guidance is no longer an option: it switched the copy that taught the " +
+      "agent to CHOOSE SPANS, and the agent does not choose spans. The runtime cuts at the " +
+      "frontier and the agent annotates what it cut, so the guidance it switched has been " +
+      "replaced wholesale by the post-fold notice, which is not optional because a fold the " +
+      "agent is never told about is one it can never brief");
+  }
   if (Object.hasOwn(options, "commandPrefix")) {
     throw new Error("commandPrefix is no longer an option: give whole names with commandNames");
   }
@@ -317,13 +320,12 @@ export function registerActiveContext(pi: any, options: {
   }
   const thresholds = resolveThresholds(options.thresholds);
   assertThresholdsServable(thresholds, providerInputBudget ?? servingBudgetTokens(DEFAULT_CONTEXT_WINDOW));
-  const guidance = resolveGuidance(options.guidance);
   const stateEntryType = `${entryTypePrefix}-state`;
   const foldRecordEntryType = `${entryTypePrefix}-fold-record`;
   const milestoneProjectionType = `${entryTypePrefix}-milestone`;
   const advisoryProjectionType = `${entryTypePrefix}-advisory`;
+  const foldNoticeProjectionType = `${entryTypePrefix}-fold-notice`;
   const receiptProjectionType = `${entryTypePrefix}-receipts`;
-  const riderProjectionType = `${entryTypePrefix}-rider`;
   const curationProjectionType = `${entryTypePrefix}-curation`;
   const entryNamespace = entryTypeNamespace(entryTypePrefix);
   const providerMeasurementEntryType = `${entryNamespace}-provider-context-measurement`;
@@ -353,6 +355,10 @@ export function registerActiveContext(pi: any, options: {
   };
 
   const ladder = {
+    /** The provider measurement the last band-top commit ran against; one commit per one. */
+    bandTopMeasurement: null as unknown,
+    /** The snapshot-and-state key whose frontier scan came back empty; see advanceFoldFrontier. */
+    frontierEmptyKey: null as string | null,
     pendingManual: false,
     preparing: null as { id: string; controller: AbortController; promise: Promise<void> } | null,
     lastPreparationError: null as string | null,
@@ -401,7 +407,12 @@ export function registerActiveContext(pi: any, options: {
     previousText: null as string | null,
     lastChange: "append" as ProjectionChange,
     lastPreservedShare: null as number | null,
-    sinceHandoff: [] as Array<{ seq: number; kind: string }>,
+    sinceHandoff: [] as Array<{
+      seq: number;
+      kind: string;
+      action?: string;
+      ok?: boolean;
+    }>,
     mutationsSinceHandoff: 0,
     requests: 0,
     lastMutationRequest: 0,
@@ -462,6 +473,13 @@ export function registerActiveContext(pi: any, options: {
     hardFenceReleasedProjectionKeys: new Set<string>(),
   };
 
+  // EPHEMERAL PEEK (Build 4b): tool call ids whose peek asked for one-read
+  // visibility. In-memory ON PURPOSE: a restart forgets the registry and the
+  // result stays durable, which is the safe default, and the durable entry
+  // always keeps the exact bytes, so folding, peek and rollback read the
+  // source unchanged whatever the projection shows.
+  const ephemeralPeeks = new Set<string>();
+
   const nativeCompaction = {
     lastThresholdDecision: null as Record<string, unknown> | null,
     pendingNativeReceipt: null as NativeCompactionCompletionReceipt | null,
@@ -540,7 +558,12 @@ export function registerActiveContext(pi: any, options: {
       revision: persistence.state?.revision ?? 0,
       at: Date.now(),
     }, payload);
-    instrumentation.sinceHandoff.push({ seq: record.seq, kind });
+    instrumentation.sinceHandoff.push({
+      seq: record.seq,
+      kind,
+      ...(typeof record.action === "string" ? { action: record.action } : {}),
+      ...(typeof record.ok === "boolean" ? { ok: record.ok } : {}),
+    });
     const operation = curation.instrumentationQueue.then(async () => {
       try { await pi.appendEntry(contextEventEntryType, record); }
       catch { }
@@ -552,6 +575,12 @@ export function registerActiveContext(pi: any, options: {
   const PREFIX_MUTATING_KINDS: ReadonlySet<string> = new Set([
     "context.commit", "context.fold", "context.absorb", "context.split", "context.recovery",
   ]);
+  const CACHE_ACTION_REQUEST_CLASS: Readonly<Record<string, string>> = Object.freeze({
+    fold: "after-mark",
+    peek: "after-peek",
+    expand: "after-expand",
+    refold: "after-refold",
+  });
 
   const deliverReceipt = (receipt: ContextReceipt): void => {
     curation.receipts = withReceipt(curation.receipts, receipt);
@@ -1191,7 +1220,6 @@ export function registerActiveContext(pi: any, options: {
       policy: snapshot ? {
         maxTarget: snapshot.thresholds.maxTarget,
         minTarget: snapshot.thresholds.minTarget,
-        freshTail: snapshot.thresholds.freshTail,
         hardFenceRatio: hardFenceRatio(snapshot),
       } : null,
     });
@@ -1487,6 +1515,198 @@ export function registerActiveContext(pi: any, options: {
     ctx.abort();
   };
 
+  // THE BAND TOP COMMITS ON ITS OWN (Shane, 2026-08-22).
+  //
+  // `maxTarget` is what the settings panel calls the commit trigger, and until now it
+  // fired nothing. There were two commit sites: the fence below, which measures against
+  // the WHOLE serving budget plus a margin, and the compaction boundary, which is Pi's
+  // own threshold near the top of the window. A live 1M-window session sat at 571,367
+  // tokens against a stated trigger of 516,096 with `folds: 0`, because neither site was
+  // anywhere near. On a 251,520-token budget the fence sits close enough behind the
+  // boundary to hide it; at 1M the two are half a million tokens apart.
+  //
+  // Shane, on the shape of the fix: "if the context is over our max, we commit. I don't
+  // think that should be anything like once it crosses this threshold or anything like
+  // that, it should just be an if statement. That way there isn't much room for error, if
+  // it's over we fold." So there is no latch and no crossing to detect. Every projection
+  // pass asks one question and acts on the answer. Occupancy only moves when the provider
+  // measures, and a second attempt inside one handoff already defers on the mutation
+  // budget, so "one commit per pass while over" is what this produces. A pass that finds
+  // nothing to fold says so in the stream, which is a state worth seeing rather than one
+  // worth suppressing.
+  /**
+   * Cut the raw material that has piled up past the last fold, and say so.
+   *
+   * This is the whole of "the runtime cuts": no commit, no bytes moved, no persistence
+   * boundary. It stages pending marks the same way a commit's own top-up does, through
+   * the same selector and the same brief builder, so a frontier cut and a commit fill are
+   * the same object and the agent cannot tell them apart except by when it heard.
+   */
+  const advanceFoldFrontier = (snapshot: ActiveContextSnapshot): number => {
+    if (!persistence.state) return 0;
+    if (ladder.automaticFailure !== null) return 0;
+    // A SCAN THAT FOUND NOTHING IS NOT RE-RUN UNTIL SOMETHING CHANGES. Exhausting the
+    // selector costs one window scan per staged cut and one more to come back empty, and
+    // once everything foldable is staged EVERY later pass pays that last scan to be told
+    // the same thing. Measured on the 90-projection loop inside gate 50's instrumentation
+    // claim: 137ms of a 460ms pass, 30 percent of the runtime's own per-request cost, for
+    // an answer that cannot have changed.
+    //
+    // The key is the one `authoritativeSnapshotFor` already trusts for the snapshot
+    // itself, plus the two pieces of state the selector reads: the revision, which moves
+    // on every durable write, and the pending-mark count, which moves when the agent
+    // withdraws one. It is only consulted when the last scan staged NOTHING; a scan that
+    // staged something changed the state, so its key is stale by construction.
+    const frontierKey = `${snapshot.messages.length}:${snapshot.mapped.length}:` +
+      `${persistence.state.revision}:${pendingMarks(persistence.state).length}`;
+    if (ladder.frontierEmptyKey === frontierKey) return 0;
+    // CONSOLIDATION IS ANNOUNCED THE SAME WAY (Shane, 2026-08-23). When standing folds
+    // reach `consolidateAfter` the parent that will absorb them is staged HERE rather than
+    // being computed inside the commit, for exactly the reason the frontier exists: a
+    // parent's brief indexes ten children, it is the entry the agent will navigate by, and
+    // the agent knows what mattered in those children while the commit only knows their
+    // order. Staged, it is byte-inert like any other pending mark and rides the same
+    // notice, so there is one mechanism and not two.
+    const marks = [
+      ...frontierMarks({
+        snapshot,
+        state: persistence.state,
+        ordinal: instrumentation.requests,
+      }),
+      ...consolidationMarks({
+        snapshot,
+        state: persistence.state,
+        ordinal: instrumentation.requests,
+      }),
+    ];
+    let state = persistence.state;
+    const staged: ReturnType<typeof frontierMarks> = [];
+    for (const mark of marks) {
+      const addition = addPendingMark(state, mark);
+      if (!addition.added) continue;
+      state = addition.state;
+      staged.push(mark);
+    }
+    // NOTHING STAGED, so this key is answered and the next pass under it can skip the
+    // scan. Read from `staged` rather than from `marks`, because a candidate the pending
+    // set already holds comes back from the selector every pass and is refused every
+    // pass: keying on `marks` left the skip unreachable in exactly the steady state it
+    // was built for, and half its measured saving on the floor.
+    if (!staged.length) {
+      ladder.frontierEmptyKey = frontierKey;
+      return 0;
+    }
+    persistence.state = state;
+    emit("context.frontier", {
+      cut: staged.length,
+      pending_marks: (state.pendingMarks ?? []).length,
+      min_fold_chars: thresholds.minFoldChars,
+    });
+    // NO PERSISTENCE BOUNDARY OF ITS OWN, deliberately. A cut is DERIVED: the mark id
+    // comes from the span, so a restart that lost these re-cuts exactly the same spans
+    // with exactly the same ids, and the only thing that has to survive is a brief the
+    // agent WROTE, which its own action persists along with the marks it rides with.
+    // Persisting here instead cost a durable write on every projection pass, and the
+    // branch entry it appended rebuilt the projection: gates 110 and 111 caught it as an
+    // occupancy anchor that stopped reading the provider's own count.
+    return staged.length;
+  };
+
+  /**
+   * Tell the agent what was cut, once there is enough of it to be worth a turn.
+   *
+   * It is built from LIVE state, so it names what is unbriefed at the pass it speaks on,
+   * and it is admitted ONCE per frozen projection, so a pass that adds material leaves it
+   * buried at its own index rather than moving it to the tail. Those two together mean it
+   * is a snapshot rather than a running tally: cuts staged after it spoke wait for the
+   * next pass that rebuilds the projection anyway, and that is the trade being made. A
+   * carrier that re-renders to stay current has to move, moving costs the occupancy
+   * anchor its provider count, and an anchor is worth more than a fold id arriving one
+   * epoch early. What it must never do is ask twice for a brief the agent has written,
+   * and it does not: the rebuild reads the marks, not its own last text.
+   */
+  const appendFoldNotice = (projected: unknown[], snapshot: ActiveContextSnapshot): unknown[] => {
+    if (!persistence.state) return projected;
+    const held = pendingMarks(persistence.state);
+    const unbriefed = held.filter((mark) => mark.briefProvenance?.kind !== "supplied");
+    // BATCHED, AND APPENDED ONCE. A notice per cut is noise, and noise is how guidance
+    // gets ignored; the frontier cuts often and this speaks only when a batch has built
+    // up. `carrierAdmitted` is what makes it an APPEND rather than a rewrite: once the
+    // carrier is in the frozen projection it is not pushed again, so raw material
+    // arriving afterwards lands after it and the prefix in front of it never moves.
+    //
+    // The first cut of this withdrew the carrier and re-pushed it at the tail every pass,
+    // the way the steward band had to because a band must be able to stand down. That is
+    // exactly wrong for this one: re-pushing moved the notice past each newly arrived
+    // message, so the byte at its old index changed on a pass where nothing else had, and
+    // gates 110 and 111 read the whole projection as rewritten and dropped the occupancy
+    // anchor back to the estimate. A carrier that moves on a quiet pass costs the cache,
+    // which is the one thing this design exists to avoid.
+    if (unbriefed.length < UNBRIEFED_FOLDS_BEFORE_NOTICE) return projected;
+    if (!carrierAdmitted("fold-notice")) return projected;
+    const text = foldNoticeText({
+      unbriefed: unbriefed.map((mark) => ({
+        id: mark.id,
+        kind: mark.kind,
+        tokens: estimatedTokens(markFreedBytes(snapshot, persistence.state!, mark)),
+      })),
+      pending: held.length,
+      toolName,
+      brandNoun,
+    });
+    emit("context.frontier", {
+      cut: 0,
+      pending_marks: held.length,
+      unbriefed: unbriefed.length,
+      notice_chars: text.length,
+    });
+    projected.push({
+      role: "custom",
+      customType: foldNoticeProjectionType,
+      content: text,
+      display: false,
+      details: { source: activeContextSource(entryTypePrefix), ephemeral: true },
+      timestamp: typeof ownValue(snapshot.messages.at(-1), "timestamp") === "number"
+        ? ownValue(snapshot.messages.at(-1), "timestamp")
+        : 0,
+    });
+    return projected;
+  };
+
+  const enforceBandTop = async (
+    snapshot: ActiveContextSnapshot,
+    ctx: any,
+  ): Promise<boolean> => {
+    if (!epochCommitDue(snapshot, measurements.latestRatio)) return false;
+    // ONE COMMIT PER MEASUREMENT, which is what "one commit per crossing" means once the
+    // commit stops taking everything. There was no latch here and none was needed: the
+    // band-top commit folded every span the class law offered, so the next pass found
+    // nothing proposable and deferred. The 2026-08-23 depth bound ends that, on purpose,
+    // and without this the parked window commits a SLICE on every pass at the same
+    // declared occupancy, which is a prefix rewrite per pass and the exact cache cost the
+    // one-commit rule exists to prevent. Occupancy is anchored to the provider's own
+    // count, so a new count is the only evidence that the window actually moved; the
+    // latch is keyed to that measurement and nothing else.
+    if (ladder.bandTopMeasurement !== null &&
+        ladder.bandTopMeasurement === measurements.lastProviderMeasurement) {
+      return false;
+    }
+    ladder.bandTopMeasurement = measurements.lastProviderMeasurement;
+    let action: Record<string, unknown> | null = null;
+    try {
+      // NULL RATIO, deliberately. The band top is routine housekeeping at a stated
+      // threshold, not an emergency, and a null ratio is what arms the depth bound: the
+      // commit takes stalest-first and stops at the aim, so the newest events stay raw
+      // for as long as there is room for them. The fence and the compaction boundary
+      // carry a ratio and no bound, because something has already gone wrong there.
+      action = await attemptAutomaticCommit(snapshot, ctx, "band-top", null);
+    } catch (error) {
+      suspendAutomatic(error, "band-top", ctx);
+      return false;
+    }
+    return action !== null;
+  };
+
   const enforceProjectionBudget = async (
     snapshot: ActiveContextSnapshot,
     projected: unknown[],
@@ -1503,9 +1723,10 @@ export function registerActiveContext(pi: any, options: {
       attempts += 1;
       // THE EMERGENCY IS THE REQUEST THAT WILL NOT FIT, and only that. A projection at
       // the margin is ordinary work: the fence commits it because it is the pass holding
-      // the request, but it is not a recovery, it does not waive the current-turn guard,
-      // and it does not buy an exemption from the reclaim floor. Waiving at the margin
-      // spends the open turn's own evidence on headroom the boundary was about to buy.
+      // the request, but it is not a recovery and it does not buy an exemption from the
+      // reclaim floor. What separates it from the band top is depth alone: the fence
+      // carries a ratio, so its commit takes everything eligible rather than stopping at
+      // the aim.
       const emergency = measured.over || rejected;
       if (emergency) curation.recoveryAttempts += 1;
       let action: Record<string, unknown> | null = null;
@@ -1678,40 +1899,90 @@ export function registerActiveContext(pi: any, options: {
     return projected;
   };
 
-  const appendRider = (projected: unknown[], snapshot: ActiveContextSnapshot): unknown[] => {
-    const rider = persistence.state?.rider;
-    if (!rider) return projected;
-    if (!carrierAdmitted("rider")) return projected;
-    projected.push({
-      role: "custom",
-      customType: riderProjectionType,
-      content: rider.text,
-      display: false,
-      details: {
-        source: activeContextSource(entryTypePrefix),
-        ephemeral: true,
-        riderEpoch: rider.epoch,
-      },
-      timestamp: typeof ownValue(snapshot.messages.at(-1), "timestamp") === "number"
-        ? ownValue(snapshot.messages.at(-1), "timestamp")
-        : 0,
-    });
-    return projected;
-  };
-
   const holdFrozen = (projected: unknown[]): unknown[] => {
     freeze.projection = [...projected];
     freeze.active = false;
     return projected;
   };
 
+  // An ephemeral peek result rides the projection exactly until the model's
+  // next message, the same answered reading as the directed ask, then its
+  // index holds a one-line placeholder and the reply is the surviving trace.
+  // A message already projection-shaped (a fold's own deterministic brief
+  // placeholder carries the same toolCallId) is never touched: only the raw
+  // result is the ephemeral one.
+  //
+  // Returns what it replaced, keyed by call id, because the freeze has to be
+  // told. Running against the BODY alone was not enough: the freeze compares
+  // this pass's body prefix against the previous one and reuses the previous
+  // PROJECTION when they match, and a withdrawal edits a body index inside
+  // that prefix, so the comparison failed and the whole projection was rebuilt
+  // from the body. The rebuild drops every receipt the freeze had
+  // buried mid-array over the session, which moves divergence back to the
+  // FIRST buried carrier rather than leaving it at the withdrawn index. That
+  // is the opposite of what this mechanism is for: a tail edit was rewriting
+  // the session's whole cached prefix.
+  const withdrawConsumedEphemeralPeeks = (body: unknown[]): Map<string, unknown> => {
+    const withdrawn = new Map<string, unknown>();
+    if (!ephemeralPeeks.size) return withdrawn;
+    for (let index = 0; index < body.length; index += 1) {
+      const message = body[index];
+      const callId = ownValue(message, "toolCallId");
+      if (ownValue(message, "role") !== "toolResult" || typeof callId !== "string" ||
+        !ephemeralPeeks.has(callId)) continue;
+      const details = ownValue(message, "details");
+      if (details && typeof ownValue(details, "projection") === "string") continue;
+      const answered = body.slice(index + 1).some((later) =>
+        ownValue(later, "role") === "assistant");
+      if (!answered) continue;
+      const placeholder = {
+        role: "toolResult",
+        toolCallId: callId,
+        toolName: ownValue(message, "toolName"),
+        content: [{ type: "text", text: "Ephemeral peek consumed; the reply that followed it is the surviving trace." }],
+        isError: false,
+        details: { projection: "ephemeral-peek-consumed" },
+        timestamp: ownValue(message, "timestamp"),
+      };
+      body[index] = placeholder;
+      withdrawn.set(callId, placeholder);
+    }
+    return withdrawn;
+  };
+
+  // Carry a withdrawal into the freeze's own kept arrays so the frozen prefix
+  // stays usable. Matched by CALL ID rather than by position: the projection
+  // interleaves buried carriers, so a body index is not a projection index.
+  // The substitution is identity-preserving on role, call id, tool name and
+  // timestamp, so what changes is the one result's content and nothing else,
+  // and divergence lands at the withdrawn index where the mechanism puts it.
+  const carryWithdrawalIntoFreeze = (messages: unknown[], withdrawn: Map<string, unknown>): void => {
+    for (let index = 0; index < messages.length; index += 1) {
+      const message = messages[index];
+      if (ownValue(message, "role") !== "toolResult") continue;
+      const callId = ownValue(message, "toolCallId");
+      if (typeof callId !== "string") continue;
+      const placeholder = withdrawn.get(callId);
+      if (!placeholder) continue;
+      const details = ownValue(message, "details");
+      if (details && typeof ownValue(details, "projection") === "string") continue;
+      messages[index] = placeholder;
+    }
+  };
+
   const projectWithAdvisory = (snapshot: ActiveContextSnapshot): unknown[] => {
     const body = projectActiveContext(snapshot, persistence.state!).filter((message) => {
       const customType = ownValue(message, "customType");
       return customType !== milestoneProjectionType && customType !== advisoryProjectionType &&
-        customType !== receiptProjectionType &&
-        customType !== riderProjectionType && customType !== curationProjectionType;
+        customType !== receiptProjectionType && customType !== curationProjectionType &&
+        customType !== foldNoticeProjectionType;
     });
+    const withdrawn = withdrawConsumedEphemeralPeeks(body);
+    if (withdrawn.size && freeze.body) {
+      carryWithdrawalIntoFreeze(freeze.body, withdrawn);
+      freeze.bodyText = stableStringify(freeze.body);
+      if (freeze.projection) carryWithdrawalIntoFreeze(freeze.projection, withdrawn);
+    }
     const held = freeze.body?.length ?? 0;
     freeze.active = freeze.projection !== null && body.length >= held &&
       stableStringify(body.slice(0, held)) === freeze.bodyText;
@@ -1722,7 +1993,7 @@ export function registerActiveContext(pi: any, options: {
     freeze.body = body;
     freeze.bodyText = stableStringify(body);
     appendReceipts(projected, snapshot);
-    appendRider(projected, snapshot);
+    appendFoldNotice(projected, snapshot);
     return holdFrozen(projected);
   };
   const noteProjection = (projected: unknown[]): void => {
@@ -1738,8 +2009,27 @@ export function registerActiveContext(pi: any, options: {
       ? divergence.identicalChars / previousChars
       : null;
     const charsPerToken = projectionCharsPerToken();
+    const successfulCacheActions = instrumentation.sinceHandoff.filter((event) =>
+      event.kind === "context.attempt" && event.ok === true &&
+      typeof event.action === "string" && CACHE_ACTION_REQUEST_CLASS[event.action]);
+    const latestCacheAction = successfulCacheActions.at(-1) ?? null;
+    const latestCacheActionClass = latestCacheAction?.action
+      ? CACHE_ACTION_REQUEST_CLASS[latestCacheAction.action]
+      : null;
+    const projectionActions = successfulCacheActions.filter((event) =>
+      event.action === "expand" || event.action === "refold");
     const causes = instrumentation.sinceHandoff.filter((event) =>
-      PREFIX_MUTATING_KINDS.has(event.kind));
+      PREFIX_MUTATING_KINDS.has(event.kind) || projectionActions.includes(event));
+    const structuralCause = causes.some((event) => event.kind !== "context.attempt");
+    const requestClass = causes.some((event) => event.kind === "context.recovery")
+      ? "after-rollback"
+      : (latestCacheAction?.action === "expand" || latestCacheAction?.action === "refold")
+        ? latestCacheActionClass!
+        : structuralCause
+          ? "after-fold"
+          : latestCacheActionClass
+            ? latestCacheActionClass
+            : divergence.index === null ? "steady-state" : "after-message";
     const reading = projectedTokenReading(projected);
     emit("context.projection", {
       change: comparison.change,
@@ -1768,14 +2058,14 @@ export function registerActiveContext(pi: any, options: {
       estimated_tokens: Math.ceil(text.length / charsPerToken),
       cause: divergence.index === null
         ? "pure-append"
-        : (causes.length ? causes.map((event) => event.kind).join(",") : "unattributed"),
+        : (causes.length ? causes.map((event) => event.kind === "context.attempt"
+          ? `context.attempt:${String(event.action)}`
+          : event.kind).join(",") : "unattributed"),
       cause_event_seqs: causes.map((event) => event.seq).join(","),
       events_since_handoff: instrumentation.sinceHandoff.length,
-      request_class: divergence.index === null
-        ? "steady-state"
-        : (causes.some((event) => event.kind === "context.recovery")
-          ? "after-rollback"
-          : (causes.length ? "after-fold" : "after-message")),
+      cache_action: latestCacheAction?.action ?? null,
+      cache_action_seq: latestCacheAction?.seq ?? null,
+      request_class: requestClass,
     });
     instrumentation.previousText = text;
     instrumentation.sinceHandoff = [];
@@ -1852,6 +2142,7 @@ export function registerActiveContext(pi: any, options: {
     let state = persistence.state!;
     let peekAdded = 0;
     let topUpAdded = 0;
+    let refoldAdded = 0;
     let consolidationAdded = 0;
     let closingAdded = 0;
     for (const mark of ephemeralPeekMarks({ snapshot, state, ordinal })) {
@@ -1862,7 +2153,6 @@ export function registerActiveContext(pi: any, options: {
       const addition = addPendingMark(state, mark);
       if (addition.added) { state = addition.state; consolidationAdded += 1; }
     }
-    const guarded = currentTurnRefKeys(snapshot);
     const capacity = servingCapacity(snapshot.contextWindow);
     const usedTokens = capacity.usedTokens;
     const budgetTokens = capacity.budgetTokens;
@@ -1879,40 +2169,60 @@ export function registerActiveContext(pi: any, options: {
       });
       return null;
     }
-    const freeingTarget = usedTokens === null || budgetTokens <= 0
-      ? 0
-      : Math.max(0, (usedTokens - thresholds.minTarget * budgetTokens) / budgetTokens);
-    if (topUp) {
-      for (const mark of topUpMarks({
-        snapshot,
-        state,
-        ordinal,
-        eligibleOnly: true,
-        targetShare: freeingTarget,
-      })) {
+    // ONE DEFINITION OF THE DROP. The fill sizes itself to it, the advisory warns
+    // against it, and the mark response answers "how much more" with it.
+    const freeingTarget = commitCoverage({ snapshot, state, usedTokens, budgetTokens }).targetShare;
+    // ONE COMMIT, SIZED BEFORE IT RUNS (Shane, 2026-08-21). At the threshold we know how
+    // far the window has to come down: `freeingTarget` is the distance from what is used
+    // now to the minTarget floor. The agent's marks count toward that distance first and
+    // the ladder fills the remainder from the stale end, so an agent that marked 30k of a
+    // 100k drop leaves 70k for the fill and both land in the SAME commit.
+    //
+    // Three rules decide the fill, and each replaced something that was tried first:
+    //
+    // The ladder does not STAND DOWN when the agent has marked. Standing down commits at
+    // whatever depth the agent happened to reach, so one small mark commits a barely-moved
+    // window and the next fence pass fires a second commit in the same cycle, which is the
+    // cache cost the one-commit rule exists to prevent. `topUpMarks` measures progress
+    // against the state it is handed, so agent marks are counted rather than displaced,
+    // and `claimedRefKeys` keeps the fill off spans the agent already took.
+    //
+    // Raw stale material is spent BEFORE expanded folds, so an agent reading an expanded
+    // fold keeps it while anything else can cover the drop. This is also the only route
+    // to the refold rung now that nothing stages between commits.
+    //
+    // The fill measures progress over EVERY mark it makes, not just the ones this commit
+    // will apply. Measuring the eligible share alone is what a starved commit needs and it
+    // is wrong here: a mark over protected evidence moves the eligible share by nothing,
+    // so the loop kept marking and walked a whole 24-batch excursion chasing a target it
+    // could not reach that way (the retainer was the current-turn guard then; pins and
+    // protected evidence retain the same way now). Counting everything bounds the fill at
+    // the drop it was asked for. The backstop still reads the eligible share, because
+    // starvation is the one state where the difference is the point.
+    const fill = (targetShare: number, eligibleOnly: boolean): void => {
+      for (const mark of topUpMarks({ snapshot, state, ordinal, eligibleOnly, targetShare })) {
         const addition = addPendingMark(state, mark);
         if (addition.added) { state = addition.state; topUpAdded += 1; }
       }
+      for (const mark of refoldMarks({ snapshot, state, ordinal, eligibleOnly, targetShare })) {
+        const addition = addPendingMark(state, mark);
+        if (addition.added) { state = addition.state; refoldAdded += 1; }
+      }
+    };
+    let backstopFired = false;
+    if (topUp) {
+      fill(freeingTarget, false);
       const reachedShare = markAccounting(snapshot, state).eligibleFreedBudgetShare;
       const shallow = reachedShare < Math.max(commitDepthFloorShare(snapshot), freeingTarget);
       if (shallow && atOrAboveBackstop(snapshot, waiverRatio)) {
-        for (const mark of topUpMarks({
-          snapshot,
-          state,
-          ordinal,
-          eligibleOnly: true,
-          targetShare: 1,
-        })) {
-          const addition = addPendingMark(state, mark);
-          if (addition.added) { state = addition.state; topUpAdded += 1; }
-        }
+        backstopFired = true;
+        fill(1, true);
       }
     }
     const wedges = absorbWedgeMarks({
       snapshot,
       state,
       charsPerToken: projectionCharsPerToken(),
-      excludeRefKeys: guarded,
     });
     state = wedges.state;
     const accounting = markAccounting(snapshot, state);
@@ -1942,49 +2252,80 @@ export function registerActiveContext(pi: any, options: {
         eligible_marks: accounting.eligibleMarks,
         eligible_freed_share: accounting.eligibleFreedBudgetShare,
         reclaim_floor_share: COMMIT_RECLAIM_FLOOR_SHARE,
+        // THE REMAINDER RIDES EVERY DEFERRAL, not just the empty one. It was on
+        // `nothing-proposable` alone, which was the only starved shape while staging
+        // happened at commit time. The frontier cuts ahead of the commit, so a starved
+        // pass now usually arrives holding a mark it cannot apply and lands HERE instead,
+        // and "below the reclaim floor" without the remainder does not tell a reader
+        // whether the mass is held or simply absent. That is the distinction the whole
+        // record exists to draw.
+        unmarked_stale_spans: unmarkedRemainder(snapshot, state, projectionCharsPerToken()).spans,
         window_tokens: snapshot.contextWindow,
       });
       return null;
     }
     const bytesBefore = bytes(projectActiveContext(snapshot, state));
-    const guardWaiver = guardWaiverCount({
-      snapshot,
-      ratio: waiverRatio,
-      boundary: trigger === "compaction-boundary",
-      guardedMarks: pendingMarks(state).filter((mark) =>
-        markTouchesCurrentTurn(state, mark, guarded)).length,
-      otherApplicableMarks: pendingMarks(state).filter((mark) =>
-        !markTouchesCurrentTurn(state, mark, guarded) &&
-        markEligibility(snapshot, state, mark) === "eligible").length,
-    });
+    // THE COMMIT CUTS ONLY AS DEEP AS THE BUDGET ASKS (Shane, 2026-08-23). The frontier
+    // stages as material arrives, so by now the pending set is most of the window; without
+    // this bound the first commit would fold all of it. `freeingTarget` is a share of the
+    // budget and the bound is bytes, so it is converted once, here, through the same ratio
+    // the projection weighs itself with.
+    //
+    // It binds on the ROUTINE path only: a null ratio is the band top, ordinary
+    // housekeeping at a stated threshold, and that is where "only as deep as it needs"
+    // belongs. The fence and the compaction boundary carry a ratio because something has
+    // already gone wrong there, and a lane holding a request that will not fit is not the
+    // place to leave depth on the table. The backstop is exempt for the same reason: it
+    // fires only when the commit is already starving.
+    //
+    // This bound is also what protects the working set since the current-turn guard was
+    // deleted (Shane, 2026-08-23, from the first live session): the cut takes stalest
+    // first and stops at the aim, so the newest events stay raw exactly as long as there
+    // is room for them, in every session shape including one that never closes a turn.
     let result = await commitPendingMarks({
       snapshot,
       state,
       generation: lifecycle.generation,
       retainIneligible: true,
-      guardCurrentTurn: true,
-      guardWaiver,
+      ...(backstopFired || waiverRatio !== null ? {} : {
+        applyTargetBytes: Math.ceil(freeingTarget * budgetTokens * projectionCharsPerToken()),
+      }),
     });
     for (;;) {
+      // THE CLOSING PASS COMMITS ONLY WHAT IT SEATS (2026-08-23). It rides the same paid
+      // rewrite to give a group its parent, and it runs UNBOUNDED because a parent's whole
+      // span must land together. Handing it the full pending set therefore leaked the depth
+      // cut: the marks the bound had just retained were still pending, the closing commit
+      // carried no bound, and the first band-top commit after the guard deletion folded all
+      // 24 of them to the floor (gate 09's fixture, applied 26 of 24 with deferred 0). The
+      // marks the cut held back are set aside before the closing commit and restored after,
+      // so the only thing an unbounded closing pass can spend is the parents it just made.
       let closing = result.state;
+      const heldBack = pendingMarks(closing);
+      let seeded = withPendingMarks(closing, []);
+      let seededAdded = 0;
       for (const mark of consolidationMarks({ snapshot, state: closing, ordinal })) {
         const addition = addPendingMark(closing, mark);
-        if (addition.added) { closing = addition.state; closingAdded += 1; }
+        if (!addition.added) continue;
+        closing = addition.state;
+        const carried = addPendingMark(seeded, mark);
+        if (carried.added) { seeded = carried.state; closingAdded += 1; seededAdded += 1; }
       }
-      if (closing === result.state) break;
+      if (!seededAdded) break;
       const closed = await commitPendingMarks({
         snapshot,
-        state: closing,
+        state: seeded,
         generation: lifecycle.generation,
         retainIneligible: true,
-        guardCurrentTurn: true,
       });
       if (!closed.applied.length) break;
       result = {
         ...closed,
+        state: withPendingMarks(closed.state, [...pendingMarks(closed.state), ...heldBack]),
         applied: [...result.applied, ...closed.applied],
         refused: [...result.refused.filter((mark) => !mark.retained), ...closed.refused],
-        waived: [...result.waived, ...closed.waived],
+        retained: [...result.retained.filter((mark) =>
+          !closed.applied.some((appliedMark) => appliedMark.id === mark.id)), ...closed.retained],
       };
     }
     persistence.state = result.state;
@@ -2012,12 +2353,12 @@ export function registerActiveContext(pi: any, options: {
       applied_marks: result.applied.length,
       refused_marks: result.refused.filter((mark) => !mark.retained).length,
       deferred_marks: result.retained.length,
-      waived_marks: result.waived.length,
       pending_marks: accounting.pending,
       agent_marks: accounting.agentMarks,
       ladder_marks: accounting.ladderMarks,
       peek_marks: peekAdded,
       topup_marks: topUpAdded,
+      refold_marks: refoldAdded,
       consolidation_marks: consolidationAdded,
       closing_consolidation_marks: closingAdded,
       absorbed_wedges: wedges.absorbed.length,
@@ -2033,36 +2374,6 @@ export function registerActiveContext(pi: any, options: {
     instrumentation.mutationsSinceHandoff += 1;
     instrumentation.lastMutationRequest = instrumentation.requests;
     instrumentation.lastMutationTokens = usedTokens;
-    const riderEpoch = commitEvent.seq;
-    if (persistence.state.rider?.epoch !== riderEpoch) {
-      const postAccounting = markAccounting(snapshot, persistence.state);
-      const remainder = unmarkedRemainder(snapshot, persistence.state, projectionCharsPerToken());
-      const pinnedMass = explicitProtectedMass(snapshot, persistence.state);
-      const pinnedShare = budgetTokens > 0
-        ? estimatedTokens(pinnedMass.bytes) / budgetTokens
-        : 0;
-      const riderText = contextRiderText({
-        toolName,
-        brandNoun,
-        pendingAgentMarks: postAccounting.agentMarks,
-        eligibleMarks: postAccounting.eligibleMarks,
-        freedTokens: postAccounting.freedTokens,
-        eligibleFreedTokens: postAccounting.eligibleFreedTokens,
-        anchors: remainder.candidates.slice(0, 3).map((candidate) => candidate.id),
-        pinnedShare,
-        maxPinnedShare: MAX_PINNED_SHARE,
-      });
-      persistence.state = { ...persistence.state, rider: { epoch: riderEpoch, text: riderText } };
-      emit("context.rider", {
-        epoch: riderEpoch,
-        chars: riderText.length,
-        anchors: Math.min(3, remainder.candidates.length),
-        pending_agent_marks: postAccounting.agentMarks,
-        eligible_marks: postAccounting.eligibleMarks,
-        pinned_share: pinnedShare,
-        max_pinned_share: MAX_PINNED_SHARE,
-      });
-    }
     let foldedToolResults = 0;
     let foldedSpans = 0;
     for (const applied of result.applied) {
@@ -2093,7 +2404,8 @@ export function registerActiveContext(pi: any, options: {
         end_id: wedge.endId,
         entries: wedge.entries,
         tokens: wedge.tokens,
-        threshold_tokens: MAX_WEDGE_ABSORB_TOKENS,
+        chars: wedge.chars,
+        threshold_chars: thresholds.minFoldChars,
       });
     }
     const epoch = {
@@ -2105,6 +2417,7 @@ export function registerActiveContext(pi: any, options: {
       ladderMarks: accounting.ladderMarks,
       peekMarks: peekAdded,
       topUpMarks: topUpAdded,
+      refoldMarks: refoldAdded,
       consolidationMarks: consolidationAdded,
       closingMarks: closingAdded,
       absorbedWedges: wedges.absorbed.length,
@@ -2114,8 +2427,6 @@ export function registerActiveContext(pi: any, options: {
       occupancyTokensBefore: usedTokens,
       depthFloorShare: commitDepthFloorShare(snapshot),
       reclaimFloorShare: COMMIT_RECLAIM_FLOOR_SHARE,
-      guardWaived: result.waived.length > 0,
-      waivedMarks: result.waived.length,
       appliedMarks: result.applied.length,
       refusedMarks: result.refused.filter((mark) => !mark.retained).length,
       deferredMarks: result.retained.length,
@@ -2124,8 +2435,6 @@ export function registerActiveContext(pi: any, options: {
       protectedStaleBytes: pinHeld.bytes,
       protectedStaleRefs: pinHeld.refs,
       retainedMarks: result.retained.length,
-      currentTurnRetained: result.retained.filter((mark) =>
-        markTouchesCurrentTurn(state, mark, guarded)).length,
       eligibleMarks: accounting.eligibleMarks,
       estimatedRewriteTokens: accounting.rewriteTokens,
       estimatedFreedTokens: accounting.freedTokens,
@@ -2186,59 +2495,14 @@ export function registerActiveContext(pi: any, options: {
     }));
   };
 
-  const applyAutomaticRung = async (
-    snapshot: ActiveContextSnapshot,
-    ratio: number,
-    rungOptions: {
-      toolOnly?: boolean;
-      waiverRatio?: number;
-    } = {},
-  ): Promise<Record<string, unknown> | null> => {
-    if (!persistence.state || ladder.automaticFailure || ladder.preparing) return null;
-    const rungSelectionOptions = { toolOnly: rungOptions.toolOnly };
-    const markLadderSelection = (): Record<string, unknown> | null => {
-      if (!persistence.state) return null;
-      const decision = selectAutomaticRung(snapshot, persistence.state, ratio, {
-        ...rungSelectionOptions,
-        claimed: claimedRefKeys(persistence.state),
-        claimedFoldIds: markedFoldIds(persistence.state),
-      });
-      const mark = decision
-        ? ladderSelectionMark({
-          snapshot, state: persistence.state, selection: decision, ordinal: markOrdinal(snapshot),
-        })
-        : null;
-      if (!mark) return null;
-      const addition = addPendingMark(persistence.state, mark);
-      if (!addition.added) return null;
-      persistence.state = addition.state;
-      ladder.pendingContextNote =
-        `Pending ${mark.mark} mark ${mark.id} recorded; no context bytes moved. ` +
-        "It applies at the next commit epoch.";
-      ladder.lastAutomaticAction = {
-        kind: "mark",
-        foldIds: [mark.id],
-        sourceIds: [],
-        markKind: mark.mark,
-        markOrigin: mark.origin,
-        pendingMarks: pendingMarks(persistence.state).length,
-        sourceBytesSaved: 0,
-      };
-      return ladder.lastAutomaticAction;
-    };
-    // MARKING ONLY. Every mutation the rung used to perform inline -- a prepared chapter,
-    // a tool fold, a refold, a consolidation, a chapter split -- now travels as a pending
-    // mark and lands at the boundary, which is the one point the projection changes.
-    // WHAT the rung decides is unchanged; WHEN it takes effect is.
-    return markLadderSelection();
-  };
   /**
-   * The one durable transaction. Whatever it wraps either lands with its state persisted
-   * or leaves the state it entered with, and a failure suspends folding by name rather
-   * than being retried quietly. Marking and committing both go through it, which is why
-   * a commit that vanishes at persistence (gate 122) and a suspension that says nothing
-   * (gate 123) are single properties rather than one per caller.
+   * A COMMIT, THROUGH THE SAME TRANSACTION AND THE SAME QUEUE. Two callers reach it: the
+   * compaction boundary, which is the ordinary one, and the projection fence, which is
+   * the emergency one. The fence cannot wait for a boundary because the request it is
+   * holding does not fit, so it commits in place; that is the one exception, and it is
+   * the exception that already existed.
    */
+
   const runAutomaticTransaction = async (
     snapshot: ActiveContextSnapshot,
     ratio: number,
@@ -2291,25 +2555,6 @@ export function registerActiveContext(pi: any, options: {
     ladder.actionQueue = queued.catch(() => undefined);
     return queued;
   };
-  const attemptAutomaticRung = (
-    snapshot: ActiveContextSnapshot,
-    ratio: number,
-    ctx: any,
-    phase: string,
-    rungOptions: {
-      toolOnly?: boolean;
-      waiverRatio?: number;
-    } = {},
-  ): Promise<Record<string, unknown> | null> => queueAutomatic(
-    snapshot, ratio, ctx, phase, () => applyAutomaticRung(snapshot, ratio, rungOptions),
-  );
-  /**
-   * A COMMIT, THROUGH THE SAME TRANSACTION AND THE SAME QUEUE. Two callers reach it: the
-   * compaction boundary, which is the ordinary one, and the projection fence, which is
-   * the emergency one. The fence cannot wait for a boundary because the request it is
-   * holding does not fit, so it commits in place; that is the one exception, and it is
-   * the exception that already existed.
-   */
   const attemptAutomaticCommit = (
     snapshot: ActiveContextSnapshot,
     ctx: any,
@@ -2495,14 +2740,11 @@ export function registerActiveContext(pi: any, options: {
               return { messages: event.messages };
             }
           }
-          if (selectAutomaticToolBatch(snapshot, persistence.state)[0]) mutationAttempted = true;
-          const action = await attemptAutomaticRung(
-            snapshot, measurements.latestRatio, ctx, "context",
-          );
-          if (action) {
-            mutationAttempted = true;
-            persistedSucceeded = true;
-          }
+          // NO EAGER LADDER MARKING (Shane, 2026-08-21): the rung used to stage a mark
+          // here on every measured response, which crowded the agent out of curation
+          // entirely -- by the time an agent looked, every eligible batch was already
+          // marked. The commit epoch fills fresh at commit time (topUpMarks), which is
+          // the only automatic marking there is.
         } else measurements.lastProviderMeasurement = observedMeasurement;
       } else {
         measurements.latestRatio = contextUsageRatio(measurements.lastProviderMeasurement);
@@ -2524,6 +2766,23 @@ export function registerActiveContext(pi: any, options: {
         updateStatus(ctx);
         return { messages: event.messages };
       }
+      // THE FRONTIER CUTS FIRST, and it costs the projection nothing to do so: a pending
+      // mark moves no bytes, so this runs BEFORE the band top and the fence and changes
+      // neither of their inputs. What it changes is WHEN the agent learns a fold exists,
+      // which is now while the material it covers is still in front of it.
+      advanceFoldFrontier(snapshot);
+      // BEFORE the fence, so an ordinary crossing is an ordinary commit and the fence is
+      // left holding only the requests that genuinely will not fit.
+      if (await enforceBandTop(snapshot, ctx)) {
+        mutationAttempted = true;
+        persistedSucceeded = true;
+        try { projected = projectWithAdvisory(snapshot); }
+        catch (error) {
+          suspendAutomatic(error, "projection", ctx);
+          abortUnsafeHardContext(snapshot, ctx);
+          return { messages: event.messages };
+        }
+      }
       const budgeted = await enforceProjectionBudget(snapshot, projected, ctx);
       projected = budgeted.projected;
       const reading = projectedTokenReading(projected);
@@ -2598,13 +2857,7 @@ export function registerActiveContext(pi: any, options: {
     if (measurements.latestRatio >= hardFenceRatio(measurement, ctx) && ladder.preparing) await ladder.preparing.promise;
     if (!sessionIdentityStillValid(ctx, capturedSessionId, capturedGeneration) ||
         !durableProviderMeasurementMatches(measurement)) return;
-    const action = await attemptAutomaticRung(
-      authoritativeSnapshotFor(ctx),
-      measurements.latestRatio,
-      ctx,
-      "message-end",
-    );
-    if (!action && measurementStateChanged && persistence.state && persistence.persisted &&
+    if (measurementStateChanged && persistence.state && persistence.persisted &&
         !sameStateProjection(persistence.state, persistence.persisted)) {
       await persistThroughActionQueue(ctx);
     }
@@ -2629,6 +2882,7 @@ export function registerActiveContext(pi: any, options: {
           model: ownValue(message, "model") ?? null,
           input_tokens: observation.inputTokens,
           cache_read_tokens: observation.cacheReadTokens,
+          cache_write_tokens: observation.cacheWriteTokens,
           total_tokens: providerTokens(message),
           projection_change: observation.change,
           provider_side_miss: observation.providerSideMiss,
@@ -2672,7 +2926,7 @@ export function registerActiveContext(pi: any, options: {
           durableProviderMeasurementMatches(measurements.lastProviderMeasurement)) {
         startPreparation(snapshot, measurements.latestRatio, ctx);
         if (measurements.latestRatio >= hardFenceRatio(snapshot) && ladder.preparing) await ladder.preparing.promise;
-        await attemptAutomaticRung(snapshot, measurements.latestRatio, ctx, "turn-end");
+        // No rung here either: turn end stages nothing (see the context-path note).
       }
       ladder.pendingManual = false;
       if (!ladder.automaticFailure) ladder.boundaryFailure = null;
@@ -3001,6 +3255,203 @@ export function registerActiveContext(pi: any, options: {
     );
   };
 
+  /**
+   * THE ONE STAGING PATH FOR FOLD MARKS (2026-08-23). The tool's fold action and the
+   * /fold-editor's user marks run THIS code and nothing else: span snapping, claim
+   * refusal, brief contract, prepareFold, replacement of a standing mark over the
+   * same span. Only the ORIGIN differs -- "agent" for the model, "user" for a human
+   * laying marks in the editor -- and origin changes nothing mechanical: a user mark
+   * counts toward the commit's coverage, answers with its commit arithmetic, and
+   * folds at the epoch exactly as an agent mark does.
+   */
+  /**
+   * THE WITHDRAWAL PATH, shared by the tool's unmark action and the editor's
+   * withdraw intent: same refusal for an unknown id, same persist, same status.
+   */
+  const withdrawMarks = async (ids: string[], ctx: any): Promise<Array<Record<string, unknown>>> => {
+    const requested = new Set(ids);
+    const before = pendingMarks(persistence.state!);
+    const kept = before.filter((mark) => !requested.has(mark.id));
+    const removed = before.filter((mark) => requested.has(mark.id));
+    const unknown = ids.filter((id) => !before.some((mark) => mark.id === id));
+    if (unknown.length) throw new Error(`No pending mark named ${unknown.join(", ")}`);
+    await persistManual(withPendingMarks(persistence.state!, kept), "unmark", ctx);
+    updateStatus(ctx);
+    return removed as Array<Record<string, unknown>>;
+  };
+
+  /**
+   * THE PIN CHANGE PATH, shared by the tool's pin/unpin actions and the editor's
+   * pin toggle: the pinned-share cap, protectEvidence, the canonical event, persist.
+   */
+  const applyProtectionChange = async (
+    snapshot: ActiveContextSnapshot,
+    ids: string[],
+    pin: boolean,
+    ctx: any,
+  ): Promise<void> => {
+    const refsBefore = persistence.state!.protected.length;
+    const nextProtection = protectEvidence(snapshot, persistence.state!, ids, pin);
+    if (pin) {
+      const capacity = servingCapacity(snapshot.contextWindow);
+      const prospectiveShare = capacity.budgetTokens > 0
+        ? estimatedTokens(explicitProtectedMass(snapshot, nextProtection).bytes) / capacity.budgetTokens
+        : 0;
+      if (prospectiveShare > MAX_PINNED_SHARE) {
+        throw new Error(
+          `protect refused: these pins would hold ${Math.round(prospectiveShare * 100)}% of the ` +
+          `working window raw, past the ${Math.round(MAX_PINNED_SHARE * 100)}% pinned-share cap. ` +
+          'Release earlier pins with {"action":"unpin","ids":["<entry-id>"]} first; ' +
+          "folding keeps entries exactly recoverable without pinning them.");
+      }
+    }
+    await persistManual(nextProtection, pin ? "pin" : "unpin", ctx);
+    emit("context.pin", {
+      pin,
+      ids: ids.join(","),
+      id_count: ids.length,
+      protected_refs_before: refsBefore,
+      protected_refs_after: persistence.state!.protected.length,
+    });
+    updateStatus(ctx);
+  };
+
+  const stageFoldMarks = async (
+    requests: BatchedMarkRequest[],
+    origin: MarkOrigin,
+    signal: AbortSignal,
+    ctx: any,
+    snapshot: ActiveContextSnapshot,
+  ): Promise<{ marks: Array<Record<string, unknown>>; corrections: SpanCorrection[]; staged: ActiveContextState }> => {
+      const resolved: Array<{
+        candidate: FoldCandidate;
+        brief?: string;
+        corrections: SpanCorrection[];
+        splitFrom: number;
+      }> = [];
+      for (const request of requests) {
+        const snapped = snapFoldCandidate(snapshot, persistence.state, request.ids, { allowProtected: true });
+        // AN AGENT'S SPAN IS TAKEN WHOLE (Shane, 2026-08-22). The bite-size cap was
+        // applied to manual marks too, and it was the only caller: the ladder never
+        // splits, because `selectAutomaticChapter` stops accumulating at the cap on its
+        // own. So the split existed solely to second-guess the one judgement the design
+        // wants to encourage, and it charged for it twice. One intended fold became five
+        // or ten placeholders, and every piece was handed the SAME brief, so each one
+        // claimed to describe a span it held a fraction of, while the correction text
+        // said "each with its own brief", which was never true.
+        //
+        // The cap stays for the ladder, where it was earned (2026-08-06 rep 6: one
+        // 60,432-byte chapter hid the fact the run needed). The difference is who chose
+        // the boundary. A ladder fold is a span nobody vouched for, so it is kept small
+        // enough to read back cheaply. An agent fold is a span the agent cut and wrote a
+        // brief for, and it stays navigable by a route that did not exist in 2026-08:
+        // peek takes offset and bytes, states the omitted middle, and reads any child id,
+        // so a large fold has a narrow read. An expand that will not fit is refused with
+        // a peek offered instead, so size costs a refusal rather than a window.
+        resolved.push({
+          candidate: snapped.candidate,
+          brief: request.brief,
+          corrections: snapped.corrections,
+          splitFrom: 0,
+        });
+      }
+      const corrections = resolved.flatMap((item) => item.corrections);
+      const marks: Array<Record<string, unknown>> = [];
+      let staged = persistence.state!;
+      for (const item of resolved) {
+        const { candidate } = item;
+        const alreadyPrepared = staged.folds.some((fold) =>
+          fold.id === foldIdFor(candidate.kind, candidate.parts));
+        const deferred = refsProtected(candidate.sourceRefs, staged, snapshot) ||
+          (candidate.kind === "tool-result" &&
+            refsProtected(candidate.sourceRefs, staged, snapshot));
+        // A MARK IS EDITABLE UNTIL IT COMMITS (Shane, 2026-08-21). Marking a span you
+        // already marked REPLACES the mark, so a brief written in haste is corrected by
+        // writing it again: the span is identical, the id derives from the span, and no
+        // byte has moved yet, so the correction costs nothing at all. After the commit
+        // the fold is standing and there is no rewrite verb, because rewriting a
+        // standing brief rewrites the projection at its placeholder; `reboundary`
+        // re-cuts the span instead, which was going to rewrite anyway.
+        const replacing = foldIdFor(candidate.kind, candidate.parts);
+        const claimed = markClaimingRef(staged, candidate.sourceRefs);
+        if (claimed && claimed.markId !== replacing) {
+          marks.push({
+            id: replacing,
+            kind: candidate.kind,
+            ok: false,
+            deferred: false,
+            reason: `Evidence ${claimed.entryId} is already held by pending mark ${claimed.markId}, ` +
+              `which folds at the next commit. Unmark ${claimed.markId} first if you want to ` +
+              "mark this span differently.",
+          });
+          continue;
+        }
+        const suppliedComplaint = item.brief === undefined
+          ? null
+          : briefContractComplaint(item.brief.trim(), snapshot.policy.maxBriefChars, snapshot.toolName);
+        if (suppliedComplaint !== null) {
+          marks.push({
+            id: foldIdFor(candidate.kind, candidate.parts),
+            kind: candidate.kind,
+            ok: false,
+            deferred: false,
+            reason: `Supplied brief rejected. ${suppliedComplaint}`,
+          });
+          continue;
+        }
+        const briefed = !deferred && !alreadyPrepared
+          ? await prepareFold({
+            candidate,
+            snapshot,
+            state: staged,
+            generation: lifecycle.generation,
+            brief: item.brief,
+            ctx,
+            signal,
+          })
+          : null;
+        const mark = foldMarkFor({
+          candidate,
+          brief: briefed?.fold.brief ?? item.brief ?? ladderBrief(snapshot, staged, candidate),
+          briefProvenance: briefed?.fold.provenance ??
+            (item.brief ? { kind: "supplied" } : { kind: "deterministic" }),
+          origin,
+          ordinal: markOrdinal(snapshot),
+        });
+        // Drop the standing mark over this exact span before adding, so a re-mark is a
+        // replacement rather than a duplicate refusal. `claimed` is this same mark by the
+        // check above, and the id is derived from the span, so the state after is the
+        // state a first mark with the new brief would have produced.
+        const replaced = claimed !== null;
+        if (replaced) {
+          staged = withPendingMarks(staged,
+            pendingMarks(staged).filter((standing) => standing.id !== replacing));
+        }
+        const addition = addPendingMark(staged, mark);
+        if (!addition.added) {
+          marks.push({ id: mark.id, kind: mark.kind, ok: false, deferred: false, reason: addition.reason });
+          continue;
+        }
+        staged = addition.state;
+        marks.push({
+          id: mark.id,
+          kind: mark.kind,
+          ok: true,
+          deferred,
+          ...(replaced ? { replaced: true } : {}),
+          ...(deferred
+            ? {
+              scheduled: "the span is still in the fresh window; this mark is held and folds at the " +
+                "first commit after it ages out",
+            }
+            : {}),
+          brief: mark.brief,
+          provenance: normalizeLegacyProvenance(mark.briefProvenance),
+        });
+      }
+      return { marks, corrections, staged };
+  };
+
   const executeAction = async (
     params: Record<string, unknown>,
     signal: AbortSignal | undefined,
@@ -3010,6 +3461,11 @@ export function registerActiveContext(pi: any, options: {
     if (!persistence.state) persistence.state = emptyActiveContextState(ctx.sessionManager.getSessionId());
     const executionArgumentsSha256 = sha256Value(params);
     const action = String(params.action ?? "");
+    // A deleted action is refused BY NAME rather than by "not enabled": the two are
+    // different facts, and an agent told a verb is merely off will keep offering it.
+    if (Object.prototype.hasOwnProperty.call(RETIRED_TOOL_ACTIONS, action)) {
+      throw new Error(RETIRED_TOOL_ACTIONS[action]);
+    }
     if (!allowedToolActionSet.has(action)) {
       throw new Error(`${toolName} action '${action}' is not enabled in this runtime`);
     }
@@ -3038,7 +3494,6 @@ export function registerActiveContext(pi: any, options: {
           persistence.state,
           statusOffset,
           statusLimit,
-          snapshot.policy.maxFoldSourceRefs,
           { diet: !paged },
         ),
         headroomTokens: currentCapacity(ctx).headroomTokens,
@@ -3056,7 +3511,6 @@ export function registerActiveContext(pi: any, options: {
           hardFenceRatio: hardFenceRatio(snapshot),
           thresholds: { ...snapshot.thresholds },
           zones: {
-            freshBoundary: snapshot.freshBoundary,
             budgetTokens: snapshot.budgetTokens,
           },
           responseReserve: currentCapacity(ctx).outputReservation,
@@ -3121,6 +3575,19 @@ export function registerActiveContext(pi: any, options: {
             state: persistence.state,
             ratio: measurements.latestRatio,
           }),
+          // WHAT THE RUNTIME HAS CUT AND NOT YET FOLDED, by name, because the agent needs
+          // an id to brief one and a notice it saw two turns ago is not a reference. Read
+          // from the LIVE state rather than the durable record: a frontier cut is derived
+          // from its span and is not written on its own, so the durable record is behind
+          // by design and only a brief or a commit brings it forward.
+          pendingFolds: pendingMarks(persistence.state).map((mark) => ({
+            id: mark.id,
+            kind: mark.kind,
+            tokens: estimatedTokens(markFreedBytes(snapshot, persistence.state!, mark)),
+            briefed: mark.briefProvenance?.kind === "supplied",
+            brief: mark.brief ?? null,
+            briefProvenance: mark.briefProvenance ? clone(mark.briefProvenance) : null,
+          })),
           nativeSummaries: "disabled",
           instrumentation: {
             enabled: true,
@@ -3152,12 +3619,15 @@ export function registerActiveContext(pi: any, options: {
     if (action === "peek") {
       const id = String(params.id ?? "").trim();
       if (!id) throw new Error("peek requires id");
+      if (params.ephemeral !== undefined && typeof params.ephemeral !== "boolean") {
+        throw new Error("peek ephemeral must be a boolean");
+      }
       const offset = boundedInteger(params.offset, 0, 0, 1_000_000_000, "offset");
       const sliceBytes = boundedInteger(
         params.bytes,
         PEEK_DEFAULT_MAX_BYTES,
         PEEK_MIN_SLICE_BYTES,
-        snapshot.policy.maxChapterChars,
+        snapshot.policy.maxSourceChars,
         "bytes",
       );
       const target = persistence.state.folds.find((item) => item.id === id);
@@ -3169,40 +3639,24 @@ export function registerActiveContext(pi: any, options: {
         requestedBytes: Math.max(0, Math.min(sliceBytes, target.sourceChars - offset)),
         children: childFoldIds(target),
       });
-      const payload = toolPayload(peekFoldSource({
-        foldId: id,
-        state: persistence.state,
-        entries: ctx.sessionManager.getEntries?.() ?? ctx.sessionManager.getBranch(),
-        sessionId: ctx.sessionManager.getSessionId(),
-        maximumBytes: sliceBytes,
-        offset,
-        toolName,
-      }));
-      return payload;
-    }
-    if (action === "rebrief") {
-      const id = String(params.id ?? "").trim();
-      if (!id) throw new Error("rebrief requires id");
-      const brief = typeof params.brief === "string" ? params.brief.trim() : "";
-      if (!brief) throw new Error("rebrief requires a nonempty brief");
-      if (brief.length > snapshot.policy.maxBriefChars) {
-        throw new Error(`rebrief brief must be at most ${snapshot.policy.maxBriefChars} characters`);
-      }
-      const fold = requireActiveFold(snapshot, persistence.state, id);
-      const previous = foldBrief(fold, persistence.state);
-      const briefs = { ...(persistence.state.briefs ?? {}), [id]: brief };
-      await persistManual({ ...persistence.state, revision: persistence.state.revision + 1, briefs }, action, ctx);
-      updateStatus(ctx);
-      return toolPayload({
-        version: 1,
-        action,
-        id,
-        brief,
-        previousBrief: previous,
-        durableRevision: persistence.state.revision,
-        activation: "the fold's placeholder and index rows now carry your brief; " +
-          "the exact source and its fold record are untouched.",
+      const payload = toolPayload({
+        ...peekFoldSource({
+          foldId: id,
+          state: persistence.state,
+          entries: ctx.sessionManager.getEntries?.() ?? ctx.sessionManager.getBranch(),
+          sessionId: ctx.sessionManager.getSessionId(),
+          maximumBytes: sliceBytes,
+          offset,
+          toolName,
+        }),
+        ...(peekIsEphemeral(params) ? {
+          ephemeral: "this result rides your context exactly until your next message; " +
+            "extract what your current task needs into that reply, which takes over its " +
+            "place. Peeking again is lossless and cheap; pass ephemeral false when you " +
+            "need these bytes standing for several turns",
+        } : { durable: "this result stays in your context like any other tool result" }),
       });
+      return payload;
     }
     if (action === "reboundary") {
       if (params.ids !== undefined) {
@@ -3230,7 +3684,10 @@ export function registerActiveContext(pi: any, options: {
         const recut = manualFoldCandidate(snapshot, persistence.state, snapped.ids, { allowProtected: true });
         const created: Array<Record<string, unknown>> = [];
         const correctedBriefs: Record<string, string> = {};
-        for (const part of splitCandidateBySize(snapshot, persistence.state, recut)) {
+        // Re-cut whole, for the same reason a mark is taken whole: the agent named this
+        // boundary, and splitting it hands one brief to several folds that each hold a
+        // fraction of what it describes.
+        for (const part of [recut]) {
           const durable = persistence.persistedFoldRecords.get(foldIdFor(part.kind, part.parts));
           const { preparedFold, nextState } = await prepareAndCommitExplicit({
             snapshot, candidate: part, brief: durable ? durable.fold.brief : supplied, ctx, signal,
@@ -3348,52 +3805,51 @@ export function registerActiveContext(pi: any, options: {
         activation: "durable immediately; projected on the next model call in this same turn",
       });
     }
-    if (action === "protect" || action === "unprotect") {
+    if (action === "pin" || action === "unpin") {
       const ids = stringIds(params.ids);
-      const refsBefore = persistence.state.protected.length;
-      const nextProtection = protectEvidence(snapshot, persistence.state, ids, action === "protect");
-      if (action === "protect") {
-        const capacity = servingCapacity(snapshot.contextWindow);
-        const prospectiveShare = capacity.budgetTokens > 0
-          ? estimatedTokens(explicitProtectedMass(snapshot, nextProtection).bytes) / capacity.budgetTokens
-          : 0;
-        if (prospectiveShare > MAX_PINNED_SHARE) {
-          throw new Error(
-            `protect refused: these pins would hold ${Math.round(prospectiveShare * 100)}% of the ` +
-            `working window raw, past the ${Math.round(MAX_PINNED_SHARE * 100)}% pinned-share cap. ` +
-            'Release earlier pins with {"action":"unprotect","ids":["<entry-id>"]} first; ' +
-            "folding keeps entries exactly recoverable without pinning them.");
-        }
-      }
-      await persistManual(nextProtection, action, ctx);
-      const refsAfter = persistence.state.protected.length;
-      emit("context.protect", {
-        protect: action === "protect",
-        ids: ids.join(","),
-        id_count: ids.length,
-        protected_refs_before: refsBefore,
-        protected_refs_after: refsAfter,
+      await applyProtectionChange(snapshot, ids, action === "pin", ctx);
+      const refsAfter = persistence.state!.protected.length;
+      // A PIN IS A CLAIM ON THE WINDOW, so it answers with the same picture a mark does.
+      // It never pays the drop, and saying so here is what stops an agent pinning its way
+      // to a coverage it does not have.
+      const pinCapacity = servingCapacity(snapshot.contextWindow);
+      const pinClaims = windowClaims({
+        snapshot,
+        state: persistence.state,
+        budgetTokens: pinCapacity.budgetTokens,
+        charsPerToken: projectionCharsPerToken(),
+      });
+      const pinCoverage = commitCoverage({
+        snapshot,
+        state: persistence.state,
+        usedTokens: pinCapacity.usedTokens,
+        budgetTokens: pinCapacity.budgetTokens,
       });
-      updateStatus(ctx);
       return toolPayload({
         version: 1,
         action,
         ids,
         protectedRefs: refsAfter,
-        activation: "durable immediately; projected on the next model call in this same turn",
+        pinnedTokens: pinClaims.pinnedTokens,
+        pinnedShare: pinClaims.pinnedShare,
+        maxPinnedShare: MAX_PINNED_SHARE,
+        markedTowardCommitTokens: pinClaims.markedTokens,
+        unclaimedTokens: pinClaims.unclaimedTokens,
+        commitTargetTokens: pinCoverage.targetTokens,
+        unmarkedAgainstCommitTokens: pinCoverage.remainingTokens,
+        activation: action === "pin"
+          ? "durable immediately; projected on the next model call in this same turn. " +
+            "Pinned entries stay RAW and are never folded, automatically or by a mark, so " +
+            "this is how you keep a span expanded. It frees nothing: the next commit still " +
+            "has to reach its drop from what is left, so pinned mass makes the rest of the " +
+            "window fold sooner rather than later."
+          : "durable immediately; projected on the next model call in this same turn. The " +
+            "released entries are foldable again and rejoin the next commit's candidates.",
       });
     }
     if (action === "unmark") {
-      const ids = stringIds(params.ids);
-      const requested = new Set(ids);
-      const before = pendingMarks(persistence.state);
-      const kept = before.filter((mark) => !requested.has(mark.id));
-      const removed = before.filter((mark) => requested.has(mark.id));
-      const unknown = ids.filter((id) => !before.some((mark) => mark.id === id));
-      if (unknown.length) throw new Error(`No pending mark named ${unknown.join(", ")}`);
-      await persistManual(withPendingMarks(persistence.state, kept), action, ctx);
-      updateStatus(ctx);
-      const accounting = markAccounting(snapshot, persistence.state);
+      const removed = await withdrawMarks(stringIds(params.ids), ctx);
+      const accounting = markAccounting(snapshot, persistence.state!);
       return toolPayload({
         version: 1,
         action,
@@ -3405,162 +3861,67 @@ export function registerActiveContext(pi: any, options: {
         activation: "the withdrawn marks will never be applied; no context bytes moved",
       });
     }
-    if (action === "fold") {
-      const requested = batchedMarkRequests(params);
-      const resolved: Array<{
-        candidate: FoldCandidate;
-        brief?: string;
-        corrections: SpanCorrection[];
-        splitFrom: number;
-      }> = [];
-      for (const request of requested) {
-        const snapped = snapFoldCandidate(snapshot, persistence.state, request.ids, { allowProtected: true });
-        const spanChars = candidateSpanChars(snapshot, persistence.state, snapped.candidate);
-        const parts = splitCandidateBySize(snapshot, persistence.state, snapped.candidate);
-        for (const [index, part] of parts.entries()) {
-          resolved.push({
-            candidate: part,
-            brief: request.brief,
-            corrections: index === 0
-              ? [
-                ...snapped.corrections,
-                ...(parts.length > 1
-                  ? [{
-                    from: request.ids,
-                    to: [],
-                    reason: `span was ${spanChars} chars, over the ${MAX_FOLD_SPAN_CHARS}-char bite-size cap; ` +
-                      `split into ${parts.length} sequential folds, each with its own brief`,
-                  }]
-                  : []),
-              ]
-              : [],
-            splitFrom: parts.length > 1 && index === 0 ? spanChars : 0,
-          });
-        }
-        if (parts.length > 1) {
-          emit("context.split", {
-            source: "agent",
-            span_chars: spanChars,
-            parts: parts.length,
-            cap_chars: MAX_FOLD_SPAN_CHARS,
-            fold_ids: "",
-          });
-        }
+    if (action === "brief") {
+      // THE ONE EDIT THAT IS FREE. A pending mark is not in the window, so writing its
+      // brief moves no bytes and costs no prefix cache; the brief reaches the projection
+      // only when the commit writes that placeholder for the first time. A STANDING fold
+      // is the opposite case and is refused by name: its placeholder is already in the
+      // window, and rewriting it breaks the cache from that point on, which is the
+      // rebrief deletion of 2026-08-21 read from the other side.
+      const id = String(params.id ?? "").trim();
+      if (!id) throw new Error("brief needs the id of a pending fold");
+      const standing = persistence.state!.folds.find((fold) => fold.id === id);
+      if (standing) {
+        throw new Error(
+          `${id} is a standing fold, not a pending one, so its brief is already in your ` +
+          "window and rewriting it would rewrite the projection from that placeholder on. " +
+          `Read it with ${toolName} {"action":"peek","id":"${id}"}, or re-cut the span with ` +
+          `${toolName} {"action":"reboundary","ids":[...]} if the boundary is wrong.`,
+        );
       }
-      const corrections = resolved.flatMap((item) => item.corrections);
-      const marks: Array<Record<string, unknown>> = [];
-      let staged = persistence.state;
-      for (const item of resolved) {
-        const { candidate } = item;
-        const alreadyPrepared = staged.folds.some((fold) =>
-          fold.id === foldIdFor(candidate.kind, candidate.parts));
-        const deferred = refsProtected(candidate.sourceRefs, staged, snapshot) ||
-          (candidate.kind === "tool-result" &&
-            toolRefsProtected(candidate.sourceRefs, staged, snapshot));
-        const suppliedComplaint = item.brief === undefined
-          ? null
-          : briefContractComplaint(item.brief.trim(), snapshot.policy.maxBriefChars, snapshot.toolName);
-        if (suppliedComplaint !== null) {
-          marks.push({
-            id: foldIdFor(candidate.kind, candidate.parts),
-            kind: candidate.kind,
-            ok: false,
-            deferred: false,
-            reason: `Supplied brief rejected. ${suppliedComplaint}`,
-          });
-          continue;
-        }
-        const briefed = !deferred && !alreadyPrepared
-          ? await prepareFold({
-            candidate,
-            snapshot,
-            state: staged,
-            generation: lifecycle.generation,
-            brief: item.brief,
-            ctx,
-            signal,
-          })
-          : null;
-        const mark = foldMarkFor({
-          candidate,
-          brief: briefed?.fold.brief ?? item.brief ?? ladderBrief(snapshot, staged, candidate),
-          briefProvenance: briefed?.fold.provenance ??
-            (item.brief ? { kind: "supplied" } : { kind: "deterministic" }),
-          origin: "agent",
-          ordinal: markOrdinal(snapshot),
-        });
-        const addition = addPendingMark(staged, mark);
-        if (!addition.added) {
-          marks.push({ id: mark.id, kind: mark.kind, ok: false, deferred: false, reason: addition.reason });
-          continue;
-        }
-        staged = addition.state;
-        marks.push({
-          id: mark.id,
-          kind: mark.kind,
-          ok: true,
-          deferred,
-          ...(deferred
-            ? {
-              scheduled: "the span is still in the fresh window; this mark is held and folds at the " +
-                "first commit after it ages out",
-            }
-            : {}),
-          brief: mark.brief,
-          provenance: normalizeLegacyProvenance(mark.briefProvenance),
-        });
+      const held = pendingMarks(persistence.state!);
+      const target = held.find((mark) => mark.id === id);
+      if (!target) {
+        const names = held.slice(0, 5).map((mark) => mark.id).join(", ");
+        throw new Error(
+          `No pending fold ${id}. ${held.length
+            ? `The folds waiting for a brief are: ${names}${held.length > 5 ? ", ..." : ""}.`
+            : "Nothing is pending right now, so there is nothing to brief."}`,
+        );
       }
-      await persistManual(staged, action, ctx);
+      const text = String(params.brief ?? "").trim();
+      const complaint = briefContractComplaint(text, snapshot.policy.maxBriefChars, snapshot.toolName);
+      if (complaint !== null) throw new Error(`Supplied brief rejected. ${complaint}`);
+      const nextState = {
+        ...persistence.state!,
+        revision: persistence.state!.revision + 1,
+        pendingMarks: held.map((mark) => mark.id === id
+          ? { ...mark, brief: text, briefProvenance: { kind: "supplied" as const } }
+          : mark),
+      };
+      persistence.state = nextState;
+      await persistManual(nextState, action, ctx);
       updateStatus(ctx);
-      const accounting = markAccounting(snapshot, persistence.state);
-      const held = pendingMarks(persistence.state).map((mark) => ({
-        id: mark.id,
-        kind: mark.kind,
-        tokens: estimatedTokens(markFreedBytes(snapshot, persistence.state!, mark)),
-      }));
-      const remainder = unmarkedRemainder(snapshot, persistence.state, projectionCharsPerToken());
-      const only = marks.length === 1 && marks[0].ok === true ? marks[0] : null;
+      emit("context.brief", { id, chars: text.length, origin: "agent" });
+      const accounting = markAccounting(snapshot, persistence.state!);
+      const remainder = unmarkedRemainder(snapshot, persistence.state!, projectionCharsPerToken());
       return toolPayload({
         version: 1,
         action,
-        scheduling: "epoch",
-        ok: marks.some((mark) => mark.ok === true),
-        deferredMarks: marks.filter((mark) => mark.deferred === true).length,
-        ...(only
-          ? {
-            id: only.id,
-            kind: only.kind,
-            brief: only.brief,
-            provenance: only.provenance,
-            deferred: only.deferred,
-            ...(only.scheduled ? { scheduled: only.scheduled } : {}),
-          }
-          : {}),
-        marks,
-        corrections,
+        id,
+        kind: target.kind,
+        brief: text,
+        provenance: "agent",
         argumentsSha256: executionArgumentsSha256,
-        durableRevision: persistence.state.revision,
+        durableRevision: persistence.state!.revision,
         pendingMarks: accounting.pending,
-        eligibleMarks: accounting.eligibleMarks,
-        retainedMarks: accounting.retainedMarks,
-        estimatedFreedWindowShare: accounting.freedBudgetShare,
-        estimatedEligibleWindowShare: accounting.eligibleFreedBudgetShare,
-        estimatedRewriteTokens: accounting.rewriteTokens,
-        held,
-        heldNote: "held until it ages out or the next fold event",
+        unbriefed: pendingMarks(persistence.state!)
+          .filter((mark) => mark.briefProvenance?.kind !== "supplied").map((mark) => mark.id),
         unmarkedSpans: remainder.spans,
         unmarkedTokens: remainder.tokens,
-        unmarkedShare: remainder.share,
-        unmarkedCandidates: remainder.candidates,
-        ...(guidance.actionResponses ? {
-          awareness: markAwarenessText({ held, remainder, toolName, brandNoun }),
-          activation: "accepted as pending marks; no context bytes moved, and nothing else in your " +
-            "context changed either. They apply together at the next commit epoch, which the runtime " +
-            "opens at the fold event. " +
-            "A mark over a still-fresh span is held, not refused: it is scheduled, and it folds at the " +
-            "first commit after that span ages out of the fresh window. " +
-            "Mark several spans in one call: this whole picture comes back with each one.",
-        } : {}),
+        activation: "durable immediately, and it costs your window nothing: this fold is " +
+          "pending, so the brief you just wrote is stored outside the projection and " +
+          "reaches it only when the commit folds this span. Nothing in your context moved.",
       });
     }
     throw new Error(`Unknown ${toolName} action '${action}'`);
@@ -3590,6 +3951,7 @@ export function registerActiveContext(pi: any, options: {
           marks_requested: requestedMarkCount(params),
           corrections_applied: corrections.length,
           arguments_sha256: sha256Value(params ?? {}),
+          ...(action === "peek" ? { ephemeral: peekIsEphemeral(params) } : {}),
         });
         for (const correction of corrections) {
           const from = denseOwnArrayValues(ownValue(correction, "from")) ?? [];
@@ -3609,6 +3971,7 @@ export function registerActiveContext(pi: any, options: {
         const result = await executeAction(params, signal, ctx);
         const corrections = denseOwnArrayValues(ownValue(ownValue(result, "details"), "corrections"));
         attempt(true, null, (corrections ?? []) as Array<Record<string, unknown>>);
+        if (action === "peek" && peekIsEphemeral(params)) ephemeralPeeks.add(toolCallId);
         return result;
       } catch (error) {
         attempt(false, error instanceof Error ? error.message : String(error), []);
@@ -3642,7 +4005,11 @@ export function registerActiveContext(pi: any, options: {
       if (!lifecycle.latestSnapshot) lifecycle.latestSnapshot = snapshot;
       const divider = args.indexOf(" -- ");
       const selector = (divider >= 0 ? args.slice(0, divider) : args).trim();
-      if (selector === "commit") {
+      // BARE /fold IS THE COMMIT (Shane, dogfooding 2026-08-22): staging is the
+      // normal accumulation and applying it is the default verb. The old bare behavior
+      // rescue-folded an auto-offered chapter, which read as the command ignoring the
+      // staged pile; a rescue now needs explicit ids.
+      if (!selector || selector === "commit") {
         const capacity = servingCapacity(snapshot.contextWindow);
         const occupancy = capacity.usedTokens !== null && capacity.budgetTokens > 0
           ? capacity.usedTokens / capacity.budgetTokens
@@ -3665,16 +4032,20 @@ export function registerActiveContext(pi: any, options: {
           committed
             ? `Committed ${ownValue(committed, "applied_marks") ?? 0} mark(s)${topUp ? " with automatic top-up" : ""}. ` +
               "Exact source remains expandable."
-            : "Nothing eligible to commit: no pending mark is outside the fresh tail.",
+            : "Nothing to commit: no staged mark could apply (pinned or already-folded spans hold).",
           "info",
         );
         return;
       }
       const supplied = (divider >= 0 ? args.slice(divider + 4) : "").trim() || undefined;
       const ids = selector ? selector.replace(/\.\./g, " ").split(/[\s,]+/).filter(Boolean) : [];
-      const candidate = ids.length
-        ? manualFoldCandidate(snapshot, persistence.state!, ids)
-        : selectAutomaticChapter(snapshot, persistence.state!) ?? selectAutomaticToolBatch(snapshot, persistence.state!)[0] ?? null;
+      if (!ids.length) {
+        throw new Error(
+          "Nothing to rescue without ids: /fold with no arguments commits every staged mark; " +
+            "name the span to fold now (/fold <start-id> [end-id] -- brief)",
+        );
+      }
+      const candidate = manualFoldCandidate(snapshot, persistence.state!, ids);
       if (!candidate) throw new Error("No exact stale rescue span is currently eligible");
       const stateBefore = persistence.state!;
       const persistedBefore = persistence.persisted ? clone(persistence.persisted) : null;
@@ -3721,6 +4092,200 @@ export function registerActiveContext(pi: any, options: {
     }
   };
 
+  /**
+   * /fold-editor, V2.2. The handler assembles a plain data snapshot of the working
+   * window and hands it to the view; the view holds no runtime reference and no
+   * mutation path. What changed in V2.2: raw entries are MARK POINTS, and a span
+   * laid down between two of them stages through `stageFoldMarks` -- the SAME
+   * validated path the tool's fold action runs -- with origin "user". The view
+   * computes nothing but the arithmetic it is handed (spanCost) and reports one
+   * intent (onStageMark); this handler owns every state transition.
+   */
+  const foldEditorCommandHandler = async (_args: string, ctx: any): Promise<void> => {
+    if (typeof ctx.ui?.custom !== "function") {
+      throw new Error("/fold-editor needs an interactive UI; use /fold-status for the text form");
+    }
+    const snapshot = lifecycle.latestSnapshot
+      ? authoritativeSnapshotFor(ctx)
+      : snapshotForEvent(ctx, ctx.sessionManager.buildSessionContext().messages);
+    if (!lifecycle.latestSnapshot) lifecycle.latestSnapshot = snapshot;
+    if (!persistence.state) throw new Error("The context window is empty; there is nothing to show yet");
+
+    // THE WOULD-BE FOLD SIZE (Shane, 2026-08-23). The footer's number while a span is
+    // being laid down is the runtime's own estimate -- span bytes over the mapped
+    // window at ESTIMATED_BYTES_PER_TOKEN -- so what the user sees before staging is
+    // what the staged mark answers with after it.
+    const spanCost = (from: number, to: number) => ({
+      entries: Math.abs(to - from) + 1,
+      tokens: estimatedTokens(spanBytes(snapshot, Math.min(from, to), Math.max(from, to) + 1)),
+    });
+
+    // Marks move no bytes until the commit, so window geometry cannot change while
+    // the editor holds it open; only pending state grows. Rebuilding against the SAME
+    // snapshot with fresh state keeps PROPOSED rows honest without re-deriving indices.
+    const buildData = () => {
+      const state = persistence.state!;
+      const capacity = servingCapacity(snapshot.contextWindow);
+      const occupancy = capacity.usedTokens !== null && capacity.budgetTokens > 0
+        ? capacity.usedTokens / capacity.budgetTokens
+        : null;
+      const accounting = markAccounting(snapshot, state);
+      return {
+        title: `pi-fold context editor · ${snapshot.sessionId.slice(0, 8)}`,
+        occupancy: {
+          usedTokens: capacity.usedTokens,
+          budgetTokens: capacity.budgetTokens,
+          commitOccupancy: thresholds.maxTarget,
+          commitDue: occupancy !== null && occupancy >= thresholds.maxTarget,
+        },
+        blocks: buildFoldEditorData(snapshot, state, {
+          foldRows: () => (state.folds ?? []).map((fold: any) => {
+            const row = foldIndexRow(fold, state, snapshot);
+            const entries = flattenFoldRefs(fold, state)
+              .map((ref) => {
+                const item = exactMapped(snapshot, ref);
+                const message = item?.message as Record<string, unknown> | undefined;
+                const role = String(item?.ref?.role ?? message?.role ?? "entry");
+                const content = message?.content;
+                let preview = "";
+                if (typeof content === "string") preview = content.slice(0, 300);
+                else if (Array.isArray(content)) {
+                  const firstText = content.find((part) => part?.type === "text");
+                  preview = typeof firstText?.text === "string" ? firstText.text.slice(0, 300) : "";
+                }
+                return { id: ref.entryId, role, preview: preview.replace(/\s+/g, " ") };
+              });
+            return {
+              id: String(row.id),
+              kind: String(row.kind ?? ""),
+              brief: String(row.brief ?? ""),
+              sourceCount: Number(row.sourceCount ?? 0),
+              startPosition: Number(row.startPosition),
+              endPosition: Number(row.endPosition),
+              entries,
+            };
+          }),
+          pendingMarkRefs: () => pendingMarks(state)
+            .filter((mark) => mark.mark === "fold")
+            .map((mark) => ({
+              id: mark.id,
+              origin: String(mark.origin),
+              brief: String(mark.brief ?? ""),
+              // WHAT THE STAGED MARK FREES, so a PROPOSED row states its size the
+              // way the footer prices an unstaged span.
+              ...(typeof markFreedBytes(snapshot, state, mark) === "number"
+                ? { tokens: estimatedTokens(markFreedBytes(snapshot, state, mark)) }
+                : {}),
+              entryIds: markSpanRefs(state, mark).refs
+                .map((ref) => ref.entryId)
+                .filter((entryId): entryId is string => Boolean(entryId)),
+            })),
+          mappedRange: (from: number, to: number) => {
+            const out: Array<{ id: string; role: string; preview: string; index?: number }> = [];
+            for (let index = from; index <= to; index += 1) {
+              const item = snapshot.mapped[index];
+              if (!item) continue;
+              const message = item.message as Record<string, unknown> | undefined;
+              const role = String(item.ref?.role ?? message?.role ?? "entry");
+              const content = message?.content;
+              // 300 chars, same as fold entries: the view shows 48 on the row and
+              // deepens to 240 on Enter, so a 48-char preview made detail a no-op.
+              let preview = "";
+              if (typeof content === "string") preview = content.slice(0, 300);
+              else if (Array.isArray(content)) {
+                const firstText = content.find((part) => part?.type === "text");
+                preview = typeof firstText?.text === "string" ? firstText.text.slice(0, 300) : "";
+              }
+              // THE INDEX IS THE MARK POINT: raw entries carry their mapped position so
+              // the view can price a span and name its two boundary ids.
+              out.push({
+                id: item.ref?.entryId ?? String(index),
+                role,
+                preview: preview.replace(/\s+/g, " "),
+                ...(item.ref?.entryId ? { index } : {}),
+              });
+            }
+            return out;
+          },
+          entryCount: snapshot.mapped.length,
+        }),
+        pending: {
+          count: pendingMarks(state).length,
+          agentMarks: accounting.agentMarks,
+          ladderMarks: accounting.ladderMarks,
+          userMarks: accounting.userMarks,
+          freedTokens: accounting.freedTokens,
+        },
+        pinned: state.protected.map((ref) => ref.entryId),
+      };
+    };
+
+    let view: FoldEditorView | null = null;
+    const runQueued = async (work: () => Promise<void>): Promise<void> => {
+      const operation = ladder.actionQueue.then(work);
+      ladder.actionQueue = operation.catch(() => undefined);
+      await operation;
+    };
+    const refreshAfter = (): void => {
+      if (view) view.refresh(buildData());
+    };
+    const editorActions = {
+      spanCost,
+      onStageMark: async (fromId: string, toId: string, brief?: string): Promise<void> => {
+        await runQueued(async () => {
+          const fresh = authoritativeSnapshotFor(ctx);
+          const request = brief && brief.trim()
+            ? { ids: [fromId, toId], brief: brief.trim() }
+            : { ids: [fromId, toId] };
+          const { marks, staged } = await stageFoldMarks(
+            batchedMarkRequests(request), "user",
+            new AbortController().signal, ctx, fresh);
+          // Refuse BEFORE persisting: an all-refused batch leaves state untouched and
+          // persisting it would be a no-op write against the same-state projection.
+          if (!marks.some((mark) => mark.ok === true)) {
+            const reason = marks.map((mark) => mark.reason).filter(Boolean).join("; ") ||
+              "the span was refused";
+            throw new Error(reason);
+          }
+          await persistManual(staged, "fold", ctx);
+          updateStatus(ctx);
+        });
+        safeNotify(ctx, "Staged user mark(s); they apply at the next commit epoch.", "info");
+        refreshAfter();
+      },
+      onWithdrawMark: async (markId: string): Promise<void> => {
+        let removed: Array<Record<string, unknown>> = [];
+        await runQueued(async () => {
+          removed = await withdrawMarks([markId], ctx) as Array<Record<string, unknown>>;
+        });
+        safeNotify(ctx,
+          `Withdrew ${removed.length} staged mark(s); no context bytes moved.`, "info");
+        refreshAfter();
+      },
+      onTogglePin: async (entryId: string): Promise<void> => {
+        const pinnedAlready = persistence.state!.protected
+          .some((ref: any) => ref.entryId === entryId);
+        await runQueued(async () => {
+          await applyProtectionChange(authoritativeSnapshotFor(ctx), [entryId], !pinnedAlready, ctx);
+        });
+        safeNotify(ctx, pinnedAlready
+          ? "Unpinned: the released entries rejoin the next commit's candidates."
+          : "Pinned raw: held through every fold; frees nothing toward the drop.", "info");
+        refreshAfter();
+      },
+    };
+    await ctx.ui.custom((
+      _tui: unknown,
+      theme: any,
+      keybindings: { matches(data: string, action: string): boolean } | null,
+      done: () => void,
+    ) => {
+      view = new FoldEditorView(buildData(), done, keybindings, theme, editorActions);
+      return view;
+    });
+    updateStatus(ctx);
+  };
+
   pi.registerTool(buildActiveContextTool({
     name: toolName,
     label: toolLabel,
@@ -3735,8 +4300,10 @@ export function registerActiveContext(pi: any, options: {
   for (const command of buildActiveContextCommands({
     statusName: commandNames.status,
     foldName: commandNames.fold,
+    editorName: "fold-editor",
     statusHandler: statusCommandHandler,
     foldHandler: foldCommandHandler,
+    editorHandler: foldEditorCommandHandler,
   })) {
     pi.registerCommand(command.name, {
       description: command.description,