docs: rebalance prose cleanup and add trimming skill

packages/subagent/subagent-fork/src/index.ts

@@ -2,7 +2,8 @@
  * The in-process FORK subagent backend: registers a {@link SubagentProvider} on
  * `ctx.subagents` that runs each child as a child {@link Agent} SEEDED with a prefix of the
  * parent's session log — so the child inherits the parent's conversation context instead of
- * starting fresh.
+ * starting fresh. The seed ends at the last `turn/end`: the current tool-call turn is
+ * unbalanced and cannot be replayed as a valid child session.
  * @module @deepseek-ai/dsh-subagent-fork
  */
 
@@ -32,8 +33,9 @@ export const Config: z<Config> = z.object({
 
 /**
  * The balanced completed-turn prefix of `parent`'s log: every event up to and including the
- * last `turn/end`.
- *
+ * last `turn/end`. The in-flight turn is excluded; before any completed turn the child starts
+ * fresh. Because live sequence numbers equal array indexes, the result remains a valid seed
+ * beginning at sequence zero.
  * @param parent - the agent whose session log to slice.
  * @returns the seed events, contiguous from seq 0; empty when no turn has completed.
  */

packages/subagent/subagent-fork/tests/subagent-fork.spec.ts

@@ -136,7 +136,8 @@ describe('dsh-subagent-fork', () => {
 
   it('produces an invariant-CLEAN seed: forking mid-turn excludes the open turn', async () => {
     // Drive the parent so it has one completed turn, then start a SECOND turn that is still
-    // open (a hanging model call), and fork while it's in flight.
+    // open (a hanging model call), and fork while it's in flight. The seed must stop after the
+    // balanced first turn; including the open turn would fail invariant replay during start.
     const { ctx, parent } = await setup([textResponse('done'), 'hang', textResponse('child')])
     parent.send([{ type: 'text', text: 'q1' }])
     await parent.whenIdle()
@@ -181,7 +182,8 @@ describe('dsh-subagent-fork', () => {
   })
 
   it('does NOT return the seeded parent output when the child produces no message of its own', async () => {
-    // Regression: readResult must scope to the child's own events (after the seed).
+    // `readResult` must scan only child-owned events after the seed. The child emits no assistant
+    // message, so scanning the whole log would incorrectly return the parent's distinctive text.
     const { ctx, parent } = await setup([textResponse('parent stale'), emptyStop])
     parent.send([{ type: 'text', text: 'parent question' }])
     await parent.whenIdle()