fix(agent): correct session-prefix composition-order docs; scrub messagePrefix in snapshots

Two ds-review-bot findings:

The seam JSDoc claimed extending 'await next()' composes in
registration order — false for the append form: the waterfall unwinds
innermost-first, so appending places later-registered contributions
first. The canonical contribution is now documented as the PREPEND
'[mine, ...await next()]' (registration order on the wire), with the
append form's reverse-order behavior stated explicitly; the ordering
test now uses the canonical pattern in both listeners.

scrubRequestHeaders tokenized only system/tools, so a fixture recording
a composed session prefix would carry its raw text (workspace-specific
churn/leak). The scrubber now maps each header/delta messagePrefix
entry to a {{messagePrefix}} token — count stays a structural fact,
absence stays absent, the empty-array transition stays visible — with
normalize.spec coverage for the header, delta, absence, and odd-shape
paths.

packages/core/agent-loop/tests/interception.spec.ts

@@ -352,23 +352,24 @@ describe('agent/session-prefix', () => {
     expect(agent.session.deriveMessages()[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'go' }] })
   })
 
-  it('contributions compose across listeners in registration order', async () => {
+  it('the canonical prepend pattern composes contributions in registration order', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
 
+    // Both listeners use the canonical `[mine, ...await next()]` prepend: the
+    // waterfall unwinds innermost-first (the second listener's array is built
+    // first), so prepending puts the FIRST-registered contribution first.
     ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
       return [{ role: 'user', content: [{ type: 'text', text: 'first' }] }, ...await next()]
     })
     ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
-      return [...await next(), { role: 'user', content: [{ type: 'text', text: 'second' }] }]
+      return [{ role: 'user', content: [{ type: 'text', text: 'second' }] }, ...await next()]
     })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
 
-    // Registration order composes: the first listener runs last on the way
-    // out (waterfall), so its prepend lands first.
     const texts = adapter.requests[0]!.messages.map(m => m.content[0]?.type === 'text' ? m.content[0].text : '')
     expect(texts).toEqual(['first', 'second', 'hi'])
   })

packages/core/agent/src/types.ts

@@ -408,9 +408,14 @@ declare module 'cordis' {
      * durable `context/message` paid once and prefix-cached thereafter.
      *
      * The seed is a frozen empty list; a contributing listener returns a NEW
-     * array extending `await next()` (`[...prefix, mine]` — never an in-place
-     * push), so contributions compose across plugins in registration order
-     * and compose deterministically for a fixed plugin set. Call `next()` to
+     * array — never an in-place push. The canonical contribution is a
+     * PREPEND, `[mine, ...await next()]`: the waterfall unwinds
+     * innermost-first (the LAST-registered listener's `next()` resolves
+     * first), so prepending yields registration order on the wire, and every
+     * plugin using it composes deterministically. The append form
+     * `[...await next(), mine]` is legal but places a contribution AFTER
+     * every later-registered plugin's — reverse registration order when all
+     * contributors append. Call `next()` to
      * delegate, or return a list without it to short-circuit.
      * @param agent - the agent whose session prefix is being composed.
      * @param prefix - the frozen empty seed; return an extended replacement to contribute.