docs: rebalance prose cleanup and add trimming skill

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

@@ -167,7 +167,8 @@ describe('ReactLoopAgent', () => {
     let flushes = 0
     ctx.on('session/flush', () => { flushes += 1 })
 
-    // A post-turn-start append failure still closes and checkpoints the turn.
+    // Invalid injected content throws after turn/start. `finally` must still append turn/end and
+    // flush the balanced in-memory turn so a crash cannot lose it before the next checkpoint.
     expect(() => {
       agent.inject([{ type: 'text', text: 'x', bad: 1n } as never], { source: { kind: 'plugin', plugin: 'p' } })
     }).toThrow(/non-JSON-serializable/)
@@ -249,26 +250,20 @@ describe('ReactLoopAgent', () => {
   })
 
   it('disposer is idempotent (double-stop)', async () => {
-    // Create a bare ReactLoopAgent and start it through the package-internal
-    // test seam. Then call its disposer twice — the second call hits the
-    // early-return branch.
+    // The internal start seam exposes one idle driver's disposer for repeated invocation.
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('test'))
     const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { model: 'mock' }, session)
     const { agent } = prepared
 
-    // Start the loop to get the disposer; the agent waits for messages
-    // (idle, never-resolving cancel), so it will stay idle.
     prepared.markPublished()
     const dispose = prepared.startDriver()
 
-    // First dispose
     const firstDisposal = dispose()
     expect(agent.status).toBe('disposed')
     await firstDisposal
 
-    // Second dispose — idempotent, no throw
     await expect(dispose()).resolves.toBeUndefined()
     expect(agent.status).toBe('disposed')
   })
