@kodax-ai/kodax 0.7.96-rc.9 → 0.7.97-alpha.1

package/CHANGELOG.md

@@ -8,6 +8,279 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.7.97-alpha.1] - 2026-10-08
+
+First alpha of the v0.7.97 line: FEATURE_298's unified product Host and
+client contract. The interactive product pins to the independent Host, one
+shared session contract carries data, control, and information semantics to
+every consumer, and execution funnels through one prepared action. Every
+v0.7.96 stable contract is retained. npm publication remains a manual
+maintainer action.
+
+### Added
+
+- Shared product session contract and SDK entry: `KodaXProductClient`
+  through `/client` exposes sessions, goals, notices, paged history reads,
+  and Host-estimated token accounting to product consumers (T01, T09, T32).
+- The interactive REPL pins to the independent Host: session-command
+  mutations, `/compact`, `/goal`, full-text queue retention with atomic
+  pull-back, prompt input artifacts, and canonical session writes route
+  through the Host plane (T27, T34).
+- Host-owned planes replace client-side reimplementations: queued inputs
+  with batching and withdrawal (T06), steer/redirect/explicit-stop delivery
+  with required target runs (T07), one permission authority (T14), skills
+  preparation expanded at consumption (T37), declarative workflow start and
+  control operations (T22), memory management (T36), per-session MCP
+  persistence with typed catalogs (T12), A2A serving from bootstrap listen
+  config (T21), agent registry and Actor collaboration (T30), invocations
+  preparation over RPC for all interactive faces (T37), session derivation
+  by fork or deterministic recovery seed (T10), lineage selection/labels/
+  rewind (T11), and conservative legacy-run reads with event repair (T33).
+
+### Fixed
+
+- Preserve canonical history and ordinary browsing: complete canonical items
+  restore before identity assignment, reverse wheel input routes from frozen
+  windows, browse waiting is bounded and cancellable, partial pages keep the
+  final answer after older tools, and quoted managed protocol markers no
+  longer truncate ordinary assistant answers (Issues 344-349).
+- Host command failures stay visible with their feedback, late observation
+  cleanup keeps its diagnostics, and Host message counts drive `/new`.
+- Frontmatter hooks execute on Linux: the default hook contract no longer
+  pairs the bash contract with `/bin/sh`, which is dash on Debian/Ubuntu and
+  rejected every hook at shell environment resolution (Issue 354).
+- Crash recovery proceeds after a `SIGKILL`ed daemon on Linux: a zombie pid
+  waiting for its parent to reap it is no longer classified as a live
+  competing owner (Issue 355).
+- Release validation hardened the interactive fixtures (CI static-output
+  detection, learning-review request classification), raised the
+  machine-relative long-line layout budget on CI evidence (Issues 356-358;
+  358 remains open for profiling), and aligned the release binary provider
+  smoke with Host-owned execution by seeding every provider's key env per
+  probe.
+
+---
+
+## [0.7.96] - 2026-10-01
+
+Stable release of the v0.7.96 line, finalizing the fourteen release
+candidates: trusted text transactions and platform shell containment across
+Windows, Linux, and macOS; Windows daemon lifecycle arbitration with
+nonblocking uncertain Shell cleanup; turn-matched interrupted-Run recovery
+across Runs; provable tool-history pairing and compaction-copy tracing;
+macOS system Git preflight; provider authentication isolation; single-writer
+Runtime transcript ownership in Ink sessions; and Windows NUL-ACE startup
+recovery. CI runs inside the tag-triggered Release workflow. Every rc.14
+contract is retained; open items remain tracked in `docs/KNOWN_ISSUES.md`.
+npm publication remains a manual maintainer action.
+
+---
+
+## [0.7.96-rc.14] - 2026-10-01
+
+Fourteenth release candidate of the v0.7.96 line: interrupted-Run recovery
+reaches coding Runs and managed execution with budgeted turn-matched
+records, tool-history pairing and compaction-copy tracing become provable,
+Anthropic-compatible providers ignore inherited `ANTHROPIC_AUTH_TOKEN`, the
+Ink host defers to the Runtime as the single transcript writer, and Windows
+interactive startup re-verifies the NUL account ACE behind a current setup
+marker after a reboot. CI now runs inside the tag-triggered Release
+workflow instead of on branch pushes. Every rc.13 contract is retained. npm
+publication remains a manual maintainer action.
+
+### Fixed
+
+- Interactive Windows startup verifies the live NUL sandbox-account grant
+  before trusting the durable setup marker. Missing access enters the existing
+  setup recovery boundary; installation omits historical read roots whose
+  files disappeared. SDK/daemon startup and ordinary admission remain
+  read-only and do not activate setup automatically (Issue 341).
+- Windows sandbox unit tests provision mock-SID artifacts and remove recovery
+  fixtures in a private temporary native cache, so they no longer interfere
+  with live sandbox commands using the host's shared cache. The native
+  provisioning suite still requires an ordinary host token (Issue 343).
+- Tool-history validation pairs calls with results across the whole assistant
+  scope, so an internal managed-run context message between them no longer
+  strips both halves of the pair (Issue 340).
+- Failed managed provider calls hand back the Runner transcript they received,
+  not provider-normalized request copies, so compatibility cleanup never becomes
+  persisted history.
+- Conversation resolution restores active-path entries damaged by the old
+  adjacent-only cleanup when a retained sibling chain reproduces the damage
+  exactly; unproven cases stay ambiguous. The page cache version is bumped so
+  existing v6 caches rebuild once.
+- The next managed or coding Run of a Session receives a labelled, bounded,
+  transient record of journaled progress from an earlier unfinished Run on the
+  active branch: confirmed results, operations whose result is unknown, and
+  unconfirmed excerpts of assistant text the Run streamed but never saved. The
+  record is never saved and each part disappears once history contains it.
+  Operations from every included Run take the size bound before any excerpt.
+  Operations match history per turn, so a provider reusing a tool call id in a
+  later turn no longer hides an earlier unfinished operation, and the source
+  tracing also covers histories compacted again before this fix.
+- Conversation resolution traces a compaction copy of a copy back to its first
+  retained predecessor, so re-compacted history no longer shows the same
+  message twice. When an older compaction boundary cannot be proven, history
+  is truncated at that boundary and reported as `partial` with
+  `compaction_history_truncated`, instead of flattening unproven regions into
+  one conversation. The page cache version is bumped to 9.
+- Anthropic-compatible providers no longer pick up an inherited
+  `ANTHROPIC_AUTH_TOKEN`. The SDK sent it as a Bearer header next to the
+  provider key, so gateways such as zhipu-coding and deepseek returned 401 and
+  the Anthropic token reached a third-party endpoint. The native Anthropic
+  provider is unchanged.
+- Compare PowerShell-emitted native artifact and control-directory paths
+  through long-form realpaths when the literal comparison disagrees.
+  PowerShell's `GetFullPath` expands 8.3 path components, so a runner whose
+  `TEMP` root uses a short name (`C:\Users\RUNNER~1\...`) made the private
+  test native-artifact cache provisioning fail with an unexpected-path error
+  even though the provisioner returned the canonical destination.
+- The interactive REPL no longer forks a duplicate branch every round when a
+  Runtime owns the Session. The host stops writing its own lineage. Storage
+  reconciles host saves against the Runtime's durable lineage, and the host
+  continues from the Runtime's entry ids. That fixes three problems:
+  - The next host save no longer replaces the Runtime's branch.
+  - A crash between the two writes no longer leaves a permanent fork.
+  - A Run cancelled before it produced a result no longer clears the host's
+    transcript copy.
+
+### Changed
+
+- CI runs through `workflow_call` or manual dispatch instead of branch pushes
+  and pull requests. Tag and manually dispatched release builds run the full
+  reusable CI workflow before their build matrix.
+
+### Documentation
+
+- Align the public SDK guide with read-only legacy history repair, partial
+  compaction truncation, transient interrupted-Run recovery, and Runtime-owned
+  transcript persistence. Document the CLI-only NUL recovery boundary and
+  provider authentication isolation.
+- Track unexpected interactive REPL exit as unresolved (Issue 342). Successful
+  SDK concurrency and full-TTY trace replay do not resolve that failure.
+
+---
+
+## [0.7.96-rc.13] - 2026-09-29
+
+Thirteenth release candidate of the v0.7.96 line: Runtime-owned managed
+runs persist generated output at Runner commit boundaries so an interrupted
+run keeps its transcript instead of losing it with a hung request. Every
+rc.12 contract is retained. npm publication remains a manual maintainer
+action.
+
+### Fixed
+
+- Runtime-owned managed runs persist generated assistant messages and tool results
+  at Runner commit boundaries, before tools or subsequent provider calls can hang.
+  Persist the current compacted transcript and queued-input identities; do not
+  repeatedly save old input messages or change host-owned persistence timing.
+
+---
+
+## [0.7.96-rc.12] - 2026-09-28
+
+Twelfth release candidate of the v0.7.96 line: uncertain Shell cleanup no
+longer blocks conversations, Runner iteration progress becomes observable,
+exhausted Actor children settle with honest structured results, and the test
+toolchain upgrades to Vitest 4. Every rc.11 contract is retained. npm
+publication remains a manual maintainer action.
+
+### Fixed
+
+- Return exhausted Shell cleanup diagnostics and partial output to the model
+  without cancelling its Run. Keep unresolved process identities as deferred
+  cleanup, allow successors and close, and accept queued input during Stop.
+- Expose Root Runner iteration progress in Runtime live snapshots and structured
+  Actor iteration progress in durable turn summaries/output. Values come from
+  the executing Runner; the default managed Root (500) and native Actor child
+  (200) thresholds are unchanged.
+- Settle exhausted native Actor children as failed with terminationReason
+  iteration_limit, preserving partial output, artifacts and structured results.
+  Parent completion notifications include the reason. Exhaustion no longer runs
+  a structured-output repair or workflow digest, and follow-up starts a fresh
+  iteration count. Completion on the final permitted iteration remains successful.
+
+### Changed
+
+- Upgrade the test toolchain to Vitest 4.1.11 (with `@vitest/coverage-v8`
+  4.1.11 and pinned vite 7.3.3/vite-node) and fflate ^0.8.3, which fixes a
+  ZIP64 directory scan that never terminated when a compressed-size sentinel
+  was present without the required `0x0001` extra field; skill archive
+  regression coverage locks the fix in.
+
+### Documentation
+
+- Document the embedder-owned Electron `safeStorage` credential storage
+  lifecycle: on Windows, the `Local State` encryption state must be preserved
+  together with the ciphertext across cleanup, uninstall, reinstall, and
+  profile migration, and an undecryptable existing client secret surfaces a
+  terminal credential recovery error instead of a silent replacement.
+
+---
+
+## [0.7.96-rc.11] - 2026-09-23
+
+Eleventh release candidate of the v0.7.96 line: SDK-owned background Git
+calls on macOS preflight the system Git shim so a machine without usable
+command-line developer tools no longer receives repeated Apple installation
+prompts. Every rc.10 contract is retained. npm publication remains a manual
+maintainer action.
+
+### Fixed
+
+- Preflight the macOS system Git shim before SDK-owned Git calls
+  (`@kodax-ai/agent/runtime/macos-git`): the shared platform guard detects
+  the known developer-tools-missing condition only (exit code 2,
+  `DEVELOPER_DIR`-aware), caches probes with a bounded TTL, shares one probe
+  across concurrent callers, and recovers after installation with no
+  permanent disable state. Repo-intelligence, worktree, changed-diff,
+  managed-task checkpoint, agent-adapter, worktree-sweep, session-snapshot,
+  REPL helpers, and synchronous memory paths apply the guard while ordinary
+  Git on `PATH`, independent Git installations, and arbitrary Bash/PTY
+  commands remain unchanged (Issue 339). Worktree operations keep actionable
+  errors; synchronous memory identity keeps its remote-based identity and
+  local-path fallback rules. Native macOS on-device UI verification remains
+  recommended on real hardware.
+
+---
+
+## [0.7.96-rc.10] - 2026-09-22
+
+Tenth release candidate of the v0.7.96 line: Runtime shutdown now owns and
+drains the background work it starts, Edits-mode text tools no longer reject
+ordinary project files when a workspace root contains protected native state,
+and the MCP image-validation cancellation fixture is stabilized. Every rc.9
+contract is retained. npm publication remains a manual maintainer action.
+
+### Fixed
+
+- Drain owned managed terminal maintenance on Runtime close: the optional
+  repo-intelligence/artifact maintenance factory is registered with its own
+  Runtime before it can start, close stops accepting new optional maintenance
+  and waits for existing owned work before releasing Actor, executor, and
+  owner-liveness resources, so test workspaces are no longer held after
+  `Runtime.close()` returns. Run completion, successor admission, and Stop
+  stay independent of maintenance; shared repo caches are not cancelled.
+- Own and settle memory work on shutdown: Runtime registers its memory
+  setup/finalization IO and background review drains before execution; close
+  refuses new work, cancels pending review requests, and awaits
+  already-started work before releasing the owner. Managed execution finishes
+  its required durable memory finalization before publishing completion, the
+  classic finalizer owns learned-Skill outcome and binding-release IO, and
+  branch-authority setup checks cancellation before prompt/Git work. A caller
+  signal already aborted at entry settles as an interrupt terminal (defined
+  `KodaXResult`, terminal `onComplete`) instead of a raw rejection, keeping
+  the CAP-005-001b and CAP-086-003 contracts.
+- Scope trusted text transaction cache protection to the authorized canonical
+  target: Edits-mode `edit`/`write` no longer fail with `Runtime write policy
+  targets protected native text state` for ordinary project files when a
+  workspace root contains the protected native cache (for example a home
+  root). Development artifact trust still checks every authorized write root,
+  so a writable manifest cannot redefine trusted native bytes.
+
+---
+
 ## [0.7.96-rc.9] - 2026-09-21
 
 Ninth release candidate of the v0.7.96 line: Windows daemon startup trees

