zcode-acp-server 0.1.0

package/dist/translators/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Internal event-dict shape — the seam between translators and the dispatcher.
+ *
+ * Both `EventTranslator` (event-stream path) and `ProjectionDiffer` (snapshot
+ * path) emit these discriminated unions; `dispatchEvent` consumes them and
+ * serialises each into an ACP `session/update` notification.
+ */
+import type { PlanEntry, ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind } from "@agentclientprotocol/sdk";
+export interface ToolCallNewEvent {
+    kind: "ToolCallNew";
+    callId: string;
+    tool: string;
+    acpKind: ToolKind;
+    status: ToolCallStatus;
+    title: string;
+    input?: unknown;
+    output?: string;
+    content?: ToolCallContent[];
+    diffContent?: ToolCallContent[];
+    locations?: ToolCallLocation[];
+}
+export interface ToolCallUpdateEvent {
+    kind: "ToolCallUpdate";
+    callId: string;
+    tool?: string;
+    status: ToolCallStatus;
+    output?: string;
+    rawOutput?: unknown;
+    rawResult?: unknown;
+    content?: ToolCallContent[];
+    diffContent?: ToolCallContent[];
+    locations?: ToolCallLocation[];
+}
+export interface UsageDeltaEvent {
+    kind: "UsageDelta";
+    used: number;
+    size: number;
+}
+export interface TextDeltaEvent {
+    kind: "TextDelta";
+    text: string;
+}
+export interface ReasoningDeltaEvent {
+    kind: "ReasoningDelta";
+    text: string;
+}
+export interface PlanUpdateEvent {
+    kind: "PlanUpdate";
+    entries: PlanEntry[];
+}
+/** A plan entry being built before dispatch (status/priority are normalised here). */
+export declare function makePlanEntry(content: string, status: string, priority?: string): PlanEntry;
+export interface FilesChangedEvent {
+    kind: "FilesChanged";
+    files: string[];
+}
+export type InternalEvent = ToolCallNewEvent | ToolCallUpdateEvent | UsageDeltaEvent | TextDeltaEvent | ReasoningDeltaEvent | PlanUpdateEvent | FilesChangedEvent;
+//# sourceMappingURL=types.d.ts.map

package/dist/translators/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/translators/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,SAAS,EAGT,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,QAAQ,EACT,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAM3F;AAcD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,mBAAmB,GACnB,eAAe,GACf,cAAc,GACd,mBAAmB,GACnB,eAAe,GACf,iBAAiB,CAAC"}

package/dist/translators/types.js

@@ -0,0 +1,27 @@
+/**
+ * Internal event-dict shape — the seam between translators and the dispatcher.
+ *
+ * Both `EventTranslator` (event-stream path) and `ProjectionDiffer` (snapshot
+ * path) emit these discriminated unions; `dispatchEvent` consumes them and
+ * serialises each into an ACP `session/update` notification.
+ */
+/** A plan entry being built before dispatch (status/priority are normalised here). */
+export function makePlanEntry(content, status, priority) {
+    return {
+        content,
+        status: normalisePlanStatus(status),
+        priority: normalisePlanPriority(priority),
+    };
+}
+function normalisePlanStatus(s) {
+    if (s === "completed" || s === "in_progress" || s === "pending") {
+        return s;
+    }
+    return "pending";
+}
+function normalisePlanPriority(p) {
+    if (p === "high" || p === "medium" || p === "low")
+        return p;
+    return "medium";
+}
+//# sourceMappingURL=types.js.map

