docs: tighten identity bridge prose

packages/ui/jsonrpc/README.md

@@ -1,26 +1,26 @@
 # @deepseek-ai/dsh-jsonrpc
 
-The **SDK server plugin** (`jsonrpc`): mounting it serves a stdio JSON-RPC server that lets an out-of-process SDK client (e.g. the Python `deepseek_harness` package) drive DeepSeek Harness agents without touching Cordis. The client speaks newline-delimited JSON-RPC on the process stdin/stdout ([`HarnessSdkServer`](src/server.ts): `initialize` → `session/prompt` → `shutdown`, with `session.event` / `session.finished` / `subagent.*` notifications over [`JsonRpcLineTransport`](src/transport.ts)). The SDK-client analogue of the [`acp`](../acp/README.md) bridge, split the same way: this package is the protocol plugin, while [`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) is the app bin that boots a `cordis.yml` around it — which process serves this protocol is a config decision, not a hardcoded bin. This plugin is the serving face of the [single-executable distribution plan](../../../docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md).
+The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-process SDK clients can drive harness agents. [`HarnessSdkServer`](src/server.ts) owns the protocol methods and notifications; [`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) supplies the surrounding `cordis.yml` application.
 
 ## Wiring
 
-`inject: ['agents']`. The server gets or creates one agent per `sessionId` from the `initialize.provider`/`initialize.model` pair. It forwards subagent completions only when the lifecycle payload's `local` flag was snapshotted from the provider's exact in-process child; reusable provider names, child ids, and durable lineage never establish locality. A registered owner for the provider route wins; an unowned `deepseek` route mounts `dsh-llm-deepseek` using `$DEEPSEEK_API_KEY` and `$DEEPSEEK_BASE_URL`, while any other unowned provider fails initialization. Persistence, tools, and other adapters come from the surrounding `cordis.yml`.
+`inject: ['agents']`. The server gets or creates one agent per `sessionId`. It forwards subagent completions only when the service-snapshotted lifecycle `local` flag is true; provider names, child ids, and durable lineage never establish locality. A registered adapter wins, an unowned `deepseek` route mounts `dsh-llm-deepseek`, and any other unowned provider fails initialization. Other capabilities come from the surrounding `cordis.yml`.
 
 ## Config
 
-No `cordis.yml`-settable keys. The `JsonRpcConfig` fields (`input`, `output`, `exit`) are runtime-only test seams so a spec can drive the server over in-memory streams without a subprocess or a killed test process; production always serves the process stdio and exits via `process.exit`.
+There are no `cordis.yml` keys. `JsonRpcConfig.input`, `output`, and `exit` are runtime-only transport seams; production uses process stdio and `process.exit`.
 
 ## stdout is the protocol
 
-The process stdout this plugin runs in carries only JSON-RPC frames. The tree that loads it must load NO stdout logger (a console logger corrupts the frames) — the guarantee is config-only, same as the ACP bridge. Diagnostics go to stderr.
+Stdout carries only JSON-RPC frames. The deployment must not compose a stdout logger; diagnostics belong on stderr.
 
 ## Shutdown and exit semantics
 
-The plugin owns the PROTOCOL-level exit: a `shutdown` request is answered first (the response frame flushes), then the plugin disposes its own fiber — running the effect disposer: an idempotent `server.shutdown()` (every SDK-created agent disposed to quiescence, event subscriptions detached) plus `transport.close()` — and exits the process with code 0. Own-fiber disposal is deliberate: the request's `server.shutdown()` already flushed all SDK-owned session state, and the process exit that follows is the teardown of the rest of the tree. Process-level exits (stdin EOF → 0, SIGTERM → 0, SIGINT → 130) belong to the app bin, which disposes the whole root context. Fiber disposal WITHOUT a `shutdown` request (HMR-style unload) just stops serving — it never exits the process.
+The plugin answers `shutdown`, disposes SDK-owned agents and subscriptions to quiescence, closes the transport, then exits with code 0. EOF and signal exits belong to the app bin, which disposes the root context. Unloading only this plugin stops serving without exiting the process.
 
 ## Wire notes
 
