Merge worktree-hooks-b-bash-seam into worktree-hooks-c-interception

Bring the interception-seams branch onto current master (via A→B). The
substantive reconciliation is master's compaction `agent/pre-step` serial seam
meeting C's interception seams:

- types.ts: keep BOTH master's `agent/pre-step` AND C's new interception events
  (`agent/prompt-submit`, `agent/session-start`, `agent/turn-continuation`→
  `ContinuationDecision`); drop the turn-mirror declarations (removed on A).
- loop.ts: the merged per-turn order is `turn/start` → per queued msg
  `agent/prompt-submit` (rewrite/inject/block) → (fully-blocked ⇒ zero-step
  `rejected`) → per step: drain steering → assemble system prompt →
  `agent/pre-step` (compaction, OUTSIDE the step) → `step/start` → single
  `deriveMessages()` → model → tools/pre-execute·dispatch·post-execute. No
  turn-mirror emits; `closeTurn()` is the A-simplified single-call form.
- Docs (architecture, core.md, agent/agent-loop READMEs, catalog) reconciled to
  show C's interception seams alongside `agent/pre-step`, no turn/step mirrors.
- rfc/README: dropped the stale `proposed/` compaction row (master moved that RFC
  to implemented/); kept C's new `pre-tool-input-rewrite` proposed row.
- interception.spec.ts: migrated its two `agent/turn-end` reason collectors to
  the `turn/end` session event, and ADDED a cross-test proving a
  `prompt-submit` rewrite + additionalContext is VISIBLE to an `agent/pre-step`
  listener on the same turn — pinning the merged seam ordering (compaction sees
  the post-prompt-submit surface, not stale history).

packages/core/session/src/index.ts