package/dist/translators/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/translators/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4DH,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,MAAc,EAAE,QAAiB;IAC9E,OAAO;QACL,OAAO;QACP,MAAM,EAAE,mBAAmB,CAAC,MAAM,CAAC;QACnC,QAAQ,EAAE,qBAAqB,CAAC,QAAQ,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAAC,CAAS;IACpC,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,aAAa,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QAChE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,qBAAqB,CAAC,CAAqB;IAClD,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,CAAC,CAAC;IAC5D,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared utilities: logging and project-wide constants.
+ *
+ * Logging goes to stderr so it never corrupts the stdout ACP protocol stream.
+ */
+/** ACP protocol version this server speaks. */
+export declare const PROTOCOL_VERSION = 1;
+/** Agent identity advertised in the initialize response. */
+export declare const AGENT_INFO: {
+    readonly name: "zcode-acp-server";
+    readonly title: "ZCode";
+    readonly version: "0.1.0";
+};
+/** Path to the ZCode v2 config (credentials + provider/model metadata). */
+export declare const ZCODE_CREDS_PATH: string;
+/**
+ * Slash commands surfaced to the editor. Each maps to a ZCode session method
+ * that the server forwards when the user types the command.
+ */
+export declare const SLASH_COMMANDS: readonly [{
+    readonly name: "compact";
+    readonly description: "Compress conversation context (free up tokens)";
+}, {
+    readonly name: "goal";
+    readonly description: "Set or show the session goal";
+    readonly input: {
+        readonly hint: "goal description";
+    };
+}, {
+    readonly name: "fork";
+    readonly description: "Fork the session at the latest checkpoint";
+}, {
+    readonly name: "rewind";
+    readonly description: "Rewind workspace files to the latest checkpoint";
+}, {
+    readonly name: "steer";
+    readonly description: "Append an instruction to a running turn";
+    readonly input: {
+        readonly hint: "content";
+    };
+}, {
+    readonly name: "mode";
+    readonly description: "Switch permission mode (plan/build/edit/yolo)";
+    readonly input: {
+        readonly hint: "plan|build|edit|yolo";
+    };
+}, {
+    readonly name: "model";
+    readonly description: "Switch the session model";
+    readonly input: {
+        readonly hint: "GLM-5.2|GLM-5-Turbo";
+    };
+}, {
+    readonly name: "thought";
+    readonly description: "Set the reasoning effort";
+    readonly input: {
+        readonly hint: "max|high|nothink";
+    };
+}];
+/** Static metadata for the configOptions selects (model/mode/thought). */
+export declare const CONFIG_META: {
+    readonly model: {
+        readonly name: "Model";
+        readonly category: "model";
+        readonly options: Array<{
+            value: string;
+            name: string;
+        }>;
+    };
+    readonly mode: {
+        readonly name: "Mode";
+        readonly category: "mode";
+        readonly options: readonly [{
+            readonly value: "plan";
+            readonly name: "plan";
+        }, {
+            readonly value: "build";
+            readonly name: "build";
+        }, {
+            readonly value: "edit";
+            readonly name: "edit";
+        }, {
+            readonly value: "yolo";
+            readonly name: "yolo";
+        }];
+    };
+    readonly thought: {
+        readonly name: "Thought Level";
+        readonly category: "thought_level";
+        readonly options: readonly [{
+            readonly value: "max";
+            readonly name: "max";
+        }, {
+            readonly value: "high";
+            readonly name: "high";
+        }, {
+            readonly value: "nothink";
+            readonly name: "nothink";
+        }];
+    };
+};
+/** configId → zcode method + param key (model deliberately absent — switch via runtimeModel). */
+export declare const CONFIG_DISPATCH: Record<string, {
+    method: string;
+    paramKey: string;
+}>;
+/** Verbose diagnostic log. Only emitted when `ZCODE_ACP_DEBUG=1`. */
+export declare function log(msg: string): void;
+/** Warning — always emitted. For perceivable failures. */
+export declare function warn(msg: string): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,4DAA4D;AAC5D,eAAO,MAAM,UAAU;;;;CAIb,CAAC;AAEX,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,QAK5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BjB,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,WAAW;;;;0BAIL,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqB/C,CAAC;AAEX,iGAAiG;AACjG,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAGhF,CAAC;AAoBF,qEAAqE;AACrE,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGrC;AAED,0DAA0D;AAC1D,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtC"}