-`initialize.serverInfo.name` is the wire-stable `deepseek-harness-sdk-runtime` (SDK clients key on it, independent of this package's name). A session accepts at most one in-flight `session/prompt`; an overlapping prompt for the same `sessionId` fails immediately through the standard handler-error response, while other sessions remain independent and the same session can be reused after the active prompt settles. Persistence roots and the deployment persona come from `cordis.yml`; the wire exposes only parameters the server applies.
+`initialize.serverInfo.name` is the wire-stable `deepseek-harness-sdk-runtime`. A session accepts one in-flight prompt; overlap fails immediately, other sessions remain independent, and the session is reusable after settlement. Persistence roots and persona come from `cordis.yml`.
 
 ## Model Experience
 

packages/ui/jsonrpc/src/server.ts

@@ -1,13 +1,6 @@
 /**
- * `HarnessSdkServer`: the JSON-RPC method surface the `dsh-jsonrpc` plugin
- * serves to out-of-process SDK clients (e.g. the Python `deepseek_harness`
- * package). Requests: `initialize` → `session/prompt`* → `shutdown`.
- * Notifications pushed to the host: `session.event` (every durable session
- * event, verbatim), `session.finished` (per prompt turn settle),
- * `subagent.started` / `subagent.finished` (child-session lineage and run
- * outcomes). The server owns only the SDK-facing session map — the harness
- * itself is the context the plugin mounts in; plugins, persistence, and
- * the LLM adapter set all come from the external `cordis.yml`.
+ * JSON-RPC method and notification surface for out-of-process harness SDKs.
+ * The surrounding context owns plugins, persistence, and configured adapters.
  *
  * @module @deepseek-ai/dsh-jsonrpc/server
  */
@@ -23,7 +16,7 @@ import type { SubagentRunEndInfo } from '@deepseek-ai/dsh-subagent'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import type { JsonRpcTransportPeer } from './transport.ts'
 
-/** Parameters of the `initialize` request (once per process, before any prompt). */
+/** Parameters for the process-wide SDK handshake. */
 export interface InitializeParams {
   /** Working directory recorded on every SDK-created session's header. */
   cwd: string
@@ -33,16 +26,13 @@ export interface InitializeParams {
   model: string
 }
 
-/** Result of the `initialize` request: the server's identity for the SDK handshake. */
+/** Wire-stable server identity returned by initialization. */
 export interface InitializeResult {
   /** Wire-stable server identity (`deepseek-harness-sdk-runtime`) and version. */
   serverInfo: { name: string; version: string }
 }
 
-/**
- * Parameters of a `session/prompt` request: one user turn on one SDK session,
- * with at most one in flight per session.
- */
+/** One user turn on one SDK session. */
 export interface SessionPromptParams {
   /** The SDK-side session id; an unknown id lazily creates the agent+session pair. */
   sessionId: string
@@ -50,7 +40,7 @@ export interface SessionPromptParams {
   contentBlocks: ContentBlock[]
 }
 
-/** Result of a `session/prompt` request: the prompt ran to turn settle (outcome rides on `session.finished`). */
+/** Prompt acceptance after turn settlement; outcome rides on `session.finished`. */
 export interface SessionPromptResult {
   /** Always `true`; the turn outcome is the paired `session.finished` notification. */
   accepted: true
@@ -62,20 +52,12 @@ interface SessionRecord {
   activePrompt: boolean
 }
 
-/** Recover the delegating parent carried by every service-owned subagent lifecycle event. */
+/** Recover the delegating parent from the service-owned scoped carrier. */
 function subagentParentOf(carrier: Scoped<SubagentService>): Agent {
-  // SubagentService emits this lifecycle pair only through scopeTarget(this, parent).
   return carrierKeyOf(carrier) as Agent
 }
 
-/**
- * The SDK server over a booted harness context. Constructing it subscribes to
- * session and subagent lifecycle events, forwarding durable session
- * events and SDK-facing completion notifications while retaining local-run
- * identity across child disposal. The subscriptions live until
- * {@link shutdown}. One instance serves one transport peer for the process
- * lifetime — there is no re-`initialize`.
- */
+/** SDK server whose subscriptions and created agents live until {@link shutdown}. */
 export class HarnessSdkServer {
   private cwd = process.cwd()
   private provider = 'deepseek'
@@ -125,10 +107,9 @@ export class HarnessSdkServer {
   }
 
   /**
-   * Record cwd and provider/model, mounting the DeepSeek adapter only when the
-   * `deepseek` provider route has no configured owner.
-   * @param params - the SDK handshake parameters.
-   * @returns the server identity for the handshake.
+   * Configure the SDK route, mounting the DeepSeek fallback only when unowned.
+   * @param params - SDK handshake parameters.
+   * @returns server identity for the handshake.
    */
   async initialize(params: InitializeParams): Promise<InitializeResult> {
     this.cwd = resolve(params.cwd)
@@ -142,13 +123,9 @@ export class HarnessSdkServer {
   }
 
   /**
-   * Handle `session/prompt`: get-or-create the session's agent, send the
-   * content as the user message, await turn settle (quiescence), then notify
-   * `session.finished` with the settled turn's outcome. A session accepts at
-   * most one prompt at a time; an overlapping request fails immediately while
-   * other sessions remain independent.
-   * @param params - the target session id and prompt content.
-   * @returns `{ accepted: true }` after the turn settled.
+   * Run one prompt to settlement; overlap on the same session fails.
+   * @param params - target session and user content.
+   * @returns acceptance after the turn settled.
    */
   async prompt(params: SessionPromptParams): Promise<SessionPromptResult> {
     const rec = await this.getOrCreateSession(params.sessionId)
@@ -171,11 +148,9 @@ export class HarnessSdkServer {
   }
 
   /**
-   * Handle `shutdown`: dispose every SDK-created agent handle (awaiting loop
-   * quiescence), unmount the adapter fiber this server mounted (if any), and
-   * detach the event subscriptions. The CONTEXT stays up — the bin disposes it
-   * as part of process exit.
-   * @returns an empty object (the JSON-RPC result).
+   * Dispose server-owned agents, adapter, and subscriptions to quiescence.
+   * The surrounding context remains running.
+   * @returns empty JSON-RPC result.
    */
   shutdown(): Promise<Record<string, never>> {
     this.shutdownTask ??= this.performShutdown()