fix(agent-loop): compose the session prefix before pre-step; hand it to the pressure gate

ds-review-bot critical (follow-up): on the first step of a resumed or seeded/forked instance, auto-compaction ran before runStep composed this instance's prefix, so the gate read the PREVIOUS instance's logged prefix from the header fold — a contributor that grew across resume/fork (skills added, AGENTS.md grown: exactly the environment-dependent case) could under-gate and ship an over-window first request. The loop now composes agent/session-prefix before the instance's first agent/pre-step (still once per instance; runStep just reads the cache), and agent/pre-step carries the composed prefix to its listeners. CompactService.compactIfNeeded gains the sessionPrefix parameter; BasicCompactService.estimatePressure gates on the handed value — the header-fold read is gone, so the estimate is exact at every step including a resumed/forked instance's first. Composition moving before the boundary snapshot also means a composing listener's session append now joins the CURRENT request (documented on the seam). New coverage: composition precedes pre-step and the seam receives the composed prefix; cancel and disposal landing inside the composition window drop the step cleanly; the compact gate test hands the prefix directly.
2026-07-08 20:30:10 +08:00
parent e6bd6cc9be
commit 765052a7d1
16 changed files with 244 additions and 107 deletions
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -8,7 +8,7 @@ This is the implementation tier of the compaction capability — see the [interf

 The abstract contract states only WHAT compaction does; this backend owns every HOW decision:

- **Token estimation** — `estimateContentTokens()`: chars divided by the `charsPerToken` config (default 4) with per-block structural overhead (`text`/`reasoning` = `ceil(len/charsPerToken) + 4`, `tool-call` from name + arguments, `tool-result` recursive, unknown blocks via JSON length). The pressure gate estimates the NEXT request via `estimatePressure()`: the logged session prefix (`EpochHeader.messagePrefix` from the header fold — the `agent/session-prefix` product rides every request in front of the history, so omitting it would under-estimate pressure by exactly the prefix) + the derived history + the system prompt.
+- **Token estimation** — `estimateContentTokens()`: chars divided by the `charsPerToken` config (default 4) with per-block structural overhead (`text`/`reasoning` = `ceil(len/charsPerToken) + 4`, `tool-call` from name + arguments, `tool-result` recursive, unknown blocks via JSON length). The pressure gate estimates the NEXT request via `estimatePressure()`: the session prefix (the `agent/session-prefix` product — composed by the loop BEFORE the pre-step seam and handed through it, so the gate counts the prefix this instance will actually send in front of the history, never a stale logged one) + the derived history + the system prompt.
 - **Retention policy** — `compactIfNeeded()` walks the surface nodes tail→head summing per-node token estimates, and retains the smallest tail-run of WHOLE units (a closed step, or a single no-step node such as a pre-step `user/message` or inter-step `steering/message`) whose total reaches `retainTokens`; everything older is compacted. Retention is **turn-agnostic** — turn boundaries play no role, so a single runaway turn that alone exceeds the window compacts its OWN early closed steps rather than being retained verbatim (the failure mode that motivated dropping turn-protection: a tool-heavy turn must stay compactable or the harness dies exactly when compaction is needed). The only structural guard is **tool-pairing balance**: the compacted region's edges are balanced cuts on the surface (no unanswered tool-call crosses either edge), so it never splits a step's `assistant/message` tool-calls from their `tool/result`s. When the only compactable content left is an un-splittable open tail step, it declines (returns `null`) and retries once an older step closes. **Single-unit overflow is out of scope, by design**: if one retained unit (a single closed step, or a large pasted `user/message`) ALONE exceeds the budget, compaction cannot help and the call may go out over-budget — bounding an individual unit's size is a separate concern. `compactRegion()` enforces tool-pairing balance strictly, throwing on a boundary that would split a step. `dsh-session` exports `isToolPairingBalanced` for the check.
 - **Dynamic convergence** — no static summary-length config pretends to bound what the model will write. If framing/estimator/system overhead leaves the compacted surface above threshold, `compactIfNeeded()` re-compacts the head checkpoint up to `compactionRetries` extra times; if it still cannot get below threshold, it throws. A summary whose estimated stored size is not smaller than the shadowed content fails closed before it mutates the surface.
 - **Summarization** — `summarize()`: a `GenerateOptions` request assembled via `BlockAssembler` with a fixed system prompt that asks for a structured checkpoint (Primary Request and Intent · Key Technical Concepts · Files and Code · Errors and Fixes · Pending Tasks · Current Work · Next Step · Critical Context), every section mandatory, exact paths/commands/identifiers preserved. The request is a direct one-shot `ctx.llm.stream()` call — NOT a loop step, so it does not run `agent/request` (that seam shapes the loop's conversation requests); the model comes from `summarizationModel` falling back to the agent's own, and per-call routing happens at `llm/stream` like any other direct call. `maxTokens` is the provider-side generation cap; only text blocks from the model's reply are kept before the checkpoint is stored (reasoning is dropped so private chain-of-thought never leaks into the durable summary, and a stray `tool-call` is dropped so the synthesized `user/message` summary cannot land an orphaned call with no matching `tool-result`). The compacted region is flattened to a plain-text transcript first: text and reasoning contribute their text, and every non-text block (tool-call, tool-result, plugin-added types) contributes a type-tagged placeholder (`[tool-call: name(args)]`, `[tool-result: …]`, …) so the summarizer is told what existed rather than silently dropping it.
--- a/packages/compact/compact-basic/src/index.ts
+++ b/packages/compact/compact-basic/src/index.ts
@@ -183,11 +183,11 @@ export class BasicCompactService extends CompactService {
      // log-only `compact/*` records and the replacement node cleanly outside a
      // step, so a crash mid-compaction leaves an inert orphan the turn-repair
      // closes — never a half-open step.
-      ctx.on('agent/pre-step', async (agent: Agent, _turn: number, _step: number, fullSystemPrompt: string, signal: AbortSignal) => {
+      ctx.on('agent/pre-step', async (agent: Agent, _turn: number, _step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal) => {
        try {
-          const result = await this.compactIfNeeded(agent, fullSystemPrompt, signal)
+          const result = await this.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
          if (result) {
-            const after = this.estimatePressure(agent.session, fullSystemPrompt)
+            const after = this.estimatePressure(agent.session, fullSystemPrompt, sessionPrefix)
            ctx.logger.info(
              `compaction: shadowed ${result.shadowedSeqs.length} surface nodes ` +
              `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, ` +
@@ -360,7 +360,7 @@ export class BasicCompactService extends CompactService {

  /**
   * The sole token-pressure gate: estimate the NEXT request's pressure — the
-   * logged session prefix + the surface-derived history + the system prompt
+   * session prefix + the surface-derived history + the system prompt
   * ({@link estimatePressure}) — and if it exceeds the threshold
   * (`contextWindow * thresholdRatio`), compact
   * the oldest surface nodes outside the `retainTokens` budget. The auto-
@@ -369,7 +369,11 @@ export class BasicCompactService extends CompactService {
   * carries it in front of the history (`EpochHeader.messagePrefix`) even
   * though it is not derived history — omitting it would under-estimate by
   * exactly the prefix and let a deployment at the window edge skip
-   * compaction, then ship an over-window request. Compaction itself can only
+   * compaction, then ship an over-window request. The loop composes the
+   * prefix BEFORE the pre-step seam and hands it through, so the gate sees
+   * this instance's actual prefix (never a previous instance's logged one —
+   * a resumed/forked instance whose contributor grew is gated on the grown
+   * value from its very first step). Compaction itself can only
   * shrink HISTORY: a prefix that alone approaches the window is a
   * configuration error no compactor fixes.
   *
@@ -395,13 +399,14 @@ export class BasicCompactService extends CompactService {
  override async compactIfNeeded(
    agent: Agent,
    fullSystemPrompt: string,
+    sessionPrefix: readonly Message[],
    signal: AbortSignal,
  ): Promise<CompactionResult | null> {
    const session = agent.session
    const threshold = Math.floor(this.config.contextWindow * this.config.thresholdRatio)
    let result: CompactionResult | null = null
    for (let attempt = 0; attempt <= this.config.compactionRetries; attempt++) {
-      const totalTokens = this.estimatePressure(session, fullSystemPrompt)
+      const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix)
      if (totalTokens < threshold) return result

      const range = this._compactableRange(session)
@@ -415,7 +420,7 @@ export class BasicCompactService extends CompactService {
      result = await this.compactRegion(session, range.start, range.end, agent, signal)
    }

-    const totalTokens = this.estimatePressure(session, fullSystemPrompt)
+    const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix)
    if (totalTokens < threshold) return result

    throw new Error(
@@ -425,19 +430,16 @@ export class BasicCompactService extends CompactService {
  }

  /**
-   * Estimated token pressure of the NEXT request: the logged session prefix
-   * (`EpochHeader.messagePrefix` from the header fold — request-only messages
-   * the loop sends in front of the derived history), the derived history, and
-   * the system prompt. The fold is exact from the loop instance's second
-   * request on (and from a resumed instance's first — the previous instance
-   * logged its prefix); it is absent only before a fresh session's first
-   * request, where the history is a single prompt and compaction is moot.
+   * Estimated token pressure of the NEXT request: the session prefix
+   * (`EpochHeader.messagePrefix` — request-only messages the loop sends in
+   * front of the derived history, composed before the pre-step seam and
+   * handed to the gate), the derived history, and the system prompt.
   * @param session - the session whose next request is being estimated.
   * @param fullSystemPrompt - the assembled system prompt (counts toward pressure).
+   * @param sessionPrefix - the instance's composed session prefix (counts toward pressure).
   * @returns the estimated token total the next request will carry.
   */
-  estimatePressure(session: Session, fullSystemPrompt: string): number {
-    const sessionPrefix = session.requestHeader()?.messagePrefix ?? []
+  estimatePressure(session: Session, fullSystemPrompt: string, sessionPrefix: readonly Message[]): number {
    return this.estimateTokens([...sessionPrefix, ...session.deriveMessages()], fullSystemPrompt)
  }

--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -557,27 +557,22 @@ describe('BasicCompactService.compactIfNeeded', () => {
    expect(result!.shadowedSeqs.length).toBeGreaterThan(0)
  })

-  it('counts the logged session prefix toward pressure (every request carries it in front of the history)', async () => {
+  it('counts the session prefix toward pressure (every request carries it in front of the history)', async () => {
    const svc = createTestService({ contextWindow: 200, thresholdRatio: 0.5, retainTokens: 10 })
    const session = multiTurnSession(3, 1) // 6 derived messages ≈ 84 estimated tokens — under the 100 threshold alone
    expect(await compactIfNeeded(svc, session, '', 'm', SIGNAL)).toBeNull()

-    // The loop records the composed agent/session-prefix product on the
-    // request header; it rides every request, so pressure must include it.
-    session.append('request/header', {
-      header: {
-        config: { model: 'm' },
-        messagePrefix: [
-          { role: 'user', content: [{ type: 'text', text: `opener one.${LONG_FIXTURE_TEXT}` }] },
-          { role: 'user', content: [{ type: 'text', text: `opener two.${LONG_FIXTURE_TEXT}` }] },
-        ],
-      },
-      reason: 'initial',
-    })
-    const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL)
+    // The loop composes the agent/session-prefix product before the pre-step
+    // seam and hands it to the gate; it rides every request, so pressure must
+    // include it — the same history now crosses the threshold.
+    const sessionPrefix: Message[] = [
+      { role: 'user', content: [{ type: 'text', text: `opener one.${LONG_FIXTURE_TEXT}` }] },
+      { role: 'user', content: [{ type: 'text', text: `opener two.${LONG_FIXTURE_TEXT}` }] },
+    ]
+    const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL, sessionPrefix)
    expect(result).not.toBeNull()
    // The prefix itself is NOT history: compaction shadowed surface nodes only.
-    expect(session.requestHeader()?.messagePrefix).toHaveLength(2)
+    expect(sessionPrefix).toHaveLength(2)
  })

  it('returns the first compaction result when a zero-retry pass converges after the loop', async () => {
@@ -1005,8 +1000,9 @@ function compactIfNeeded(
  fullSystemPrompt: string,
  model: string,
  signal: AbortSignal,
+  sessionPrefix: readonly Message[] = [],
 ) {
-  return svc.compactIfNeeded(stubAgent(session, model), fullSystemPrompt, signal)
+  return svc.compactIfNeeded(stubAgent(session, model), fullSystemPrompt, sessionPrefix, signal)
 }

 function compactRegion(
@@ -1174,7 +1170,7 @@ describe('BasicCompactService.summarize (real ctx.llm.stream)', () => {
 describe('BasicCompactService auto-compaction (agent/pre-step listener)', () => {
  /** Fire the agent/pre-step serial checkpoint as the loop does. */
  function firePreStep(ctx: Context, agent: Agent, step: number, fullSystemPrompt: string): Promise<unknown> {
-    return ctx.serial('agent/pre-step', agent, 1, step, fullSystemPrompt, SIGNAL)
+    return ctx.serial('agent/pre-step', agent, 1, step, fullSystemPrompt, [], SIGNAL)
  }

  it('compacts (mutating the surface) when over threshold', async () => {
@@ -1276,7 +1272,7 @@ describe('BasicCompactService auto-compaction (agent/pre-step listener)', () =>
    const session = multiTurnSession(5, 1)
    const agent = stubAgent(session, 'agent-model')

-    await ctx.serial('agent/pre-step', agent, 1, 1, '', SIGNAL)
+    await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL)

    expect(adapter.lastOptions?.model).toBe('routed-model')
    expect(session.events.some(e => e.type === 'compact/summary')).toBe(true)
@@ -1415,7 +1411,7 @@ describe('BasicCompactService edge cases', () => {
    const session = multiTurnSession(4, 1)
    const agent = stubAgent(session, 'test-model')

-    await ctx.serial('agent/pre-step', agent, 1, 1, '', SIGNAL)
+    await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL)
    expect(session.events.some(e => e.type === 'compact/summary')).toBe(true)
    // The surface was mutated; the head message is the framed summary checkpoint.
    expect(session.deriveMessages()[0]!.content).toContainEqual({ type: 'text', text: 'SUMMARY' })
@@ -1495,7 +1491,7 @@ describe('BasicCompactService edge cases', () => {
    const agent = stubAgent(session, 'test-model')
    const before = session.surface.nodes.length

-    await ctx.serial('agent/pre-step', agent, 1, 1, '', SIGNAL)
+    await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL)
    // The failure was swallowed; the surface is untouched and a warning logged.
    expect(session.surface.nodes.length).toBe(before)
    expect(session.events.some(e => e.type === 'compact/summary')).toBe(false)
@@ -1512,7 +1508,7 @@ describe('BasicCompactService edge cases', () => {
    const agent = stubAgent(session, 'test-model')
    const bigSystem = 'x'.repeat(900) // ceil(900/4)=225 > threshold 200

-    await ctx.serial('agent/pre-step', agent, 1, 1, bigSystem, SIGNAL)
+    await ctx.serial('agent/pre-step', agent, 1, 1, bigSystem, [], SIGNAL)
    expect(session.events.some(e => e.type === 'compact/start')).toBe(false)
    expect(svc.summarizeCalls.length).toBe(0)
  })
--- a/packages/compact/compact/src/index.ts
+++ b/packages/compact/compact/src/index.ts
@@ -22,6 +22,7 @@
 */

 import { Context, Service } from 'cordis'
+import type { Message } from '@deepseek-ai/dsh-llm'
 import type { Session } from '@deepseek-ai/dsh-session'
 import type { CompactionResult } from './types.ts'

@@ -68,16 +69,20 @@ export abstract class CompactService extends Service {
  /**
   * Check token pressure and compact if the conversation is too large.
   *
-   * Estimates the current surface-derived history size (including the system
-   * prompt), and if it exceeds the backend's threshold, compacts an older range
+   * Estimates the NEXT request's size — the session prefix, the
+   * surface-derived history, and the system prompt — and if it exceeds the
+   * backend's threshold, compacts an older range
   * via {@link compactRegion}, keeping recent context intact. Returns `null`
   * when no compaction is needed.
   *
   * Scope and guarantees a backend MUST honor:
-   * - **Surface-derived history only.** The decision is made against the history
-   *   derived from the session surface — the only thing compaction can act on.
-   *   Non-surface context injected downstream (into the request `messages` by a
-   *   later listener) is out of this accounting by construction.
+   * - **Compaction acts on surface-derived history only**, but the ESTIMATE
+   *   counts everything the request carries: the loop composes the session
+   *   prefix before the pre-step seam fires and hands it here, so the gate
+   *   sees the prefix this instance will actually send (`EpochHeader.messagePrefix`
+   *   — request-only, never derived history). Non-surface context injected
+   *   downstream (into the request `messages` by a later listener) is out of
+   *   this accounting by construction.
   * - **Head-anchored, best-effort.** Auto-compaction consolidates from the
   *   surface HEAD up to a balanced tool-pairing cutoff, so a prior head
   *   checkpoint is
@@ -88,10 +93,14 @@ export abstract class CompactService extends Service {
   * - **Single-unit overflow is out of scope.** If a single retained unit (one
   *   closed step, or a large free node such as a pasted `user/message`) ALONE
   *   exceeds the budget, compaction cannot help and the call may go out
-   *   over-budget. Bounding an individual unit's size is a separate concern.
+   *   over-budget. Bounding an individual unit's size is a separate concern —
+   *   as is a session prefix that alone approaches the window (a
+   *   configuration error no compactor fixes: compaction cannot shrink the
+   *   prefix).
   *
   * @param agent - agent context owning the session surface and model options.
   * @param fullSystemPrompt - assembled system prompt, counted toward the estimate.
+   * @param sessionPrefix - the instance's composed session prefix, counted toward the estimate.
   * @param signal - cancellation signal. A backend summarizing via
   *   `ctx.llm.stream()` MUST forward this into the call's `GenerateOptions.signal`
   *   so an abort/dispose tears down the in-flight summarization rather than
@@ -101,6 +110,7 @@ export abstract class CompactService extends Service {
  abstract compactIfNeeded(
    agent: CompactAgentContext,
    fullSystemPrompt: string,
+    sessionPrefix: readonly Message[],
    signal: AbortSignal,
  ): Promise<CompactionResult | null>

--- a/packages/compact/compact/tests/compact.spec.ts
+++ b/packages/compact/compact/tests/compact.spec.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CompactService } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
+import type { Message } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { CompactAgentContext } from '@deepseek-ai/dsh-compact'

@@ -18,6 +19,7 @@ class StubCompactService extends CompactService {
  override async compactIfNeeded(
    _agent: CompactAgentContext,
    _fullSystemPrompt: string,
+    _sessionPrefix: readonly Message[],
    signal: AbortSignal,
  ): Promise<CompactionResult | null> {
    this.lastSignal = signal
@@ -78,7 +80,7 @@ describe('CompactService seam', () => {
    const ctx = new Context()
    const svc = new StubCompactService(ctx)
    const session = new Session(SessionId('s'))
-    expect(await svc.compactIfNeeded(stubAgent(session), '', new AbortController().signal)).toBeNull()
+    expect(await svc.compactIfNeeded(stubAgent(session), '', [], new AbortController().signal)).toBeNull()
  })

  it('compact/* events merge into SessionEventMap and are log-only', async () => {
@@ -107,7 +109,7 @@ describe('CompactService seam', () => {
    await svc.compactRegion(session, 0, 0, stubAgent(session, 'm'), controller.signal)
    expect(svc.lastSignal).toBe(controller.signal)

-    await svc.compactIfNeeded(stubAgent(session), '', controller.signal)
+    await svc.compactIfNeeded(stubAgent(session), '', [], controller.signal)
    expect(svc.lastSignal).toBe(controller.signal)
  })
 })
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -55,12 +55,13 @@ forever:
    STEP loop:
      drain steering
      assembly = systemPrompt.assemble({agent})  ⟵ renderPrompt(assembly) IS the full prompt
-      await serial agent/pre-step        ⟵ surface mutation (compaction) outside the step
+      prefix ??= waterfall agent/session-prefix   ⟵ once per instance (first step): frozen
+                                                session prefix; on the header, never history
+      await serial agent/pre-step(…, prefix)  ⟵ surface mutation (compaction) outside the step;
+                                                pressure gates see the prefix the request carries
      boundary = session.deriveMessages()   ⟵ reconstruction boundary: same sync frame,
      session('step/start')                     strictly before step/start
      config = waterfall agent/request       ⟵ frozen seed; return a replacement to switch
-      prefix ??= waterfall agent/session-prefix   ⟵ once per instance (first request): frozen
-                                                session prefix; on the header, never history
      session('request/header'[-delta])      ⟵ the header event this request owes the log
      stream llm.stream(freeze({header..., messages: prefix+boundary})) → session('assistant/chunk')
      message = waterfall agent/step-result
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -157,13 +157,14 @@ export interface LoopHandle {
 *       drain steering → session('steering/message')  ⟵ catches late steering
 *       assembly = ctx.systemPrompt.assemble({agent}) ⟵ waterfall system-prompt/assemble; renderPrompt
 *                                                        (persona section + {{variables}}) IS the full prompt
- *       await ctx.serial('agent/pre-step')            ⟵ surface mutation (compaction) OUTSIDE the step
+ *       prefix ??= waterfall agent/session-prefix     ⟵ once per loop instance (first step): frozen
+ *                                                        session prefix; logged on the header, never
+ *                                                        session history
+ *       await ctx.serial('agent/pre-step', …, prefix) ⟵ surface mutation (compaction) OUTSIDE the step;
+ *                                                        pressure gates see the prefix the request carries
 *       boundary = session.deriveMessages()           ⟵ the reconstruction boundary: snapshot in the
 *       session('step/start')                            same sync frame, strictly before step/start
 *       config = waterfall agent/request(config)      ⟵ frozen seed; a returned replacement switches
- *       prefix ??= waterfall agent/session-prefix     ⟵ once per loop instance (first request):
- *                                                        frozen session prefix; logged on the header,
- *                                                        never session history
 *       session('request/header'|'request/header-delta')  ⟵ the header event this request owes the
 *                                                        log (initial/resume anchor, delta, fallback)
 *       req = freeze({header..., messages: prefix+boundary, sessionId, signal})
@@ -475,6 +476,41 @@ async function runTurn(
        break
      }

+      // Compose the session prefix ONCE per loop instance, lazily before the
+      // instance's first pre-step: request-only messages placed in front of
+      // the ENTIRE derived history on every request this instance sends. It
+      // MUST precede the pre-step seam so compaction gates on THIS instance's
+      // prefix — reading a previous instance's logged prefix would let a
+      // resumed/forked instance whose contributor grew skip compaction and
+      // ship an over-window first request. The result is deep-cloned
+      // (decoupled from listener-held references), deep-frozen, and cached on
+      // the transmission bookkeeping, so reuse is structural — the prefix
+      // cannot change mid-session and the provider prefix cache holds by
+      // construction (resume = a new instance = a recompose, anchored by its
+      // 'resume' snapshot). The prefix is not session history — the header
+      // event in runStep is its only durable record
+      // (EpochHeader.messagePrefix). The frozen empty seed serves both the
+      // listener chain and the no-listener fallback: a contribution is a
+      // RETURNED extension of `await next()`, never an in-place push. This
+      // runs OUTSIDE the step, before the boundary snapshot: a composing
+      // listener's session append lands before the boundary and joins the
+      // CURRENT request.
+      if (transmission.sessionPrefix === undefined) {
+        const emptyPrefix: Message[] = deepFreeze([])
+        transmission.sessionPrefix = deepFreeze(structuredClone(await ctx.waterfall(
+          'agent/session-prefix', agent, emptyPrefix, abort.signal,
+          () => Promise.resolve(emptyPrefix),
+        )))
+      }
+
+      // Interruption landing during prefix composition: mirror the assembly
+      // window above — drop the about-to-start step without running the seam.
+      if (handle.isCancelled() || handle.isDisposed()) {
+        handle.setAbort(undefined)
+        reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() }
+        break
+      }
+
      // Pre-step surface-mutation checkpoint (compaction), fired OUTSIDE the
      // step: after `turn/start` (and the prior step's close) but before
      // `step/start`, so a compaction's log-only `compact/*` records and its
@@ -485,8 +521,10 @@ async function runTurn(
      // concurrent listeners cannot interleave their `session.append`s. A
      // throwing listener escapes to the outer catch, which closes the (not-yet-
      // open) step as a no-op and ends the turn via failTurn — a broken
-      // pre-step plugin ends the turn, not the loop.
-      await ctx.serial('agent/pre-step', agent, turn, step, fullSystemPrompt, abort.signal)
+      // pre-step plugin ends the turn, not the loop. The composed session
+      // prefix rides along so token-pressure listeners count everything the
+      // request will actually carry.
+      await ctx.serial('agent/pre-step', agent, turn, step, fullSystemPrompt, transmission.sessionPrefix, abort.signal)

      // Interruption landing during the pre-step seam: do not open an empty step.
      if (handle.isCancelled() || handle.isDisposed()) {
@@ -722,27 +760,10 @@ async function runStep(
    throw new Error(`agent "${agent.id}" has no model: set AgentOptions.model or supply one via the agent/request waterfall`)
  }

-  // Compose the session prefix ONCE per loop instance, lazily on its first
-  // request-building step: request-only messages placed in front of the
-  // ENTIRE derived history on every request this instance sends. The result
-  // is deep-cloned (decoupled from listener-held references), deep-frozen,
-  // and cached on the transmission bookkeeping, so reuse is structural — the
-  // prefix cannot change mid-session and the provider prefix cache holds by
-  // construction (resume = a new instance = a recompose, anchored by its
-  // 'resume' snapshot). The prefix is not session history — the header event
-  // below is its only durable record (EpochHeader.messagePrefix), which
-  // keeps the request a pure function of the log. The frozen empty seed
-  // serves both the listener chain and the no-listener fallback: a
-  // contribution is a RETURNED extension of `await next()`, never an
-  // in-place push.
-  if (transmission.sessionPrefix === undefined) {
-    const emptyPrefix: Message[] = deepFreeze([])
-    transmission.sessionPrefix = deepFreeze(structuredClone(await ctx.waterfall(
-      'agent/session-prefix', agent, emptyPrefix, signal,
-      () => Promise.resolve(emptyPrefix),
-    )))
-  }
-  const sessionPrefix = transmission.sessionPrefix
+  // The session prefix was composed (once per instance) before this step's
+  // pre-step seam — the caller guarantees it, so the cache is always set here.
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- runTurn composes the prefix before every runStep call
+  const sessionPrefix = transmission.sessionPrefix!

  // The request header (the log's request/header* vocabulary): canonical form,
  // recorded before dispatch so the log always explains the request —
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -166,6 +166,69 @@ describe('Agent.cancel()', () => {
    expect(reasons.length).toBe(2)
  })

+  it('cancel from inside the agent/session-prefix waterfall drops the step (prefix-composition window)', async () => {
+    const adapter = new MockAdapter([textResponse('should not stream')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    // Prefix composition runs before the pre-step seam on the instance's first
+    // step; a cancel landing inside it must drop the about-to-start step
+    // without running the seam or the model.
+    let streamed = false
+    ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true })
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => {
+      agent.cancel('from prefix composition')
+      return next()
+    })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(streamed).toBe(false)
+    expect(reasons).toEqual([{ kind: 'aborted', reason: 'from prefix composition' }])
+  })
+
+  it('disposal from inside the agent/session-prefix waterfall ends the turn disposed (prefix-composition window)', async () => {
+    const adapter = new MockAdapter([textResponse('should not stream')])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    ctx.llm.registerAdapter(['mock'], adapter)
+
+    const handle = ctx.agents.create({
+      agentId: AgentId('a-dispose-prefix'),
+      sessionId: SessionId('dispose-prefix-session'),
+      agentOptions: { model: 'mock' },
+    })
+    const agent = handle.agent as ReactLoopAgent
+
+    let disposalDone: Promise<void> | undefined
+    let streamed = false
+    ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true })
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => {
+      disposalDone = handle.dispose()
+      return next()
+    })
+
+    send(agent, 'go')
+    await new Promise(resolve => setTimeout(resolve, 0))
+    await disposalDone
+    await agent.done
+
+    // No step opened, no model call ran, and the turn closed disposed.
+    expect(streamed).toBe(false)
+    expect(adapter.requests).toHaveLength(0)
+    const turnEnd = agent.session.events.findLast(e => e.type === 'turn/end')
+    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' })
+  })
+
  it('cancel from a synchronous turn/start session-event listener drops the step (step-start window)', async () => {
    const adapter = new MockAdapter([textResponse('should not stream')])
    const ctx = await harness(adapter)
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -352,6 +352,33 @@ describe('agent/session-prefix', () => {
    expect(agent.session.deriveMessages()[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'go' }] })
  })

+  it('composes before the first pre-step and hands the prefix to the seam (pressure gates see the real value)', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    const reminder: Message = { role: 'user', content: [{ type: 'text', text: 'opener' }] }
+    const order: string[] = []
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
+      order.push('compose')
+      return [reminder, ...await next()]
+    })
+    const seen: (readonly Message[])[] = []
+    ctx.on('agent/pre-step', (_agent, _turn, _step, _system, sessionPrefix) => {
+      order.push('pre-step')
+      seen.push(sessionPrefix)
+    })
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    // Composition precedes the pre-step seam, and the seam receives THIS
+    // instance's composed prefix — a token-pressure gate (compaction) counts
+    // what the request will actually carry, never a stale logged prefix.
+    expect(order).toEqual(['compose', 'pre-step'])
+    expect(seen[0]).toEqual([reminder])
+  })
+
  it('the canonical prepend pattern composes contributions in registration order', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -43,9 +43,9 @@ Turn and step boundaries are NOT mirrored as `agent/*` emits: a consumer that ne

 - `agent/session-start` (emit) — fired once before the first turn; a listener seeds context via `agent.inject()` (it cannot veto startup).
 - `agent/prompt-submit` — decide what happens to one drained queued message before it becomes a `user/message`: `PromptDecision` = `allow` (optionally rewriting the prompt `content` or attaching `additionalContext`) or `block` (drop it; a batch whose every prompt is blocked opens a zero-step turn that ends `rejected`). Maps onto Claude Code's `UserPromptSubmit`.
- `agent/pre-step` (serial) — mutate the session surface before the step opens and history is derived (compaction). Fires after `turn/start` and before `step/start`, so a listener's appended events land outside the step.
+- `agent/pre-step` (serial) — mutate the session surface before the step opens and history is derived (compaction). Fires after `turn/start` and before `step/start`, so a listener's appended events land outside the step; carries the assembled system prompt and the instance's composed session prefix so a token-pressure gate counts everything the request will carry.
 - `agent/request` — shape the call config before the model call: a frozen `LlmCallConfig` seed in, a replacement out (model switching, sampling overrides). Content is not shapeable here — every request is a pure function of the session log ([reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)); the loop logs whatever config the request actually uses as a `request/header*` event
- `agent/session-prefix` — compose the session prefix: request-only messages placed in front of the ENTIRE derived history on every request. Fired ONCE per loop instance, lazily on its first request; the composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the anchoring `request/header` snapshot, and reused verbatim afterwards — the prefix cannot change mid-session, so the provider prefix cache holds by construction (resume = a new instance = a recompose, attributably anchored by its `'resume'` snapshot). The home for session-stable openers that must not become durable history (a skills catalog, an AGENTS.md digest); `deriveMessages()` never returns it. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, `tools/post-execute` `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter
+- `agent/session-prefix` — compose the session prefix: request-only messages placed in front of the ENTIRE derived history on every request. Fired ONCE per loop instance, lazily before its first pre-step (so pressure gates see this instance's real prefix, never a previous instance's logged one); the composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the anchoring `request/header` snapshot, and reused verbatim afterwards — the prefix cannot change mid-session, so the provider prefix cache holds by construction (resume = a new instance = a recompose, attributably anchored by its `'resume'` snapshot). The home for session-stable openers that must not become durable history (a skills catalog, an AGENTS.md digest); `deriveMessages()` never returns it. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, `tools/post-execute` `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter
 - `agent/step-result` — post-process the assembled assistant message before tool dispatch (validates what the log records)
 - `agent/turn-continuation` — override the continue/stop decision via `ContinuationDecision` = `{action:'stop'}` or `{action:'continue', reason?}` (a `continue` `reason` is recorded as next-step steering in the same turn — the typed `/goal` pattern). Force-continue `/loop`, force-stop budget guard.

--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -333,21 +333,28 @@ declare module 'cordis' {
     * value; this event is typed and documented as `void`, so listeners must not
     * return a semantic veto value. `fullSystemPrompt` is the assembled prompt a
     * listener needs to measure pressure (the system prompt counts toward the
-     * budget). `signal` cancels any in-flight work a listener starts (e.g. a
+     * budget), and `sessionPrefix` is the instance's composed
+     * {@link agent/session-prefix} product for the same reason — every request
+     * carries it in front of the derived history, and it is composed BEFORE
+     * this seam fires precisely so a pressure gate counts the prefix the
+     * request will actually send (never a stale logged one). `signal` cancels
+     * any in-flight work a listener starts (e.g. a
     * summarization model call).
     * @param agent - the agent about to open the step.
     * @param turn - the already-open turn this step belongs to.
     * @param step - the number of the step about to start.
     * @param fullSystemPrompt - the assembled prompt, for measuring token pressure.
+     * @param sessionPrefix - the instance's frozen session prefix, for the same measurement.
     * @param signal - aborts in-flight listener work when the turn is torn down.
     * @mode serial
     */
-    // TODO: `fullSystemPrompt` is a smell on a generic per-step seam — compaction
-    // is its only consumer, so a wide event carries a string just one listener
+    // TODO: `fullSystemPrompt`/`sessionPrefix` are a smell on a generic
+    // per-step seam — compaction
+    // is their only consumer, so a wide event carries payloads just one listener
    // reads. Revisit if no second consumer appears: e.g. hand listeners a lazy
    // prompt provider, or move token-pressure measurement behind a
    // compaction-specific seam instead of the shared pre-step checkpoint.
-    'agent/pre-step'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, signal: AbortSignal): Promise<void> | void
+    'agent/pre-step'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void
    /**
     * Waterfall: decide what happens to ONE drained queued message before it
     * becomes a `user/message` — allow (optionally rewriting the prompt bytes or
@@ -389,13 +396,18 @@ declare module 'cordis' {
     * Waterfall: compose the SESSION PREFIX — request-only messages placed in
     * front of the ENTIRE derived history (directly after the provider's
     * system slot) on every request this loop instance sends. Fired ONCE per
-     * loop instance, lazily on its first request-building step; the composed
+     * loop instance, lazily before its first step's {@link agent/pre-step}
+     * seam — BEFORE the pre-step so a token-pressure gate (compaction) counts
+     * the prefix this instance will actually send, never a previous
+     * instance's logged one. The composed
     * result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the
     * instance's anchoring `'initial'`/`'resume'` header snapshot, and reused
     * verbatim for every subsequent request — never recomputed mid-session,
     * so the provider prefix cache holds by construction (a process restart
     * or `ctx.agents.resume()` is a new instance: it recomposes, and any
-     * drift lands attributably on the `'resume'` snapshot).
+     * drift lands attributably on the `'resume'` snapshot). Composition runs
+     * outside the step, before the boundary snapshot: a composing listener's
+     * session append joins the CURRENT request's derived history.
     *
     * This is the home for session-stable openers the model must always see
     * but that must NOT become durable history — a skills catalog, an