package/dist/utils.js

@@ -0,0 +1,110 @@
+/**
+ * Shared utilities: logging and project-wide constants.
+ *
+ * Logging goes to stderr so it never corrupts the stdout ACP protocol stream.
+ */
+import path from "node:path";
+import process from "node:process";
+/** ACP protocol version this server speaks. */
+export const PROTOCOL_VERSION = 1;
+/** Agent identity advertised in the initialize response. */
+export const AGENT_INFO = {
+    name: "zcode-acp-server",
+    title: "ZCode",
+    version: "0.1.0",
+};
+/** Path to the ZCode v2 config (credentials + provider/model metadata). */
+export const ZCODE_CREDS_PATH = path.join(process.env.HOME || process.env.USERPROFILE || "~", ".zcode", "v2", "config.json");
+/**
+ * Slash commands surfaced to the editor. Each maps to a ZCode session method
+ * that the server forwards when the user types the command.
+ */
+export const SLASH_COMMANDS = [
+    { name: "compact", description: "Compress conversation context (free up tokens)" },
+    {
+        name: "goal",
+        description: "Set or show the session goal",
+        input: { hint: "goal description" },
+    },
+    { name: "fork", description: "Fork the session at the latest checkpoint" },
+    { name: "rewind", description: "Rewind workspace files to the latest checkpoint" },
+    {
+        name: "steer",
+        description: "Append an instruction to a running turn",
+        input: { hint: "content" },
+    },
+    {
+        name: "mode",
+        description: "Switch permission mode (plan/build/edit/yolo)",
+        input: { hint: "plan|build|edit|yolo" },
+    },
+    {
+        name: "model",
+        description: "Switch the session model",
+        input: { hint: "GLM-5.2|GLM-5-Turbo" },
+    },
+    {
+        name: "thought",
+        description: "Set the reasoning effort",
+        input: { hint: "max|high|nothink" },
+    },
+];
+/** Static metadata for the configOptions selects (model/mode/thought). */
+export const CONFIG_META = {
+    model: {
+        name: "Model",
+        category: "model",
+        options: [],
+    },
+    mode: {
+        name: "Mode",
+        category: "mode",
+        options: [
+            { value: "plan", name: "plan" },
+            { value: "build", name: "build" },
+            { value: "edit", name: "edit" },
+            { value: "yolo", name: "yolo" },
+        ],
+    },
+    thought: {
+        name: "Thought Level",
+        category: "thought_level",
+        options: [
+            { value: "max", name: "max" },
+            { value: "high", name: "high" },
+            { value: "nothink", name: "nothink" },
+        ],
+    },
+};
+/** configId → zcode method + param key (model deliberately absent — switch via runtimeModel). */
+export const CONFIG_DISPATCH = {
+    mode: { method: "session/setMode", paramKey: "mode" },
+    thought: { method: "session/setThoughtLevel", paramKey: "thoughtLevel" },
+};
+/**
+ * Logging. Two levels, both write to stderr (stdout is reserved for the ACP
+ * JSON-RPC stream):
+ *   - `warn(msg)`: always emitted — failures the user can perceive (fatal
+ *     exit, broken backend pipe, command/permission failures, etc.).
+ *   - `log(msg)`: verbose diagnostic detail — only emitted when
+ *     `ZCODE_ACP_DEBUG=1` is set. Default (unset) keeps the log quiet so
+ *     a stable bridge doesn't spam `Zed.log`.
+ *
+ * Never use `console.log` — it would corrupt the stdout protocol stream.
+ */
+/** True when the user opted into verbose diagnostics.
+ *  Read at call time so tests can flip it without re-importing the module. */
+function isDebug() {
+    return process.env.ZCODE_ACP_DEBUG === "1";
+}
+/** Verbose diagnostic log. Only emitted when `ZCODE_ACP_DEBUG=1`. */
+export function log(msg) {
+    if (!isDebug())
+        return;
+    process.stderr.write(`[zcode-acp] ${msg}\n`);
+}
+/** Warning — always emitted. For perceivable failures. */
+export function warn(msg) {
+    process.stderr.write(`[zcode-acp] ${msg}\n`);
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,299 @@
+# zcode-acp-server Architecture
+
+## Overview
+
+`zcode-acp-server` bridges the headless ZCode CLI (`zcode app-server --stdio`) to
+ACP (Agent Client Protocol) compatible editors. It is the translation layer
+between ZCode's internal JSON-RPC event stream and the standard ACP protocol.
+
+## Layered Architecture
+
+```
+application-client (Zed / JetBrains)
+  session/update
+       |
+       v
+zcode-acp-server (stdio JSON-RPC ACP)
+  |-- handlers/     session, extensions, dispatch, server-requests, io, slash
+  |-- translators/    event-translator, projection-differ, tool-helpers
+  |-- interaction/    adapter
+  |-- config/         options, runtime-model, model-cache
+  |-- backend/        client, listener, types
+  |-- server.ts       ZcodeAcpServer
+       |
+       v
+zcode app-server --stdio (line-delimited JSON)
+```
+
+## Core Data Flow
+
+### 1. Session lifecycle
+
+```
+session/new → session/create → register EventListener
+     |
+prompt request → session/send → EventTranslator translates → dispatchEvent
+     |                                  |
+  end_turn / cancelled         session/update notification
+```
+
+### 2. Event stream subscription
+
+```
+EventStreamListener.subscribe()
+  |
+session/subscribe (deliveryKind: "desktop-continuous")
+  |
+ZCode pushes session/event → handleEvent()
+  |
+pollEvent() consumes → EventTranslator.translate()
+```
+
+### 3. Dual-path event handling
+
+#### Real-time path (EventTranslator)
+- Listens to zcode `session/event` pushes
+- Translates each event to an ACP `session/update` in real time
+- Maintains `seenToolIds` to avoid duplicates
+
+#### Snapshot path (ProjectionDiffer)
+- On turn completion, builds a snapshot from `session/messages` + `session/read`
+- Diffs two snapshots to produce new events (PlanUpdate / TextDelta / ToolCallNew, etc.)
+- Used for turn-completion triage and stall recovery
+
+### 4. Dual-path deduplication
+
+```
+EventTranslator (real-time path)
+  ├── seenToolIds: Set<string>
+  └── turnDone: boolean
+         |
+         v
+ProjectionDiffer (snapshot path)
+  ├── seenToolIds: Set<string>
+  ├── lastToolStatus: Map<string, string>
+  └── seenMessageIds: Set<string>
+         |
+         v
+    dispatchEvent (single exit point)
+```
+
+Key: **`seenToolIds` synchronization**
+
+In `session.ts:629`, after the event path finishes processing, the state is
+synced to the differ:
+```typescript
+for (const seenId of translator.seenToolIds) {
+  differ.markToolSeen(seenId);
+}
+```
+
+This ensures the snapshot diff does not re-emit tools already handled by the
+event path, preventing Bash terminal output from being overwritten by a
+content-less ToolCallNew.
+
+## Module Responsibilities
+
+### `backend/` — ZCode process communication
+
+| File | Responsibility |
+|------|------|
+| `client.ts` | Spawn/manage the zcode subprocess, reader-loop, request/response multiplexing, process watchdog |
+| `listener.ts` | EventStreamListener (subscribe/consume the event stream) and TurnMonitor (snapshot polling) |
+| `types.ts` | ZCode JSON-RPC message type definitions |
+
+### `translators/` — Event translation
+
+| File | Responsibility |
+|------|------|
+| `event-translator.ts` | Translate zcode events to InternalEvent (real-time path) |
+| `projection-differ.ts` | Diff two snapshots to produce InternalEvent (snapshot path) |
+| `tool-helpers.ts` | Tool-related pure functions: title generation, output rendering, diff parsing, location extraction |
+| `types.ts` | InternalEvent union type and plan entry builders |
+
+### `handlers/` — ACP method handling
+
+| File | Responsibility |
+|------|------|
+| `session.ts` | session/new/list/resume/load/prompt/set_config_option/cancel |
+| `extensions.ts` | fork/rewind/rewindCascade/goal/compact/steer/cancelBackgroundTask/setModel/setMode/setThoughtLevel |
+| `dispatch.ts` | dispatchEvent single exit point: InternalEvent → ACP session/update |
+| `server-requests.ts` | Handle zcode interaction/* requests (tool auth, ExitPlanMode, AskUserQuestion), protocol negotiation routing |
+| `io.ts` | ACP notification helpers (including `sendAvailableCommandsDeferred` deferred notification) |
+| `slash.ts` | Interception of `/`-prefixed commands (/compact /goal /fork /rewind /steer /model /mode /thought) |
+
+### `interaction/` — Interaction bridging
+
+| File | Responsibility |
+|------|------|
+| `adapter.ts` | Conversion adapter from zcode interaction requests to ACP (requestPermission + elicitation form) |
+
+### `config/` — Configuration management
+
+| File | Responsibility |
+|------|------|
+| `options.ts` | configOptions / modes construction, set_config_option dispatch |
+| `runtime-model.ts` | runtimeModel overlay construction and application |
+| `model-cache.ts` | Model ID cache and usage initialization |
+
+## Key State Machines
+
+### Turn state
+
+```
+          subscribe
+              |
+         turn.started
+              |
+    +---------------------+
+    | model.streaming     |
+    | tool.updated        |
+    | session.updated     |
+    +---------------------+
+              |
+    +---------------------+
+    | turn.completed      | -> end_turn
+    | turn.failed         | -> error
+    | turn.cancelled      | -> cancelled
+    | timeout (120s)      | -> max_turn_requests
+    | manual cancel       | -> cancelled
+    +---------------------+
+```
+
+### Tool lifecycle
+
+```
+scheduled  ->  started  ->  progress  ->  result/error
+   |            |            |
+ToolCallNew  status=in_progress  output (stdoutTail)
+   |
+(seenToolIds.add)
+```
+
+## Interaction Protocol Negotiation
+
+ZCode `interaction/*` requests are routed to different ACP client interaction
+mechanisms via protocol negotiation:
+
+```
+zcode interaction request received
+  │
+  ├─ Tool auth (interaction/requestPermission)
+  │     └─ Always uses session/request_permission (its native purpose)
+  │
+  ├─ ExitPlanMode (interaction/requestUserInput + plan_approval)
+  │     ├─ Client supports elicitation.form → elicitation/create (approve/reject form)
+  │     └─ Otherwise → session/request_permission (fallback)
+  │
+  └─ AskUserQuestion (interaction/requestUserInput)
+        ├─ Client supports elicitation.form → elicitation/create (single form)
+        └─ Otherwise → per-question session/request_permission (fallback)
+```
+
+**Key**: `server.supportsElicitationForm()` is detected at `initialize` time from
+`clientCapabilities.elicitation.form`. Tool auth always goes through
+request_permission, since that is its native purpose.
+
+## Deferred Notification Mechanism
+
+The `available_commands_update` notification must be sent **after** the session
+response; otherwise the client's session state machine is not yet ready and
+drops the notification, leaving the `/` completion menu empty.
+
+```
+session/new|resume|load handler
+  │
+  ├─ call newSession()/resumeSession()/loadSession()
+  │
+  ├─ sendAvailableCommandsDeferred(cx, sid, SLASH_COMMANDS)
+  │     └─ enqueue, send after 50ms (fire-and-forget)
+  │
+  └─ return response
+       │
+       └─ after the response is written to stdout, the 50ms timer fires sendAvailableCommands
+```
+
+`sendAvailableCommandsDeferred` (`io.ts`) encapsulates the 50ms delay logic,
+mirroring the Python bridge's `_pending_post_notifs` queue +
+`_drain_post_notifs` mechanism.
+
+## Mode Reconciliation
+
+The session mode can change through four entry points, all of which must
+notify the editor UI:
+
+| Trigger | Path | Notifies UI |
+|------|------|:---:|
+| `session/setMode` request | `extensions.ts:setMode` | yes |
+| `session/set_config_option` (mode) | `session.ts:setConfigOptionHandler` → `emitConfigOptionUpdate` | yes |
+| `/mode` slash command | `slash.ts` → `emitConfigOptionUpdate` | yes |
+| In-turn `EnterPlanMode`/`ExitPlanMode` | reconciled at turn completion | yes |
+
+The in-turn path bypasses the bridge entirely, so `prompt()` runs
+`emitModeIfChanged` (`session.ts`) at turn completion: it re-reads the
+authoritative mode via `buildModes`, compares against `server.lastMode`
+(the value last advertised to the client), and emits
+`current_mode_update` + `config_option_update` when they differ. Failures are
+swallowed so they cannot break the turn-completion path.
+
+## Prompt-Lock Release on Stop
+
+`session/stop` is fire-and-forget, but ZCode has a startup delay: when stop
+arrives before the turn truly holds the lock the backend ignores it, the turn
+runs on, and the lock leaks (next `session/send` fails with
+"A prompt is already running").
+
+`ensureTurnStopped` (`session.ts`) closes this gap. It mirrors the
+`expectLock:true` strategy from `waitForTurnIdle` (`extensions.ts`):
+
+1. send `session/stop`
+2. poll `session/goal show`; first REQUIRE seeing "prompt is running" once
+   (proves the turn started), then wait for it to clear
+3. if an 8s grace window elapses without ever seeing the lock, the turn never
+   started (stop caught it in time) or already ended → treat as released
+4. hard timeout 30s
+
+It is used at every stop site: the cancel check, the stall no-output path,
+the turn cancelled/failed result, the 120s no-progress timeout, and the
+`session/send` error path. Never throws (failures only log) so it cannot
+break the cancel path.
+
+## Process Watchdog
+
+`close()` reaps the zcode process group via `process.kill(-pid)`, but only
+when the bridge exits cleanly enough for its signal handlers to fire
+(SIGTERM/SIGINT). If the bridge is SIGKILLed (Zed force-kill on reconnect,
+crash, OOM), the handler never runs and the zcode subprocess group is
+orphaned.
+
+The watchdog (`backend/client.ts:startWatchdog`) closes that gap. It is a tiny
+detached child that polls the bridge pid every 2s and, once the bridge is
+gone, sends SIGKILL to the zcode process group, then exits. It is its own
+process-group leader and `unref`'d, so it never holds the event loop open and
+is not part of the zcode group it kills. It self-terminates as soon as the
+zcode process exits, so a normal shutdown leaves no lingering watchdog.
+
+## Design Decisions
+
+### Why a dual path?
+
+| Scenario | Real-time path | Snapshot path |
+|------|---------|----------|
+| Normal streaming | Low latency | Must wait for turn end |
+| Lost events | Loses data | Recovers from snapshot |
+| Deduplication | seenToolIds | seenMessageIds + markToolSeen() |
+| Turn-completion triage | Not triggered | PlanUpdate / usage_update |
+
+### Why no polling fallback?
+
+ZCode CLI 0.14.5 ~ 0.14.7 used `session/read` polling to emulate streaming.
+0.14.8+ introduced `session/subscribe` event push, which has lower latency and
+is more reliable. This project supports only 0.14.8+ and has removed the
+polling fallback code.
+
+### Why does ProjectionDiffer need to persist across turns?
+
+- `seenMessageIds`: prevents historical messages from being re-emitted after resume
+- `lastToolStatus` + `seenToolIds`: ensures tool state is not lost across turns
+- `lastUsage`: avoids duplicate usage_update pushes
+- `lastPlanSig`: emits only when the plan changes