@@ -363,7 +358,8 @@ describe('ReactLoopAgent', () => {
   })
 
   it('whenIdle() subscribed while running resolves via done when the agent is then disposed', async () => {
-    // The disposed waiter must chain the driver exit, not resolve eagerly.
+    // Queue the internal waiter while running, then dispose the bare driver. Its disposed branch
+    // must chain the loop's `done` promise rather than resolve before exit.
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(SessionStore)
@@ -389,7 +385,8 @@ describe('ReactLoopAgent', () => {
   })
 
   it('whenIdle() subscribed while running survives a FIBER dispose (no hung promise)', async () => {
-    // Fiber disposal must settle the agent-owned waiter.
+    // The waiter is agent-owned state, not an effect-scoped listener that owner disposal would
+    // remove before the disposed transition. Fiber teardown must still settle it.
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
     let agent!: ReactLoopAgent
@@ -407,7 +404,8 @@ describe('ReactLoopAgent', () => {
   })
 
   it('whenIdle() on a disposed agent awaits the loop exit (done), not just the status flip', async () => {
-    // Disposed status precedes driver exit; whenIdle must await both.
+    // Disposed status is emitted before the driver unwinds. `whenIdle()` must chain `done` so it
+    // resolves only after true loop exit.
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
     let agent!: ReactLoopAgent

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

@@ -2,7 +2,8 @@
  * Tests for the queue-aware `Agent.cancel()` primitive. `cancel()` is the broad verb — it
  * clears queued + steering work, aborts an in-flight step, and drops a turn about to start —
  * whereas a bare step abort (the loop's private `AbortController`) kills only the current step
- * and leaves the queue intact.
+ * and leaves the queue intact. The suite covers every landing window plus marker
+ * reset and `whenIdle()` quiescence.
  * @module dsh-agent-loop/tests/cancel
  */
 
@@ -91,8 +92,8 @@ describe('Agent.cancel()', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
 
-    // Queue work, then register a whenIdle() waiter while in the pre-step window (status idle,
-    // hasQueued true) — it does not take the fast path.
+    // This waiter cannot rely on a running→idle transition because cancellation
+    // drops the turn before it runs; the skip path must settle it directly.
     send(agent, 'q')
     const idle = agent.whenIdle()
     agent.cancel('pre-step')
@@ -228,8 +229,8 @@ describe('Agent.cancel()', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
 
-    // The first composition is interrupted mid-waterfall and — like an abort-aware listener
-    // bailing on a firing signal — contributes nothing.
+    // The interrupted first composition must not cache its degraded empty value;
+    // the next prompt recomposes and logs/sends the fresh prefix.
     const opener: Message = { role: 'user', content: [{ type: 'text', text: 'fresh opener' }] }
     let compositions = 0
     ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
@@ -258,8 +259,8 @@ describe('Agent.cancel()', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
 
-    // A turn/start listener fires right after turn/start is appended, before any
-    // AbortController is installed for the step.
+    // A turn/start listener fires before a step controller exists, so the
+    // turn-scoped marker—not step abort—must drop the pending step.
     let streamed = false
     ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true })
     const dispose = ctx.on('session/event', (session, event) => {
@@ -388,8 +389,8 @@ describe('Agent.cancel()', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
 
-    // setStatus('running') emits agent/status SYNCHRONOUSLY, so a running listener can cancel
-    // in the gap between the loop's pre-step check and runTurn.
+    // `agent/status` is synchronous, so cancellation can land after the first
+    // pre-step check; the second check must drop the now-empty turn.
     let streamed = false
     ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true })
     const dispose = ctx.on('agent/status', (subject, status) => {

packages/core/agent-loop/tests/config-session-id.spec.ts

@@ -101,7 +101,8 @@ describe('config-driven session id', () => {
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
-    // Run 2: a CONFIG agent with resumeSessionId continues that session.
+    // Resume waits for the injected persistence service, so poll until the
+    // config-created agent appears with its stored history.
     const ctx2 = new Context()
     await ctx2.plugin(LlmService)
     await ctx2.plugin(SessionStore)

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -39,7 +39,7 @@ function send(agent: ReactLoopAgent, text: string) {
   agent.send([{ type: 'text', text }])
 }
 
-describe('HIGH: session log records what agent/step-result actually produced', () => {
+describe('session log records what agent/step-result actually produced', () => {
   it('a step-result rewrite is what the log, derived history, and tool dispatch all see', async () => {
     const adapter = new MockAdapter([textResponse('original'), textResponse('done')])
     const ctx = await harness(adapter)
@@ -89,7 +89,7 @@ describe('HIGH: session log records what agent/step-result actually produced', (
   })
 })
 
-describe('HIGH: abort during tool execution ends the turn', () => {
+describe('abort during tool execution ends the turn', () => {
   it('aborting the in-flight step inside a tool prevents both remaining tools and the next model step', async () => {
     const adapter = new MockAdapter([
       // model asks for two tool calls in one step
@@ -141,7 +141,7 @@ describe('HIGH: abort during tool execution ends the turn', () => {
   })
 })
 
-describe('HIGH: steering from late extension points is never stranded', () => {
+describe('steering from late extension points is never stranded', () => {
   it('steer() from an agent/turn-continuation listener overrides a stop decision', async () => {
     const adapter = new MockAdapter([
       textResponse('no tools, would stop here'),
@@ -247,7 +247,7 @@ describe('HIGH: steering from late extension points is never stranded', () => {
   })
 })
 
-describe('HIGH: plugin exceptions are contained', () => {
+describe('plugin exceptions are contained', () => {
   it('a throwing agent/turn-continuation listener ends the turn with an error, loop survives', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
@@ -302,7 +302,7 @@ describe('HIGH: plugin exceptions are contained', () => {
   })
 })
 
-describe('MEDIUM: disposed status is part of the agent/status contract', () => {
+describe('disposed status is part of the agent/status contract', () => {
   it('disposing the fiber emits agent/status(disposed) and ends the turn with reason disposed', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
@@ -349,7 +349,7 @@ describe('MEDIUM: disposed status is part of the agent/status contract', () => {
   })
 })
 
-describe('MEDIUM: misc registry and config fixes', () => {
+describe('adapter registration, routing, and accepted-input ownership', () => {
   it('duplicate adapter registration is rejected', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
@@ -508,7 +508,7 @@ describe('MEDIUM: misc registry and config fixes', () => {
   })
 })
 
-describe('MEDIUM: turn numbering continues across seeded (forked) sessions', () => {
+describe('turn numbering continues across seeded sessions', () => {
   it('a forked agent continues turn numbers after the seed log', async () => {
     const first = new MockAdapter([textResponse('turn one')])
     const ctx = await harness(first)
@@ -546,7 +546,7 @@ describe('MEDIUM: turn numbering continues across seeded (forked) sessions', ()
   })
 })
 
-describe('LOW: discriminated SessionEvent narrows without casts', () => {
+describe('discriminated SessionEvent narrows without casts', () => {
   it('narrows event.data from event.type', () => {
     const session = new Session(SessionId('s'))
     const appended: SessionEvent = session.append('tool/call', {
@@ -564,7 +564,7 @@ describe('LOW: discriminated SessionEvent narrows without casts', () => {
   })
 })
 
-describe('HIGH: a finish-error stream chunk ends the turn as error, not completed', () => {
+describe('a finish-error stream chunk ends the turn as error, not completed', () => {
   it('translates finish {kind:error} into a turn error with a logged error event', async () => {
     // A finish-error chunk must not produce a completed assistant turn.
     const errorStream: StreamChunk[] = [
@@ -587,7 +587,7 @@ describe('HIGH: a finish-error stream chunk ends the turn as error, not complete
     // a standalone error event.
     const turnEnd = events.find(event => event.type === 'turn/end')
     expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'error', step: 1, message: 'provider 401', code: 'AUTH' })
-    // Crucially: no assistant/message was logged for the failed step.
+    // A failed step must not synthesize an assistant message.
     expect(events.some(event => event.type === 'assistant/message')).toBe(false)
   })
 
@@ -1104,7 +1104,8 @@ describe('surface: assistant/message omits sourceEventSeqs when no chunks stream
 
 describe('disposal and cancellation during pre-step assembly', () => {
   it('disposal during system-prompt assembly drops the about-to-start step as disposed', { timeout: 30000 }, async () => {
-    // Release assembly only after disposal has marked the agent disposed.
+    // Start disposal, then release assembly. Do not await disposal first: it
+    // waits for the blocked driver to exit.
     const adapter = new MockAdapter(['hang'])
     let releaseAssemble!: () => void
     const blocked = new Promise<void>(r => void (releaseAssemble = r))
@@ -1137,28 +1138,22 @@ describe('disposal and cancellation during pre-step assembly', () => {
     // Give the loop time to enter the step and reach assemble().
     await new Promise(r => setTimeout(r, 50))
 
-    // Start disposal — stop() sets status=disposed synchronously, then the
-    // disposer's await agent.done hangs because the loop is blocked in the
-    // waterfall. Do NOT await yet; release the blocker first.
+    // Release assembly before awaiting disposal because disposal joins the blocked driver.
     const disposalDone = fiber.dispose()
 
-    // Now release the blocked waterfall — the loop unblocks, checks
-    // isDisposed(), and exits, which resolves agent.done and disposalDone.
     releaseAssemble()
     await disposalDone
     await agent.done
     unlisten()
 
+    // Turn boundaries are durable rows; there is no `agent/*` mirror to assert.
     const e = [...agent.session.events]
     expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1)
     expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1)
     const turnEnd = e.findLast(x => x.type === 'turn/end')
     expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' })
-    // No step was opened, no LLM call was made.
     expect(e.some(x => x.type === 'step/start')).toBe(false)
     expect(e.some(x => x.type === 'assistant/chunk')).toBe(false)
-    // The durable turn/end record is the authoritative turn-boundary signal
-    // (turn boundaries have no agent/* mirror), so this asserts on the log.
   })
 
   it('cancel during system-prompt assembly drops the about-to-start step as aborted', { timeout: 30000 }, async () => {
@@ -1215,7 +1210,8 @@ describe('disposal and cancellation during pre-step assembly', () => {
   })
 
   it('disposal during agent/pre-step seam ends the turn disposed', { timeout: 15000 }, async () => {
-    // Release pre-step only after disposal has marked the agent disposed.
+    // Start disposal, then release pre-step; awaiting disposal first would
+    // deadlock on the blocked driver.
     const adapter = new MockAdapter(['hang'])
     let releasePreStep!: () => void
     const blocker = new Promise<void>(r => void (releasePreStep = r))

packages/core/agent-loop/tests/coverage-edges.spec.ts

@@ -225,9 +225,7 @@ describe('disposed vs aborted branching', () => {
     await fiber.dispose() // dispose during hang
     await agent.done
 
-    // The review-fixes test for 'HIGH: disposed status' already covers
-    // this assertion path. The reason is 'disposed' because isDisposed() is
-    // checked before the abort signal check in the error path.
+    // Disposal wins abort classification because the error path checks it first.
     expect(reasons).toContainEqual({ kind: 'disposed' })
   })
 })

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

@@ -64,16 +64,12 @@ describe('Inbox', () => {
     void inbox.waitForQueued(new Promise(() => {})) // first call, never resolved
     void inbox.waitForQueued(p1) // second call overwrites wakeup
 
-    // Cancel p1 (the latest waiter's cancel) — the wakeup was overwritten
-    // to p1's resolve, so canceling p1 triggers the finally block which
-    // clears the wakeup if it matches.
+    // Cancelling the latest waiter clears the shared callback; enqueue must neither
+    // wake the stale waiter nor fail on the cleared callback.
     r1()
     await p1
 
-    // Now enqueue: the first waiter's wakeup (which was overwritten) won't fire, and the second
-    // waiter's wakeup was cleared by cancel.
     inbox.enqueue({ content: [{ type: 'text', text: 'hey' }], source: { kind: 'user' } })
-    // The overwrite path + finally cleanup are exercised
   })
 
   it('clears wakeup in finally handler when enqueue resolves', async () => {
@@ -87,23 +83,17 @@ describe('Inbox', () => {
   })
 
   it('finally handler does not clear wakeup when a different waiter overwrote it', async () => {
-    // First waiter's cancel resolves AFTER a second waiter overwrote wakeup.
-    // First waiter's finally sees wakeup !== its resolve → does not clear.
+    // A stale waiter's finally must not clear the replacement waiter.
     const inbox = new Inbox()
     const { promise: c1, resolve: r1 } = resolverPair()
 
     void inbox.waitForQueued(c1) // wakeup = resolve1, c1.then(resolve1)
     void inbox.waitForQueued(new Promise(() => {})) // wakeup = resolve2, cancel never resolves
 
-    // Resolve c1 (the first cancel). c1.then(resolve1) fires → resolve1() called
-    // → waiter1's promise resolves → finally: wakeup === resolve1? NO (it's resolve2)
-    // → wakeup is NOT cleared.
     r1()
     await c1
 
-    // Now enqueue: wakeup() calls resolve2 → waiter2 resolves
-    // But waiter2's cancel never resolves — that's fine, enqueue resolves it.
+    // The replacement remains registered and is resolved by enqueue.
     inbox.enqueue({ content: [{ type: 'text', text: 'hey' }], source: { kind: 'user' } })
-    // No need to await anything further — enqueue is synchronous wakeup
   })
 })

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

@@ -117,9 +117,8 @@ describe('agent/prompt-submit', () => {
   })
 
   it('a prompt-submit rewrite + additionalContext is VISIBLE to the agent/pre-step seam (merged ordering)', async () => {
-    // The merge of the interception seams with master's compaction seam pins one ordering:
-    // `agent/prompt-submit` runs (rewriting the prompt and injecting context) before the step
-    // loop, and `agent/pre-step` fires inside the step before the single deriveMessages().
+    // Prompt rewrites and injected context land before `agent/pre-step`, so a
+    // compaction listener measures the current surface before the single derive.
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -184,7 +183,8 @@ describe('agent/prompt-submit', () => {
   })
 
   it('a mixed batch records a prompt/blocked for the vetoed prompt while the allowed one runs', async () => {
-    // Two prompts queued into one turn: block "secret", allow "safe".
+    // Blocking one prompt in a mixed batch must persist its reason even though
+    // the allowed prompt keeps the turn from ending rejected.
     const adapter = new MockAdapter([textResponse('ran once')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -508,14 +508,13 @@ describe('agent/turn-continuation (ContinuationDecision)', () => {
     await waitForIdle(ctx, agent)
 
     const log = events(agent)
-    // same turn, two steps
+    // The continuation stays in the turn, is logged with provenance before step 2,
+    // and reaches that step's request.
     expect(log.filter(e => e.type === 'turn/start')).toHaveLength(1)
     expect(log.filter(e => e.type === 'step/start')).toHaveLength(2)
-    // the reason was recorded as steering BEFORE step 2, with its plugin source
     const steering = log.find(e => e.type === 'steering/message')
     expect(steering?.type === 'steering/message' && steering.data.content).toEqual([{ type: 'text', text: 'keep going on the goal' }])
     expect(steering?.type === 'steering/message' && steering.data.source).toEqual({ kind: 'plugin', plugin: 'goal' })
-    // and reached the next request
     expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('keep going on the goal')
   })
 

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

@@ -518,8 +518,8 @@ describe('agent loop', () => {
   })
 
   it('agent/pre-step fires BEFORE the step it precedes opens (events land outside the step)', async () => {
-    // A listener appending a surface node in pre-step lands it before step/start in the log —
-    // proving the seam fires outside the step.
+    // The append lands before step/start, yet derive happens afterwards and the
+    // same step's request must include it.
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -552,9 +552,8 @@ describe('agent loop', () => {
   })
 
   it('a throwing agent/pre-step listener ends the turn (error), not the loop', async () => {
-    // The seam fires before step/start, so a throw escapes to runTurn's outer catch: the
-    // not-yet-open step closes as a no-op, the failure surfaces via agent/error, and the turn
-    // ends `error` (recorded on the durable turn/end).
+    // Before step/start, a pre-step throw reaches the turn catch: no step needs
+    // closing, the turn records error, and the loop remains available.
     const adapter = new MockAdapter([textResponse('second turn ok')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -621,7 +620,7 @@ describe('agent loop', () => {
 
     expect(adapter.requests).toHaveLength(1)
     expect(reasons).toEqual([{ kind: 'max-tokens' }])
-    // and the reason is recorded in the log's turn/end event
+    // Assert the durable row, not only the live listener.
     const turnEnd = agent.session.events.findLast(e => e.type === 'turn/end')
     expect(turnEnd!.data.reason).toEqual({ kind: 'max-tokens' })
   })
@@ -710,8 +709,8 @@ describe('agent loop', () => {
     expect(agent.session.events.some(e => e.type === 'tool/call')).toBe(false)
     expect(agent.session.deriveMessages()).toEqual([{ role: 'user', content: [{ type: 'text', text: 'go' }] }])
     expect(reasons).toEqual([{ kind: 'max-tokens' }])
-    // No-data-loss: a max-tokens step whose only content was a dropped tool call has EMPTY
-    // assistant content, but its usage must still be represented.
+    // Empty content still needs an assistant/message to carry usage; derivation
+    // skips that host so it does not create a spurious assistant turn.
     const assistantMessage = agent.session.events.find(e => e.type === 'assistant/message')
     expect(assistantMessage?.type === 'assistant/message' && assistantMessage.data).toEqual({
       turn: 1, step: 1, content: [], usage: { inputTokens: 10, outputTokens: 5 },

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

@@ -1,5 +1,7 @@
 /**
- * Property-based tests for the agent loop's inbox/turn scheduling (the property-testing RFC).
+ * Deterministic property tests for inbox scheduling: every sent message logs
+ * once, turn numbers increase, and status follows idle→running→idle/disposed.
+ * Schedules advance on status events rather than wall-clock sleeps.
  */
 
 import { describe, expect, it } from 'vitest'
@@ -139,8 +141,8 @@ describe('agent loop scheduling properties', () => {
         const ctx = await harness()
         try {
           const agent = ctx.agentLoop.create(AgentId('a'), { model: 'mock' })
-          // Capture an idle waiter before EACH send; the last one is guaranteed to resolve
-          // because the final send always triggers (or joins) a turn that ends idle.
+          // Capture before each send; the last waiter covers the final turn, and
+          // awaiting an already-settled earlier waiter is harmless.
           let lastIdle: Promise<void> | undefined
           for (const step of steps) {
             const idle = nextIdle(ctx, agent)

packages/core/agent-loop/tests/request-cache.e2e.ts

@@ -14,7 +14,8 @@ import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
  * `cacheReadTokens > 0` on every request after the first — the adapter maps the provider's
  * `prompt_cache_hit_tokens`, and the per-step usage recorded on `assistant/message` events is
  * the production observable for cache behavior (the reconstructability RFC's measurement
- * layer: prefix stability is corollary #1).
+ * layer: prefix stability is corollary #1). Mocks establish append-extension;
+ * this key-gated test establishes a real provider cache hit.
  */
 
 // Long enough that the shared request prefix comfortably spans the provider's

packages/core/agent-loop/tests/request-reconstruction.spec.ts

@@ -2,7 +2,8 @@
  * Loop-level reconstructability: every request the loop sends is a pure function of the
  * session log — messages are the derivation at the step/start boundary, the header is the fold
  * of request/header* events — and every request is an append-extension of its predecessor
- * unless a logged event (compaction replace, header change) explains the difference.
+ * unless a logged event (compaction replace, header change) explains the difference. Mock-adapter
+ * requests are the observable, and the final offline rebuild states the full contract end to end.
  */
 
 import { describe, expect, it } from 'vitest'

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

@@ -460,7 +460,8 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
   })
 
   it('an idle inject() is flushed durably on its own (survives without explicit flush/dispose)', async () => {
-    // Lifecycle 1: run a turn, then inject context while idle.
+    // Idle injection creates and flushes a one-shot turn. No explicit flush or
+    // clean disposal follows, so disk presence proves its own checkpoint ran.
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
@@ -482,7 +483,8 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
   })
 
   it('an idle inject() survives persist + resume (turn-enclosed, not dropped as crash tail)', async () => {
-    // Lifecycle 1: run a turn, then inject context while idle.
+    // Turn enclosure keeps idle context out of crash-tail repair, so it must
+    // survive persistence and resume.
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent

packages/core/agent-loop/tests/tool-order.spec.ts

@@ -2,7 +2,8 @@
  * Loop-level tool-order determinism: the request/header event — and therefore the frozen
  * request the adapter receives — carries the assembly's canonical tool order (system-prompt's
  * `toolOrder` config, or lexicographic name order), regardless of the order tool plugins
- * happened to register in.
+ * happened to register in. Registration order is a concurrent loading artifact
+ * and must not leak downstream.
  */
 
 import { describe, expect, it } from 'vitest'