package/README.md

@@ -424,21 +424,30 @@ const result = await runKodaX(
 
 ## Runtime SDK and daemon
 
-SDK hosts can use `@kodax-ai/kodax/runtime` in three forms: inline embedded for
-lowest latency, Worker-hosted embedded for private state plus hard V8 disposal,
-or a local daemon shared by REPL, Space, IDE adapters, and custom SDK clients.
-All three expose the same `KodaXRuntime` services.
+For shared Sessions, use `KodaXProductClient` from `@kodax-ai/kodax/client`.
+The Host owns execution, settings and persistence; the UI submits inputs,
+answers Host interactions and replaces its display from `sessions.observe`.
+See the [Client contract](docs/CLIENT_CONTRACT.md), [SDK migration guide](docs/SDK_MIGRATION.md),
+and [integration example](public_docs/sdk/embedder-guide.md#product-client-integration).
 
 ```ts
-import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
-
-const isolated = await createKodaXRuntime({
-  mode: 'embedded',
-  isolation: 'worker',
-  requirements: { hardDispose: true },
-});
+import { ensureKodaXClient } from '@kodax-ai/kodax/client';
+
+const client = await ensureKodaXClient();
+try {
+  const sessions = await client.sessions.list();
+  process.stdout.write(`Sessions: ${sessions.length}\n`);
+} finally {
+  await client.disconnect(); // Shared Host and Runs remain alive.
+}
 ```
 
+`connectKodaXClient` attaches without starting or replacing a Host. The Node
+connector does not provide browser HTTP/WebSocket transport. The retained
+`/runtime` inline/daemon APIs are for explicit low-level Host integration;
+Worker-hosted embedded Runtime is removed. The following structured-failure
+reference is scoped to that low-level API, not fields promised by Product Client.
+
 ### Structured Runtime failures
 
 Since v0.7.96, when Runtime has a structured failure fact, failed/cancelled runs
@@ -470,47 +479,21 @@ collections, URLs, full local paths, stacks, or raw `Error` objects into
 See [Structured Runtime failures](public_docs/sdk/embedder-guide.md#structured-credential-safe-runtime-failures)
 for the field contract, taxonomy, migration guidance, and security boundary.
 
-Inline is private and lowest-overhead; Worker is private and hard-disposable;
-daemon is process-isolated and shared. `runtime.close()` closes private
-inline/Worker ownership, but only detaches one daemon client. Contradictory
-isolation options fail instead of silently selecting a weaker mode. Worker
-isolation is a V8 fault boundary, not a security sandbox.
-
-Because a daemon is intentionally persistent, tests that auto-start one must
-also run `kodax daemon stop --home <dir> --profile <name>` (or send authenticated
-`runtime.shutdown`) before deleting their temporary home. A remaining Node
-process is not safe to kill by name alone; verify its command line and owner.
+The product CLI uses the shared Host; `--runtime-mode`, `KODAX_RUNTIME_MODE`
+and the `runtimeMode` config key are removed. Explicit low-level inline
+embedding retains private ownership, while daemon clients detach independently.
+Worker-hosted embedded Runtime is no longer an option.
 
 ```bash
 kodax daemon start
+kodax -p "Review this repository"
 kodax daemon stop --profile default
-kodax --runtime-mode daemon
-kodax -p "Review this repository" --runtime-mode daemon
 ```
 
-All CLI task forms now use the same Runtime path: interactive REPL, positional
-prompts, slash-command prompts, and `kodax -p`. Select the persistent default in
-`~/.kodax/config.json`:
-
-```json
-{
-  "runtimeMode": "daemon"
-}
-```
-
-Resolution order is explicit CLI/SDK option > environment variable >
-`config.json` > built-in default (`embedded`). `KODAX_RUNTIME_MODE=daemon` is a
-temporary environment override. The same rule applies to other paired settings,
-for example `provider` ↔ `KODAX_PROVIDER` and `effort` ↔ `KODAX_EFFORT`.
-JSON names stay camelCase while environment names use `KODAX_UPPER_SNAKE_CASE`.
-
-By default, daemon state, config, and runtime session storage use the exact
-resolved `KODAX_HOME` (normally `<OS user home>/.kodax`), so CLI and SDK clients
-converge on the same local daemon even when `KODAX_HOME` is an arbitrary custom
-directory. The high-level `createKodaXRuntime({ mode: 'daemon' })` API starts or
-reuses that daemon unless you pass an explicit endpoint/transport or
-`autoStartDaemon: false`. An explicit `--home <dir>` or `homeDir` selects the
-isolated `<dir>/.kodax` namespace for tests, CI, or project-local experiments.
+Tests that start an isolated Host must close that exact Host after its work has
+settled, before removing its temporary home. Never stop arbitrary Node processes.
+With no explicit home, CLI and SDK use the resolved `KODAX_HOME`; explicit
+`homeDir` / `--home` selects a base directory containing `.kodax`.
 
 **v0.7.71 packaged Electron patch:** packaged/asar Electron hosts can use daemon
 auto-start without relaunching the GUI. `ELECTRON_RUN_AS_NODE` is limited to a
@@ -616,7 +599,7 @@ FEATURE_280 was explicitly rescheduled to v0.7.81 (then to v0.7.86 on
 Issue 256 was explicitly rescheduled to v0.7.84 and is likewise not represented
 as shipped by this release.
 
-**v0.7.80 hardening release:** The CLI honors `worker.configuredA2A` in
+**v0.7.80 hardening release:** The CLI honored `worker.configuredA2A` in
 `~/.kodax/config.json`: the embedded Runtime becomes Worker-hosted and loads
 the configured A2A plane inside the Worker owner, so configured outbound
 Agents appear as `external:<name>` in `list_dispatchable_agents` and can be
@@ -786,6 +769,84 @@ provider's model, REPL `/compact` clears the UI only after a durable save, and
 successful reports carry bounded `summaryRequests` plus `commitMs` per
 physical summary call.
 
+**v0.7.97-alpha.1 release:** First alpha of the v0.7.97 line — FEATURE_298's
+unified product Host and client contract. The interactive REPL pins to the
+independent Host; the shared product session contract (`KodaXProductClient`
+through `/client`) carries sessions, goals, notices, paged history, queued
+inputs with batching and withdrawal, and the steer/redirect/stop delivery
+distinction; one permission authority, skills, workflows, memory, per-session
+MCP persistence, and A2A serving become Host-owned; sessions derive by fork
+or deterministic recovery seed; and runtime read/write gaps close (Issues
+344-349). Every v0.7.96 stable contract is retained; cross-platform manual
+acceptance remains open.
+
+**v0.7.96 stable release:** The stable release of the v0.7.96 line,
+finalizing the fourteen release candidates: trusted text transactions and
+platform shell containment across Windows, Linux, and macOS; Windows daemon
+lifecycle arbitration with nonblocking uncertain Shell cleanup; turn-matched
+interrupted-Run recovery across Runs; provable tool-history pairing and
+compaction-copy tracing; macOS system Git preflight; provider authentication
+isolation; single-writer Runtime transcript ownership in Ink sessions; and
+Windows NUL-ACE startup recovery. CI runs inside the tag-triggered Release
+workflow. Every rc.14 contract is retained; open items remain tracked in
+`docs/KNOWN_ISSUES.md`.
+
+**v0.7.96-rc.14 release:** Fourteenth release candidate of the v0.7.96
+line. Interrupted-Run recovery reaches coding Runs and managed execution
+with a labelled, bounded, transient record of journaled progress matched
+per turn; tool-history pairing spans the whole assistant scope;
+conversation resolution traces compaction copies to a provable root and
+truncates unproven boundaries as `partial`; Anthropic-compatible providers
+ignore an inherited `ANTHROPIC_AUTH_TOKEN`; the Ink host defers to the
+Runtime as the single transcript writer; and Windows interactive startup
+re-verifies the NUL account ACE behind a current setup marker after a
+reboot (Issues 340-341). CI now runs inside the tag-triggered Release
+workflow instead of on branch pushes. Every rc.13 contract is retained.
+
+**v0.7.96-rc.13 release:** Thirteenth release candidate of the v0.7.96
+line. Runtime-owned managed runs persist generated assistant messages and
+tool results at Runner commit boundaries, before tools or subsequent
+provider calls can hang: the current compacted transcript and queued-input
+identities survive an interrupted run, initial input replay is skipped
+rather than re-saving all history, and host-owned persistence timing is
+unchanged. Every rc.12 contract is retained.
+
+**v0.7.96-rc.12 release:** Twelfth release candidate of the v0.7.96 line.
+Uncertain Shell cleanup no longer blocks conversations: exhausted cleanup
+retries return diagnostics and partial output to the model, unresolved
+process identities become deferred cleanup records, successors and close
+proceed, and an exhausted terminal Run settles honestly with
+`effectOutcome: unknown` instead of claiming verified termination. Root
+Runner iteration progress is exposed in Runtime live snapshots and durable
+Actor turns, and exhausted native Actor children settle as failed with
+`terminationReason: iteration_limit` while preserving partial output,
+artifacts, and structured results. The test toolchain upgrades to Vitest
+4.1.11 with fflate 0.8.3 (ZIP64 scan fix). Every rc.11 contract is retained.
+
+**v0.7.96-rc.11 release:** Eleventh release candidate of the v0.7.96 line.
+SDK-owned background Git calls on macOS preflight the system Git shim: a
+shared `DEVELOPER_DIR`-aware platform guard (`@kodax-ai/agent/runtime/macos-git`)
+detects the known developer-tools-missing condition (exit code 2 only,
+TTL-cached probes shared across concurrent callers, recoverable after
+installation, no permanent disable state) so repo-intelligence, worktree,
+changed-diff, managed-task checkpoint, agent-adapter, worktree-sweep,
+session-snapshot, REPL helpers, and synchronous memory paths no longer
+repeat Apple's developer-tools installation prompt. Ordinary Git on `PATH`,
+independent Git, and arbitrary Bash/PTY commands are unchanged (Issue 339).
+Every rc.10 contract is retained.
+
+**v0.7.96-rc.10 release:** Tenth release candidate of the v0.7.96 line.
+Runtime shutdown owns and drains the background work it starts: managed
+terminal maintenance and memory setup/finalization IO plus background review
+drains are registered with the owning Runtime, close refuses new work and
+awaits already-started work before releasing resources, and managed execution
+finishes its durable memory finalization before publishing completion.
+Edits-mode `edit`/`write` no longer reject ordinary project files when a
+workspace root contains protected native state: trusted text transaction
+cache protection targets only the authorized canonical file while
+development artifact trust still checks every authorized write root. Every
+rc.9 contract is retained.
+
 **v0.7.96-rc.9 release:** Ninth release candidate of the v0.7.96 line.
 Arbitrates daemon publication against launcher loss with a one-shot startup
 handoff: unpublished Windows daemon startup trees and their Job descendants
@@ -1218,10 +1279,10 @@ effective draft after streaming and reconnect while raw journals retain the
 complete audit trail. They must not replay provider recovery checkpoints or
 deduplicate text heuristically.
 
-For the full host-integration contract, including inline/Worker/daemon selection,
+For the full host-integration contract, including Product Client and explicit inline/daemon ownership,
 multi-client permission handling, config/catalog/MCP admin APIs, artifacts,
 context diagnostics, and daemon protocol schemas, see
-[public_docs/sdk/embedder-guide.md §17](public_docs/sdk/embedder-guide.md#17-runtime-sdk-worker-isolation-and-local-daemon-feature_253-feature_257).
+[public_docs/sdk/embedder-guide.md §17](public_docs/sdk/embedder-guide.md#17-runtime-sdk-and-local-daemon-feature_253-feature_257).
 
 The Space/IDE shared-daemon contract is documented in
 [SDK Embedder Guide section 23](public_docs/sdk/embedder-guide.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769).
@@ -1252,7 +1313,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## Architecture
 
-KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 12 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
+KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; the current source packages them as a single bundled npm package `@kodax-ai/kodax` with 13 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/client`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
 
 ```
 KodaX/
@@ -1327,9 +1388,9 @@ Source-side workspace package names (`@kodax-ai/*`). npm consumers install the s
 KodaX has two layers that consumers should understand separately:
 
 - **Source-side**: 4 workspace packages above (what developers see when reading the repo).
-- **npm-published**: a single bundled package `@kodax-ai/kodax` with 12 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
+- **Current packaged exports** (not a claim of npm availability): a single bundled package `@kodax-ai/kodax` with 13 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
   - **Full-package subpaths** (`/agent`, `/llm`, `/coding`, `/repl`) — each one maps 1:1 to a source workspace and exposes its complete public API.
-  - **Integration and narrow subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`) — focused host surfaces. `/a2a` composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to `/agent`.
+  - **Integration and narrow subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/client`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`) — focused host surfaces. `/a2a` composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to `/agent`.
 
 | Source package | npm subpath | Type | What you get | Example consumer |
 |---|---|---|---|---|
@@ -1342,7 +1403,8 @@ KodaX has two layers that consumers should understand separately:
 | `packages/coding` | `@kodax-ai/kodax/coding`  | Full package | Coding agent + 50+ tools + repo-intelligence (505 exports) | Build a Claude Code-shape product |
 | `packages/repl`   | `@kodax-ai/kodax/repl`    | Full package | Ink TUI + permission modes + commands (217 exports) | Terminal-UI consumers |
 | `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... (17 exports) | IDE plugins and desktop hosts reading session history |
-| `src`             | `@kodax-ai/kodax/runtime` | Host API | Embedded/Worker/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports) | SDK hosts, Space/IDE clients, daemon clients |
+| `src`             | `@kodax-ai/kodax/client` | Product API | Shared Host connection and `KodaXProductClient` contract | TUI, desktop/IDE and automation applications |
+| `src`             | `@kodax-ai/kodax/runtime` | Host API | Explicit inline/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports) | Trusted Host integration |
 | `src`             | `@kodax-ai/kodax/sandbox` | Host API | Explicit ASRT capability/doctor/setup and host-owned contained command execution; unavailability never means silent ordinary execution | SDK hosts that need standalone process containment |
 | `src`             | `@kodax-ai/kodax/a2a` | Integration edge | A2A 1.0 Agent Card discovery, JSON-RPC/SSE F258 executor, safe fetch policy, and authenticated Runtime-backed Agent server | Agent orchestrators and KodaX hosts |
 
@@ -1465,10 +1527,11 @@ later re-enable. Private-address access and non-loopback plaintext HTTP are
 independent, persisted, default-deny permissions (`--allow-private` and
 `--allow-insecure-http`); exact loopback HTTP remains available without either.
 OAuth token endpoints retain their stricter HTTPS-or-exact-loopback rule.
-Worker-hosted SDK Runtimes can load this same configured plane inside the Worker
-owner with `worker: { configuredA2A: true }`. The CLI honors the same opt-in
-from `~/.kodax/config.json` (`"worker": { "configuredA2A": true }`) by creating
-a Worker-hosted embedded Runtime that loads the configured A2A plane. `a2a serve` loads
+SDK hosts load this same configured plane by wiring
+`createConfiguredA2ARuntimeIntegration({ configHome })` and passing its
+`runtimeOptions` as `externalAgents` — the CLI does this for its embedded
+sessions and the daemon Host it launches, and the `worker.configuredA2A` opt-in
+was removed with the Worker facade in v0.7.97. `a2a serve` loads
 its configured MCP/Extension capability surface before listening and pins that
 execution authority; it hot-reloads publication, authentication, and limits.
 
@@ -1556,7 +1619,6 @@ dist/binary/linux-x64/
 ├── builtin/                       # Sidecar built-in skills
 ├── provider-capabilities.json
 ├── semantic-worker.js             # Repo-intelligence Worker
-├── runtime-worker.js              # SDK Runtime Worker
 └── constructed-handler-worker.js  # Constructed-tool Worker
 ```
 
@@ -1568,6 +1630,10 @@ See [docs/release.md](docs/release.md) for full details on build flags, archive
 
 ### As Library
 
+For shared-Session applications, use the [Product Client integration](public_docs/sdk/embedder-guide.md#product-client-integration)
+and [migration guide](docs/SDK_MIGRATION.md). The example below is independent
+in-process coding library usage; it is not the product UI contract.
+
 ```bash
 npm install @kodax-ai/kodax
 ```
@@ -1595,6 +1661,7 @@ For smaller surface and tree-shake-friendly imports, the SDK is also exposed via
 
 ```typescript
 import { Runner } from '@kodax-ai/kodax/agent';                // agent runtime
+import { ensureKodaXClient } from '@kodax-ai/kodax/client';     // shared product Client
 import { getProvider } from '@kodax-ai/kodax/llm';              // LLM abstraction (16 aliases)
 import { runKodaX } from '@kodax-ai/kodax/coding';              // coding tools + prompts
 import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input artifacts
@@ -1608,9 +1675,9 @@ import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 client
 import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in memory SDK
 ```
 
-All 13 SDK entries (root + 12 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+All 14 SDK entries (root + 13 subpaths, including `/client`) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
 
-For the complete host-facing contract — including embedded/Worker/daemon ownership,
+For the product contract and separate low-level inline/daemon ownership,
 external-agent registration and task control, session cursor pagination, workflow
 model-tier routing, and efficiency telemetry — see the
 [SDK Embedder Integration Guide](public_docs/sdk/embedder-guide.md).
@@ -1859,6 +1926,10 @@ stays silent.
 
 ## Advanced Library Usage
 
+These examples describe independent coding-library ownership. Shared product
+clients use `/client`; see the [migration guide](docs/SDK_MIGRATION.md) before
+adapting these callbacks or storage examples into a UI.
+
 #### Simple Mode (runKodaX)
 
 ```typescript
@@ -1942,7 +2013,11 @@ await runKodaX({
 
 ## SDK Usage
 
-KodaX ships as a single npm package `@kodax-ai/kodax` with 12 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime` + v0.7.68 `/experimental-memory` + v0.7.69 `/a2a` + v0.7.78 `/sandbox`). Each subpath is tree-shake-friendly so consumers pull only what they need:
+This development tree exposes 13 SDK subpaths plus the root. Shared product
+applications use `@kodax-ai/kodax/client`; independent libraries and trusted Host
+APIs remain available through the other subpaths. See the [Client contract](docs/CLIENT_CONTRACT.md)
+and [SDK migration guide](docs/SDK_MIGRATION.md). The package version is still
+`0.7.96-rc.11`; npm publication is separate from the `v0.7.97` design target.
 
 ```bash
 npm install @kodax-ai/kodax
@@ -1950,6 +2025,7 @@ npm install @kodax-ai/kodax
 
 ```typescript
 import { runKodaX } from '@kodax-ai/kodax';                       // root: CLI helpers + runKodaX
+import { ensureKodaXClient, connectKodaXClient } from '@kodax-ai/kodax/client'; // shared product contract
 import { Runner, runFanOut } from '@kodax-ai/kodax/agent';        // generic Agent framework
 import { getProvider } from '@kodax-ai/kodax/llm';                // 16-alias LLM abstraction
 import { KODAX_TOOLS } from '@kodax-ai/kodax/coding';             // tools + prompts + agent loop
@@ -2119,7 +2195,8 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 | Building custom agent | `@kodax-ai/kodax/agent` | Runner + fan-out + idle-yield + session-lineage + capabilities |
 | Coding tasks | `@kodax-ai/kodax/coding` | Complete coding agent + tools |
 | Terminal app | `@kodax-ai/kodax/repl` | Full interactive experience |
-| Runtime host / daemon client | `@kodax-ai/kodax/runtime` | Sessions, runs, events, permissions, catalog, MCP, artifacts, diagnostics |
+| Shared Session application | `@kodax-ai/kodax/client` | Unified product intent, observation, interactions and history |
+| Trusted Runtime host | `@kodax-ai/kodax/runtime` | Explicit embedding, credentials/Host Tools and diagnostics |
 | Experimental governed memory | `@kodax-ai/kodax/experimental-memory` | Governed `MemoryAgent` list/remember/forget and scoped `MemorySession` recall/outcome contracts |
 
 ---