@@ -19,6 +19,7 @@ export { isJsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
 export type { SurfaceNode } from './surface.ts'
 export { isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
+export { isToolPairingBalanced } from './tool-pairing.ts'
 
 declare module 'cordis' {
   interface Context {

packages/core/session/src/tool-pairing.ts

@@ -0,0 +1,100 @@
+/**
+ * Tool-pairing balance over a session's SURFACE: is a given cut point in the
+ * surface a safe edge for a collapsed region (e.g. compaction)?
+ *
+ * The invariant a consumer needs: a collapsed region must never separate an
+ * `assistant/message`'s `tool-call` blocks from their answering `tool/result`s
+ * — that would leave the rehydrated transcript with a dangling tool-call or an
+ * orphaned tool-result, which every provider rejects. (This is the
+ * compaction-time mirror of the crash-recovery imbalance that
+ * {@link interruptedTurnClosers} repairs on load.) Steps were once used as a
+ * proxy for this bracketing, but a compaction REWRITES the surface — it lands a
+ * replacement node at a high log seq whose SURFACE position is the head — so a
+ * scan over the LOG's `step/*` markers mis-reads such a node's neighbours. The
+ * pairing the invariant actually protects lives in the surface nodes' own
+ * content (a `tool-call` block's id, a `tool/result`'s `callId`), which travels
+ * with the node through any reshaping, so alignment is decided over the surface
+ * directly.
+ *
+ * A **cut** is a gap between two adjacent surface nodes (named by the node it
+ * sits immediately before), or the after-tail gap (`null`). Walking the surface
+ * head→tail and assigning each node a delta — `+1` per `tool-call` block on an
+ * `assistant/message`, `-1` per `tool/result`, `0` otherwise — the depth at a
+ * cut is the number of still-unanswered tool calls before it. A cut is
+ * **balanced** when that depth is `0`. A region `[start..end]` is safe to
+ * collapse iff BOTH its edges are balanced cuts: the cut before `start` and the
+ * cut after `end`. Nodes that belong to no step (a pre-step `user/message`, an
+ * inter-step `steering/message`, an injection `context/message`) carry no
+ * pairing, contribute `0`, and so are free boundaries — exactly as before, but
+ * now as a consequence of the balance rather than a special case. An open
+ * trailing step (an assistant whose `tool/result`s have not landed yet) keeps
+ * the depth positive through the tail, so no cut inside it is balanced — the
+ * old explicit open-step check falls out of the same counter.
+ *
+ * @module @deepseek-ai/dsh-session/tool-pairing
+ */
+
+import type { SessionEvent } from './types.ts'
+import type { SurfaceNode } from './surface.ts'
+
+/**
+ * The tool-pairing delta of a surface node: how it shifts the count of
+ * unanswered tool calls. An `assistant/message` opens one bracket per
+ * `tool-call` block; a `tool/result` closes one; every other surface node
+ * (`user/message`, `context/message`, `steering/message`, a usage-only
+ * `assistant/message` with no tool-call blocks) is pairing-neutral.
+ */
+function nodeDelta(event: SessionEvent): number {
+  switch (event.type) {
+    case 'assistant/message':
+      return event.data.content.filter(block => block.type === 'tool-call').length
+    case 'tool/result':
+      return -1
+    // Non-pairing surface nodes and every non-surface event contribute nothing.
+    default:
+      return 0
+  }
+}
+
+/**
+ * Whether the surface prefix ending at the given cut has BALANCED tool-call /
+ * tool-result brackets — i.e. every `tool-call` block on the surface before the
+ * cut has its answering `tool/result` before the cut too, so the cut is a safe
+ * edge for a collapsed region (it cannot split an assistant↔result pair).
+ *
+ * `nodes` is the surface linked list in head→tail order (e.g.
+ * `session.surface.nodes`); `events` is the session log, used to look each
+ * node's event up by `seq`. `beforeSeq` names the cut by the surface node it
+ * sits immediately before; the after-tail cut (the whole surface) is `null`,
+ * as is any `beforeSeq` not present on the surface.
+ *
+ * A region `[start..end]` is collapsible iff both edges are balanced cuts: call
+ * `isToolPairingBalanced(nodes, events, start)` for the cut before `start`, and
+ * `isToolPairingBalanced(nodes, events, after)` — where `after` is `end`'s
+ * surface successor (`SurfaceNode.next`), or `null` when `end` is the tail —
+ * for the cut after `end`.
+ *
+ * @throws if the surface prefix drives the unanswered-call depth negative — a
+ *   `tool/result` with no preceding open `tool-call` on the surface. That is a
+ *   corrupt surface (a structural invariant violation), surfaced loudly here
+ *   rather than silently mis-classifying a boundary.
+ */
+export function isToolPairingBalanced(
+  nodes: readonly SurfaceNode[],
+  events: readonly SessionEvent[],
+  beforeSeq: number | null,
+): boolean {
+  let depth = 0
+  for (const node of nodes) {
+    if (node.seq === beforeSeq) return depth === 0
+    // node.seq is a surface-node seq, always a valid log index by construction.
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    depth += nodeDelta(events[node.seq]!)
+    if (depth < 0) {
+      throw new Error(`tool-pairing balance: tool/result at surface seq ${node.seq} has no matching tool-call (corrupt surface)`)
+    }
+  }
+  // Reached the after-tail cut (beforeSeq === null, or a seq not on the
+  // surface): the whole-surface prefix is balanced iff depth returned to 0.
+  return depth === 0
+}

packages/core/session/src/types.ts

@@ -184,7 +184,8 @@ export interface TodoItem {
  * same events; trace/telemetry = subscribe to the log.
  *
  * Merge-extensible: plugins declare extra event types via declaration merging
- * (e.g. a compaction plugin adds `'compaction/marker'`).
+ * (e.g. the compaction plugin adds `'compact/start'`, `'compact/summary'`,
+ * `'compact/end'`).
  *
  * Durability contract (what a persistence backend relies on): the durable log
  * persists every event verbatim, INCLUDING `assistant/chunk` — `seq` must stay
@@ -321,7 +322,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /**
      * Seq numbers of events that are provenance sources of this event
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-     * or the surface nodes shadowed by a compaction marker).
+     * or the surface nodes shadowed by a compaction replace node).
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */