Merge remote-tracking branch 'origin/master' into worktree/provider-routed-llm-adapters

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/events.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/core.md
#	docs/event-producer-consumer.md
#	docs/persistence-catalog.md
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
#	examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
#	examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl
#	examples/acp-agent/tests/snapshots/skill-load/session.jsonl
#	examples/acp-agent/tests/snapshots/text-turn/session.jsonl
#	examples/sandbox-acp-agent/cordis.yml
#	examples/sandbox-acp-agent/tests/snapshots/escalation-approved/session.jsonl
#	examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/session.jsonl
#	examples/sandbox-acp-agent/tests/snapshots/mode-switching/session.jsonl
#	packages/compact/compact-basic/README.md
#	packages/compact/compact-basic/src/index.ts
#	packages/compact/compact-basic/tests/compact-basic.spec.ts
#	packages/core/agent-loop/README.md
#	packages/core/agent-loop/src/loop.ts
#	packages/core/agent-loop/tests/properties.spec.ts
#	packages/core/session/README.md
#	packages/core/session/src/types.ts
#	packages/core/session/tests/derived-cache.spec.ts
#	packages/llm/llm-deepseek/src/index.ts
#	packages/llm/llm-pi-ai/README.md
#	packages/llm/llm-pi-ai/src/adapter.ts
#	packages/llm/llm-pi-ai/src/convert.ts
#	packages/llm/llm-pi-ai/tests/adapter.spec.ts
#	packages/llm/llm/README.md
#	packages/llm/llm/src/call-config.ts
#	packages/llm/llm/src/index.ts
#	packages/ui/acp-agent/src/index.ts
#	packages/ui/acp/tests/harness.ts
#	packages/ui/jsonrpc/README.md
#	packages/ui/jsonrpc/src/server.ts
#	packages/ui/stdio-agent/README.md
#	packages/ui/stdio-agent/src/index.ts
#	python/sdk/README.i18n.yaml

packages/ui/acp/tests/harness.ts

@@ -1,12 +1,7 @@
 /**
- * Shared test fixtures for the ACP bridge specs. A plain module (NOT a
- * *.spec.ts) so importing it does not re-register a describe block.
- *
- * `makeBridgeHarness` builds a full in-memory cordis context (llm + session +
- * system-prompt + tools + agents + agent-loop + persistence) with the ACP
- * bridge wired to an in-memory transport, plus a `ClientSideConnection` on the
- * other end — so a test drives the bridge exactly as an editor would, with no
- * subprocess and no real stdio.
+ * Shared non-spec fixture that mounts the full in-memory agent/persistence stack and connects the
+ * ACP bridge to a real SDK client over memory streams. Tests exercise the same protocol path as an
+ * editor without a subprocess or stdio.
  */
 
 import { Context } from 'cordis'
@@ -218,13 +213,10 @@ export async function makeBridgeHarness(options: {
   }
   ctx.llm.registerAdapter(['mock'], adapter)
 
-  // Two identity byte pipes cross-wired into the two ndJsonStreams: bytes the
-  // agent writes flow to the client's reader and vice versa. (ndJsonStream
-  // takes (output, input): the agent writes to a2c and reads from c2a; the
-  // client writes to c2a and reads from a2c.) The client→agent path (c2a) runs
-  // through a hand-held writer so a test can close it (`closeClientTransport`)
-  // to simulate the editor disconnecting — closing it EOFs the agent's reader
-  // and resolves the bridge's `conn.closed`.
+  // Two identity byte pipes cross-wired into the two ndJsonStreams: bytes the agent writes flow
+  // to the client's reader and vice versa. (ndJsonStream takes (output, input): the agent
+  // writes to a2c and reads from c2a; the client writes to c2a and reads from a2c.) Holding the c2a
+  // writer lets tests EOF the agent reader and simulate editor disconnect.
   const a2c = new TransformStream<Uint8Array, Uint8Array>()
   const c2a = new TransformStream<Uint8Array, Uint8Array>()
   const c2aWriter = c2a.writable.getWriter()
@@ -253,11 +245,9 @@ export async function makeBridgeHarness(options: {
     onSessionUpdateError: undefined,
     client: undefined as unknown as ClientSideConnection,
     acpFiber: undefined as unknown as BridgeHarness['acpFiber'],
-    // Close the writable the CLIENT writes to (c2a) — its readable, which the
-    // agent's ndJsonStream consumes, then EOFs cleanly, so the bridge's
-    // `conn.closed` resolves and it sees the client disconnect. If the client
-    // connection holds a writer lock on it, abort the connection's signal path
-    // instead by closing through the underlying stream.
+    // Close the writable the CLIENT writes to (c2a) — its readable, which the agent's
+    // ndJsonStream consumes, then EOFs cleanly, so the bridge's `conn.closed` resolves and it
+    // sees the client disconnect.
     closeClientTransport: async () => { await c2aWriter.close() },
     dispose: async () => { await ctx.fiber.dispose() },
     storageDir: options.storageDir,
@@ -281,28 +271,19 @@ export async function makeBridgeHarness(options: {
     },
   })
 
-  // Wire the bridge (agent side) and the client (test side). The test config
-  // can override either route field (including to undefined). Default both to
-  // `mock` unless the caller explicitly set that key, so `{ model: undefined }`
-  // still means "no model at all".
+  // Default route fields only when the caller omitted them; explicit undefined values must survive.
   const cfg: AcpConfig = { stream: agentStream, ...options.config }
   if (!(options.config && 'provider' in options.config)) cfg.provider = 'mock'
   if (!(options.config && 'model' in options.config)) cfg.model = 'mock'
-  // Mount the bridge the way production does: as a cordis PLUGIN (via
-  // `ctx.plugin` with the real `inject`), NOT `AcpPlugin.apply(ctx, cfg)`
-  // directly on the root ctx. The plugin fiber is the faithful reproduction —
-  // the bridge's `apply` runs inside the fiber's injection scope, and its ACP
-  // handlers later run from the JSON-RPC read loop OUTSIDE that scope, exactly
-  // as under the example's cordis.yml. (Mounting directly on root made every
-  // service an ungated property and hid the "cannot get property … without
-  // inject" failure that bit a real Zed session.) `harness.acpFiber.dispose()`
-  // tears down JUST the bridge (its listeners + effect) for the HMR test.
+  // Mount the bridge the way production does: as a cordis plugin (via `ctx.plugin` with the
+  // real `inject`), not `AcpPlugin.apply(ctx, cfg)` on the ungated root. Later JSON-RPC callbacks run
+  // outside apply's injection scope, matching production and exposing missing-inject failures.
   harness.acpFiber = await ctx.plugin({
     name: 'acp-test',
-    // Use the bridge's REAL exported `inject` so this never drifts from the
-    // plugin's actual dependency list (adding a service to the bridge must not
-    // require editing the harness — a hardcoded list silently broke when `tools`
-    // was added). The bridge programs against the interface packages only.
+    // Use the bridge's real exported `inject` so this never drifts from the plugin's actual
+    // dependency list (adding a service to the bridge must not require editing the harness — a
+    // hardcoded list silently broke when `tools` was added). The returned fiber permits ACP-only
+    // disposal while root services remain live for HMR assertions.
     inject: [...AcpPlugin.inject],
     apply: (inner: Context) => { AcpPlugin.apply(inner, cfg) },
   })