docs: rebalance prose cleanup and add trimming skill

packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts

@@ -54,7 +54,8 @@ runPersistenceContract('jsonl', async () => {
   }
 })
 
-// Run the shared coordinator orchestration suite against the real JSONL backend.
+// Two mounts share this temp root to exercise reload. `corruptTail` appends a partial,
+// newline-less fragment past the committed region so coordinator repair runs on real file bytes.
 runCoordinatorContract('jsonl', async (): Promise<CoordinatorFixture> => {
   const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-coord-'))
   return {
@@ -344,7 +345,7 @@ describe('SessionPersistenceJsonl: scanLog unit', () => {
     ].join('\n') + '\n'
     // No committed turn/end, so the gap is a tolerated crash boundary: scanLog PRESERVES the
     // contiguous prefix (turn/start seq 0) — real interrupted-turn work, not discarded — and
-    // stops at the gap.
+    // stops at the gap. `loadCore`, not this scanner, later closes the orphaned turn.
     expect(scanLog(Buffer.from(log)).events.map(e => e.seq)).toEqual([0])
   })
 
@@ -464,7 +465,8 @@ describe('SessionPersistenceJsonl: edge cases', () => {
   })
 
   it('list reads a header line longer than the 8KB read chunk', async () => {
-    // readFirstLine accumulates across reads when the first line exceeds its buffer.
+    // A tolerated extra field makes this valid header exceed the 8192-byte read buffer, proving
+    // `readFirstLine` accumulates chunks before `list()` parses it.
     const bucket = join(root, '_no-cwd')
     await mkdir(bucket, { recursive: true })
     const bigHeader = JSON.stringify({ type: 'session', version: 0, id: 'big', createdAt: 1, pad: 'x'.repeat(9000) })
@@ -484,7 +486,8 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     for (const s of ctx.sessions.list()) await ctx.parallel('session/flush', s)
     await sessFiberA.dispose()
 
-    // A NEW live Session object reuses id "reuse".
+    // A new Session object reuses the id. Object-keyed initialization must run independently,
+    // detect the disk collision, and reject instead of appending through session A's stale cursor.
     const backend = ctx.sessionPersistence as unknown as { inits: Map<Session, Promise<void>> }
     let b!: Session
     await ctx.plugin(Object.assign((inner: Context) => {
@@ -502,7 +505,9 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     await ctx.sessionPersistence.append(SessionId('x'), oneTurnLog())
     await ctx.fiber.dispose()
 
-    // Backend 2 over the same root.
+    // Backend 2 creates a no-cwd session whose id exists only in `/w`. Exact `loadLive(id,
+    // undefined)` must not adopt across buckets; the any-cwd collision check then rejects instead
+    // of grafting no-cwd events onto a log with mismatched cwd.
     const ctx2 = new Context()
     await ctx2.plugin(SessionStore)
     await ctx2.plugin(SessionPersistenceJsonl, { root })
@@ -570,7 +575,8 @@ describe('SessionPersistenceJsonl: edge cases', () => {
   })
 
   it('list surfaces a non-ENOENT root error (ENOTDIR) instead of reporting no sessions', async () => {
-    // A durable backend must not collapse a storage fault to "no sessions".
+    // A durable backend must not collapse a storage fault to "no sessions". Making the root a
+    // regular file forces ENOTDIR from `readdir`, which must propagate.
     const filePath = join(root, 'not-a-dir')
     await writeFile(filePath, 'x')
     const ctx2 = new Context()
@@ -581,8 +587,8 @@ describe('SessionPersistenceJsonl: edge cases', () => {
   })
 
   it('loadLive surfaces a non-ENOENT lookup error (ENOTDIR) instead of reporting absent', async () => {
-    // A non-ENOENT error from the per-id open() must surface, not be collapsed to "not found"
-    // (which would let live-adoption proceed under a false absence assumption).
+    // A non-ENOENT per-id open error must surface rather than become "not found" and permit false
+    // live adoption. Making the cwd bucket a regular file forces ENOTDIR for its child log path.
     const cwd = '/x'
     const ctx2 = new Context()
     await ctx2.plugin(SessionStore)
@@ -703,7 +709,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     const session = ctx.sessions.create(SessionId('reject-bad'))
     // Serializability is enforced at the source: Session.append throws on a BigInt-bearing
     // event before it enters session.events, so the durable log can never diverge from the live
-    // log.
+    // log. The error therefore surfaces synchronously at append, not later during backend flush.
     expect(() => {
       session.append('user/message', { content: [{ type: 'text', text: 'bad' }], source: { kind: 'user' }, bad: 1n } as never, { surfaceOp: 'append' })
     }).toThrow(/non-JSON-serializable/)