@kodax-ai/kodax 0.7.83 → 0.7.85

package/CHANGELOG.md

@@ -10,6 +10,156 @@ No changes yet.
 
 ---
 
+## [0.7.85] - 2026-08-11
+
+> Git tag and GitHub Release are created by the release workflow. npm
+> publication remains a separate manual operator step.
+
+### Changed
+
+- Runtime event ordering is now Session-scoped. Every event carries a
+  `{ sessionId, journalEpoch, seq }` cursor; public subscribe/replay calls must
+  specify `sessionId` or `runId`, and replay resumes from `after` rather than a
+  Runtime-global numeric sequence. Independent Sessions no longer contend on
+  one `event-sequence.lock`.
+- A2A assigns one Runtime Session to each A2A Task and persists that Session
+  cursor in a small progress checkpoint for recovery, avoiding a full
+  `tasks.json` rewrite per micro-event. Only semantic task-state transitions
+  are projected to the A2A stream; token/tool progress remains Runtime telemetry.
+- Daemon clients require the `sessionEventJournal:1` capability. Legacy global
+  Runtime event logs remain on disk for audit but are not mixed into live
+  Session replay.
+- Session failure latches and retention watermarks are journal-scoped. Reusing
+  a deleted Session ID rotates the epoch, ambiguous Windows path components remain
+  distinct, malformed cursors and mismatched Session/Run scopes fail closed,
+  legacy watermarks without an epoch cannot poison new replay, and a durable
+  per-Run journal index keeps fully trimmed child journals attributable if a
+  watermark is later corrupted. Missing or corrupt index evidence fails closed
+  instead of treating an ambiguous trimmed journal as unrelated.
+
+### Fixed
+
+- Memory/Learning command output is now rendered through the Ink-captured
+  command channel instead of raw stdout. `/learn` reports an explicit empty
+  state, `/learn ready` is the canonical ready-capability query, and the legacy
+  `/learn pending` alias explains that it is unrelated to episode-review work.
+  Memory management is now conversation-first: explicit remember, correction,
+  forget, recall, and exceptional-decision requests use one governed hidden tool.
+  Safe explicit mutations apply immediately; stable semantic claim keys make
+  later contradictions address the same fact/preference/policy/procedure slot.
+  A host-owned handled-operation marker prevents the instruction from being duplicated
+  into the outcome review, while the rest of the episode still participates in
+  autonomous Memory/Skill learning. Ambiguity and broad input request
+  clarification, conflicts become readable decisions, secrets are rejected,
+  and inferred changes stay governed. `/memory` remains a compact advanced escape hatch for accepted
+  Memory, decisions, diagnostics, and external-editor opening. Raw review/status
+  and derived-index rebuild commands remain hidden diagnostics; `MEMORY.md` is a
+  projection rather than the source of truth. The
+  `@kodax-ai/kodax/experimental-memory` factory now returns an additive
+  `MemoryManagementAgent` only for a management-capable controller, exposing
+  list, remember, and forget without widening the existing
+  `MemoryAgent`/`MemoryController` structural contracts. Natural-language
+  decision handles carry their preview revision across turns and fail closed if stale.
+- Unified Memory review accepts a minimal model-owned action/warning plan and
+  binds trigger, timestamps, source/candidate references, and digest authority
+  on the host. This removes redundant schema work that caused GLM providers to
+  return invalid plans without weakening deterministic action validation.
+- Issue 282 follow-up: Actor progress is now batched once per controller tree,
+  terminal persistence excludes known mutation-queue waits from its five-second
+  ambiguity budget, and a permanently blocked predecessor remains bounded by a
+  separate queue-wait fence. Progress promises also reject when an ownership
+  conflict self-fences their controller instead of remaining pending forever.
+- A durability-unknown Actor tree now fail-closes its owning root executor and
+  automatically reconciles only an exact same-owner late snapshot. Runs settle
+  as `actor_settlement_not_persisted` unless a stronger executor Promise fact
+  was captured before the fence. Same-owner durable repair plus root abort and
+  post-fence admission suppression closes the Session route after every exact
+  tool execution admitted before the fence has settled. It does not wait for
+  an abort-ignoring provider Promise; callbacks and new Runtime-mediated effects
+  from the fenced root remain blocked.
+- Healthy `after_turn` input keeps the established coding-mode default. It
+  inherits a managed predecessor's mode only when it actually drains behind an
+  Actor durability repair.
+- Self-fenced Actor admission now reports the causal settlement-persistence
+  error instead of the misleading `actor_owner_conflict`. Genuine foreign-owner
+  conflicts remain fail-closed.
+- Runtime capability negotiation now exposes `actorSettlementConvergence:1`,
+  including automatic repair and safe after-turn queueing behind an unknown Run.
+- Issue 286: Learned Skill discovery now traverses the distinct remote and local
+  hashed project roots and routes every canary mutation to the record's owning
+  store. `remote-hash:*` receives the same local fallback, while the public
+  deprecated `expectedScope` configuration remains source/runtime compatible
+  with the optional multi-scope form.
+- Issue 285: Rules-mode agent-home access now protects the home root from whole-
+  tree removal, hard-denies Runtime mutations, and reviews credential/security
+  config plus generic sensitive filenames.
+  The legacy `processes/children` registry is now treated as host control state:
+  model writes are hard-denied, and upgrade cleanup quarantines unauthenticated
+  historical records without using them to signal a process.
+  Learned Area persistence is also host-owned and no longer directly writable
+  by model file or shell tools.
+  Ordinary descendants—including `agents/*.md`, Sessions, tool results, and
+  intermediate artifacts—remain readable and writable without approval.
+- Issue 285 execution-time file sinks now recheck the hard boundary after
+  queueing. Undo backups are context-scoped and identity-fenced, while workflow
+  worktree roots are accepted only through the trusted controller context.
+  Agent Home root and Runtime shell mutations use a non-authorizable gate in
+  both Auto[LLM] and Auto[Rules]; sensitive configuration remains reviewable.
+  A cross-process category lease prevents model-started shell effects from
+  racing a privileged file sink's canonical check and write without serializing
+  independent shell calls or independent direct-file mutations.
+- Every coding run now carries a non-removable Agent Home shell boundary.
+  Opaque Bash requires a fail-closed OS sandbox with authoritative process-tree
+  containment; unsandboxed or filesystem-only standalone callers
+  may run only completely modeled exact commands. Runtime supplies that sandbox
+  in every permission mode and fails closed when preparation is unavailable.
+  Linux uses the built-in ASRT PID namespace and Windows adds a per-effect Job;
+  macOS and legacy custom adapters without the optional containment capability
+  retain exact modeled commands but fail closed for opaque Bash.
+  Protected Agent Home reads still require review, but are not permanently
+  denied by the OS sandbox after an explicit approval.
+  On Windows, ACL grants target verified ordinary Agent Home children rather
+  than the Home object itself, so `agents`, Sessions, and intermediate results
+  remain writable without granting permission to delete the whole Home root.
+- Session event replay now rejects cursors ahead of the current journal instead
+  of silently returning no events. Limited replay retains the latest-event
+  behavior without a cursor and returns the earliest forward page when `after`
+  is supplied; replay limits must be positive safe integers. Corrupt aggregate
+  journal/status metadata is reported without widening the failure to unrelated
+  Sessions, valid retired journals are not misreported as corrupt, and A2A
+  regression coverage pins legacy numeric event positions as non-cursors.
+
+---
+
+## [0.7.84] - 2026-08-07
+
+> Git tag and GitHub Release are created by the release workflow. npm
+> publication remains a separate manual operator step.
+
+### Fixed
+
+- Issue 282: Agent progress persistence is now backpressured and coalesced to
+  one in-flight write plus one latest replacement. Terminal settlement no
+  longer waits behind an unbounded progress backlog and exposes an explicit
+  durability-unknown state when the remaining write cannot settle in time.
+- A same-owner Stop can reconcile a late Actor snapshot after settlement
+  timeout, durably quiesce remaining children, and retry the repair on a later
+  Stop. Foreign owners, missing snapshots, and persistent storage failures
+  remain fail-closed.
+- Promise success/failure facts are retained while Actor durability is unknown
+  and outrank fallback terminal callbacks after repair. A stale durable unknown
+  status cannot rewind an already terminal local Run, duplicate cancellation
+  effects, or emit conflicting terminal events.
+- A quiesce with no eligible turn is now a true no-op and avoids an unnecessary
+  Session snapshot rewrite.
+
+### Documentation
+
+- Updated the release baseline, SDK embedder guidance, `kodax_manual`, feature
+  design index, regression guides, and known-issue disposition for Issue 282.
+
+---
+
 ## [0.7.83] - 2026-08-06
 
 > Git tag and GitHub Release are created by the release workflow. npm
@@ -1993,7 +2143,7 @@ No changes yet.
 
 - **`code_search` / `semantic_lookup` teaching in the Worker REPO INTELLIGENCE prompt (FEATURE_250).** A two-line, eval-justified teaching block: the floor-tier alias under-adopted the hint-only tools on ambiguous tasks (75%), and the teaching recovered adoption to 100% while being strictly non-negative on every other alias.
 - **CAP-099 live turn attribution — session/turn identity on streamed events (Space SDK).** A shared live-turn scope (`createLiveTurnScope` / `withLiveTurnAttribution`, `event-emitter.ts`) stamps `KodaXActivityEventMeta` (`sessionId` / `seq` / `turnId` / `deliveryId` / `timestamp`) onto every streamed activity callback, and explicit turn-boundary events (`emitTurnStarted` / `emitTurnCompleted` / `emitTurnFailed`) share one monotonic per-session sequence — so an SDK host can route streamed assistant events to the owning turn's UI bubble by turn ownership instead of fragile ordering-by-observation. Threaded through messaging (queue/drain), orchestration (idle-yield), run-substrate, runner-driven, run-workflow, and dispatch-child-tasks; a host that ignores the metadata sees unchanged behavior. New `cap-099-live-turn-attribution` contract test; existing `cap-005/006/007/041/046/054/086` event-contract tests updated for the added meta parameter.
-- **Client-only transcript notices + structured transcript entries (CAP-099, Space SDK).** The persisted transcript gains structured entry types (`message` / `compaction` / `branch_summary` / `client_notice` / `task_result`) with `source` + `turnId`. A `client_notice` is persisted as a lineage entry, NOT a model message: `loadSession()` (active model context) omits it while `loadFullTranscript()` returns it with `type: 'client_notice'`, `source: 'client'`, and `payload.entersModelContext === false` — so a host can render client-side scrollback notices without polluting the model's context. SDK embedder guide updated (`docs/SDK_EMBEDDER_GUIDE.md`).
+- **Client-only transcript notices + structured transcript entries (CAP-099, Space SDK).** The persisted transcript gains structured entry types (`message` / `compaction` / `branch_summary` / `client_notice` / `task_result`) with `source` + `turnId`. A `client_notice` is persisted as a lineage entry, NOT a model message: `loadSession()` (active model context) omits it while `loadFullTranscript()` returns it with `type: 'client_notice'`, `source: 'client'`, and `payload.entersModelContext === false` — so a host can render client-side scrollback notices without polluting the model's context. SDK embedder guide updated (`public_docs/sdk/embedder-guide.md`).
 - **Transcript clone provenance for SDK hosts (CAP-099, Space SDK).** Lineage entries now carry optional `logicalId` / `sourceEntryId`, and `loadFullTranscript().transcriptEntries[]` always exposes a stable `logicalId` (falling back to `entryId` for old sessions). Forked/cloned entries keep the source `logicalId` and point `sourceEntryId` at the root physical source entry, so hosts can fold cloned history precisely without guessing from role/content/timestamp or `[compacted]` placeholders. `loadFullTranscript()` remains raw append-order scrollback; it does not silently merge branches or hide compaction notices.
 
 ### Changed
@@ -2340,7 +2490,7 @@ No changes yet.
 ### Added
 
 - **FEATURE_132 — Native LSP integration: edit-time diagnostics reflux (TS/JS, Python, Go, Rust, Java).** After the `write` / `edit` / `multi_edit` tools change a file, KodaX now opens it through a language server and refluxes any type ERRORs straight back into the tool result, so the agent fixes them the same turn instead of waiting for the next build (saving ≥1 LLM round-trip). Servers are discovered on `PATH` / project `node_modules` (typescript-language-server, pyright, gopls, rust-analyzer, jdtls); when none is installed the feature is **silent** (no nagging), and a one-shot blacklist + spawn-dedup keep it cheap. It is **default-on but self-limiting**: only ERROR severity, ≤20 per file, a 5s per-file wait that runs OUTSIDE the file-mutation lock, and `KODAX_LSP=0` disables it entirely. Auto-installing a missing server is **opt-in** (`KODAX_LSP_DOWNLOAD=1`; `KODAX_LSP_NO_DOWNLOAD=1` hard-off) — KodaX never runs `go install` / `npm i` unprompted. The LSP TypeScript server runs as its own subprocess, isolated from the in-process repo-intelligence TS engine. It also adds four read-only navigation tools — `lsp_definition` / `lsp_hover` / `lsp_references` / `lsp_document_symbols` — for precise, position-anchored, real-time questions about the current code (complementing the repo-scope repo-intelligence symbol tools; the tool descriptions teach the boundary). Implemented under `packages/coding/src/lsp/`; new exports from `@kodax-ai/coding`: `LspService`, `getDefaultLspService`, `shutdownDefaultLspService`, `languageIdForPath`. See [docs/features/v0.7.47.md FEATURE_132](docs/features/v0.7.47.md).
-- **FEATURE_221 — Injectable self-manual for SDK consumers (`selfManual`).** Products built on the KodaX SDK (e.g. KodaX-Space) can now inject their **own** product manual so the built-in `kodax_manual` tool answers *their* users' "how do I use / configure …?" questions on-brand, instead of returning KodaX's internal manual. `runKodaX({ selfManual: { productName, topics } })` re-brands the ≤250-token routing rule + scope anchors to `productName` and **extend-merges** your `KodaXManualTopicInput[]` over KodaX's base topics (same `id` overrides, new `id` appends), so users can still ask about the underlying provider / config / SDK topics. **Opt-in and backward-compatible** — omit `selfManual` and the system prompt is byte-identical to before. Topics stay **tool-on-demand and 4 KB-capped**: nothing large is injected into the prompt, only the short routing rule. New exports from `@kodax-ai/coding`: `KodaXManualTopicInput`, `KodaXSelfManualConfig`, `ResolveKodaXManualOptions`, `buildSelfKnowledgeRoutingRule`. See [SDK Embedder Guide §13](docs/SDK_EMBEDDER_GUIDE.md#13-inject-your-products-manual--selfmanual-feature_221-v0747) + [docs/features/v0.7.47.md FEATURE_221](docs/features/v0.7.47.md).
+- **FEATURE_221 — Injectable self-manual for SDK consumers (`selfManual`).** Products built on the KodaX SDK (e.g. KodaX-Space) can now inject their **own** product manual so the built-in `kodax_manual` tool answers *their* users' "how do I use / configure …?" questions on-brand, instead of returning KodaX's internal manual. `runKodaX({ selfManual: { productName, topics } })` re-brands the ≤250-token routing rule + scope anchors to `productName` and **extend-merges** your `KodaXManualTopicInput[]` over KodaX's base topics (same `id` overrides, new `id` appends), so users can still ask about the underlying provider / config / SDK topics. **Opt-in and backward-compatible** — omit `selfManual` and the system prompt is byte-identical to before. Topics stay **tool-on-demand and 4 KB-capped**: nothing large is injected into the prompt, only the short routing rule. New exports from `@kodax-ai/coding`: `KodaXManualTopicInput`, `KodaXSelfManualConfig`, `ResolveKodaXManualOptions`, `buildSelfKnowledgeRoutingRule`. See [SDK Embedder Guide §13](public_docs/sdk/embedder-guide.md#13-inject-your-products-manual--selfmanual-feature_221-v0747) + [docs/features/v0.7.47.md FEATURE_221](docs/features/v0.7.47.md).
 - **FEATURE_218 — KodaX self-knowledge manual + `kodax_manual` help tool.** KodaX now ships a version-bound, structured product manual (17 topics: overview / install / providers / custom-providers / config / permissions / commands / tools / agents / skills / mcp / repo-intelligence / sessions / doctor / sdk / troubleshooting) behind a read-only `kodax_manual` tool, plus a ≤250-token routing rule that tells the model to look up KodaX usage/config questions instead of guessing or mixing in Claude Code / Codex CLI knowledge. The provider list is sourced from the single-source-of-truth capability snapshots (drift-proof, not hand-copied) and each answer is anchored to KodaX scope. REPL `/help <topic>` reuses the same registry. Lookup is deterministic (exact id → alias, incl. Chinese → query token-overlap → index) and never fabricates; single-topic output ≤4 KB, index ≤2 KB. No RAG, no vector DB, no background index, no prompt bloat. See [docs/features/v0.7.47.md FEATURE_218](docs/features/v0.7.47.md).
 - **MCP client — protocol `2025-11-25` compatibility (P0+P1).** KodaX's self-built MCP client now speaks the `2025-11-25` revision. **P0 (protocol compliance):** answers a server `ping` with an empty result instead of `-32601`; emits `notifications/cancelled` when a request times out (the `initialize` request is exempt); and resumes a dropped Streamable-HTTP notification stream via SSE `id`/`retry` + `Last-Event-ID`, with a reconnect cap so an empty-EOF stream can't reconnect-loop forever. **P1 (version + data surface):** advertises protocol `2025-11-25` with negotiation validation + the `MCP-Protocol-Version` header; carries tool/resource/prompt `icons` into descriptors (filtering unsafe URI schemes); and surfaces `execution.taskSupport`, failing fast on task-required tools. Unwired `elicitation` dead code removed. (Reverse / server-side capabilities are planned as FEATURE_222 for v0.7.48.)
 
@@ -2419,7 +2569,7 @@ shared names — the new name is required for the coding-plan provider to start.
   - **P2 — explicit per-dispatch override.** `dispatch_child_task` gains optional `provider` / `model` params, so the agent can deliberately send a child to another model family — e.g. a second independent review of the same change by a different family, to catch blind spots a single family would share. Resolution priority in `child-executor`: `bundle.provider/model` > specialist's declared model (FEATURE_191) > parent default. Omitting both is byte-identical to the prior behavior. Tolerant parse (empty/whitespace → undefined) so a misuse never fails the dispatch.
   - **P3 — cross-provider fallback + `doctor --ping`.** When a child's primary provider is *exhausted or down* (the LLM layer's same-provider `withRateLimit` retries gave up, a 5xx, or a network error), KodaX re-runs the child once on the next provider in an operator-configured chain instead of failing the whole child. Configured via `/fallback ark-coding,kimi-code` (persists to `~/.kodax/config.json` + mirrors to `KODAX_FALLBACK_PROVIDERS`; `/fallback off` to clear, `/fallback status` to inspect). Empty chain = OFF. Scope is deliberately minimal (per user direction): only hard availability errors trigger fallback — a returned `success:false` is a task outcome (not retried elsewhere) and aborts are never faked over; the speculative tool-call-fidelity / context-overflow / quality-anomaly triggers are unbuilt (YAGNI). `kodax doctor --ping` completes the health check: it sends one minimal request per configured provider (10s timeout, concurrent) to prove the key actually works and the subscription is active — opt-in, small token cost, never on the default `doctor`. 16 tests (11 fallback core + 5 `/fallback` command).
   - **P1-auto — `model_hint` → tier routing.** The previously dormant `model_hint` field (`fast`/`balanced`/`deep`, FEATURE_120) now selects an operator-configured tier: `fast` → `KODAX_FAST_PROVIDER`/`KODAX_FAST_MODEL` (**read-only children only** — the gating eval validated cheap-model quality on read-only investigation but not write/codegen, so write children stay on the parent tier), `deep` → `KODAX_DEEP_PROVIDER`/`KODAX_DEEP_MODEL` (read or write). `balanced`/unset, or any unconfigured tier, falls back to the parent — **routing is OFF by default** and turns on only when you point a tier env var at a model (no separate toggle). Specialist and explicit-P2 overrides both win over the hint. Per KodaX minimalism the original 5-name capability-alias layer (`vision`/`long-context`/…) was descoped to this env-tier form — no consumer exists for the rest yet (YAGNI). Pure routing wiring; the Worker prompt is unchanged (an eval non-trigger per `CLAUDE.md`), so $0 / no panel. Gating eval (`tests/feature-102-model-tier-quality.eval.ts`, canonical 5-alias × 3 read-only investigation × 5 run) kept as permanent regression: cheap floor `ark/v4flash` = 15/15, ≥ strong-mean 92% → cheap PRESERVES read-only quality. New unit + integration tests (7 `model-hint-routing` + 5 child-executor P2/P1-auto priority); also de-flaked the pre-existing `merges findings` child-executor test (parallel children made `mergeChildResults` emit in completion order — now deterministic dispatch order). Design: [docs/features/v0.7.45.md](docs/features/v0.7.45.md#phase-1--model_hint--真实跨-provider-子派发mvp).
-- **FEATURE_216 — `verifyProviderCredential(name)` SDK API + per-provider strategy.** New top-level helper for SDK consumers (KodaX Space, third-party embedders) to validate a provider's API key against the actual upstream — never-throws, mostly zero-token. Closes the "test connection" UI gap: existing `isConfigured()` only checks env presence; `stream()`/`sideQuery()` are too heavy. Three primitives, one per provider, baked into `provider-capabilities.json` `verifyStrategy` field: **`count-tokens`** (Anthropic `messages.countTokens()`, 0 token) for `anthropic` + 4 anthropic-coding providers; **`models-list`** (`models.list()`, 0 token) for `openai`/`deepseek`/`kimi`/`qwen`; **`minimal-message`** (~6-7 token `chat.completions.create({max_tokens:1})`) for `zhipu`/`mimo`/`mimo-coding` (where `models.list()` is publicly-served or `count_tokens` returns 404). CLI-bridge providers (`gemini-cli`, `codex-cli`) return `unsupported` — their credentials live in the CLI binary's token store, outside SDK reach. Top-level `verifyProviderCredential(name, opts?)` short-circuits unknown name / unsupported strategy / missing env var BEFORE instantiating the provider class — avoids the constructor throw on missing key, and ALSO wraps the actual `verifyCredential()` call in try/catch so the never-throws contract survives runtime-registered providers whose 3rd-party overrides might throw instead of returning an envelope. Error categorization (`unauthorized` / `network` / `timeout` / `unsupported` / `unconfigured` / `server_error` / `rate_limited` / `unknown`) is stable for UI consumers to map to user-facing states — `rate_limited` (429) is distinct from `unauthorized` so a transiently throttled key isn't misread as invalid. The error `message` field redacts `sk-...` key fragments before truncation so upstream error bodies that echo the submitted key don't leak the fragment into UI logs. The `kimi-code`-specific 400→`unauthorized` mapping is gated by `providerName` to avoid false-positives on other count-tokens providers that might 400 on a legitimate bad request (bad model id / schema mismatch). Network error detection extended to `ETIMEDOUT` + `ENETUNREACH` + `EHOSTUNREACH` + `ENETDOWN` beyond the original `ENOTFOUND`/`ECONNREFUSED`/`ECONNRESET`/`EAI_AGAIN`/`EPIPE` set. Companion `listProviderModels(name)` returns the static curated list (always `source: 'static'` in v0.7.45 — upstream `/v1/models` is noisy + inconsistent across providers per the 2026-05-28 12-provider probe matrix). Custom providers auto-inherit by `protocol`; explicit `verifyStrategy` overrides allowed. 88 tests total (28 orchestrator + 14 resolver + 38 schema + 10 real-key integration gated on `KODAX_INTEGRATION_TEST=1`). Reference industry validator: opencode's `setup-recording-env.ts` makes the same per-provider decision across 20+ providers — per-provider strategy IS industry standard, no universal 0-token primitive exists. Design + probe data: [docs/features/v0.7.45.md#feature_216](docs/features/v0.7.45.md#feature_216-provider-credential-verification-api). SDK usage guide: [docs/SDK_EMBEDDER_GUIDE.md §12](docs/SDK_EMBEDDER_GUIDE.md#12-provider-credential-verification--verifyprovidercredential-feature_216-v0745).
+- **FEATURE_216 — `verifyProviderCredential(name)` SDK API + per-provider strategy.** New top-level helper for SDK consumers (KodaX Space, third-party embedders) to validate a provider's API key against the actual upstream — never-throws, mostly zero-token. Closes the "test connection" UI gap: existing `isConfigured()` only checks env presence; `stream()`/`sideQuery()` are too heavy. Three primitives, one per provider, baked into `provider-capabilities.json` `verifyStrategy` field: **`count-tokens`** (Anthropic `messages.countTokens()`, 0 token) for `anthropic` + 4 anthropic-coding providers; **`models-list`** (`models.list()`, 0 token) for `openai`/`deepseek`/`kimi`/`qwen`; **`minimal-message`** (~6-7 token `chat.completions.create({max_tokens:1})`) for `zhipu`/`mimo`/`mimo-coding` (where `models.list()` is publicly-served or `count_tokens` returns 404). CLI-bridge providers (`gemini-cli`, `codex-cli`) return `unsupported` — their credentials live in the CLI binary's token store, outside SDK reach. Top-level `verifyProviderCredential(name, opts?)` short-circuits unknown name / unsupported strategy / missing env var BEFORE instantiating the provider class — avoids the constructor throw on missing key, and ALSO wraps the actual `verifyCredential()` call in try/catch so the never-throws contract survives runtime-registered providers whose 3rd-party overrides might throw instead of returning an envelope. Error categorization (`unauthorized` / `network` / `timeout` / `unsupported` / `unconfigured` / `server_error` / `rate_limited` / `unknown`) is stable for UI consumers to map to user-facing states — `rate_limited` (429) is distinct from `unauthorized` so a transiently throttled key isn't misread as invalid. The error `message` field redacts `sk-...` key fragments before truncation so upstream error bodies that echo the submitted key don't leak the fragment into UI logs. The `kimi-code`-specific 400→`unauthorized` mapping is gated by `providerName` to avoid false-positives on other count-tokens providers that might 400 on a legitimate bad request (bad model id / schema mismatch). Network error detection extended to `ETIMEDOUT` + `ENETUNREACH` + `EHOSTUNREACH` + `ENETDOWN` beyond the original `ENOTFOUND`/`ECONNREFUSED`/`ECONNRESET`/`EAI_AGAIN`/`EPIPE` set. Companion `listProviderModels(name)` returns the static curated list (always `source: 'static'` in v0.7.45 — upstream `/v1/models` is noisy + inconsistent across providers per the 2026-05-28 12-provider probe matrix). Custom providers auto-inherit by `protocol`; explicit `verifyStrategy` overrides allowed. 88 tests total (28 orchestrator + 14 resolver + 38 schema + 10 real-key integration gated on `KODAX_INTEGRATION_TEST=1`). Reference industry validator: opencode's `setup-recording-env.ts` makes the same per-provider decision across 20+ providers — per-provider strategy IS industry standard, no universal 0-token primitive exists. Design + probe data: [docs/features/v0.7.45.md#feature_216](docs/features/v0.7.45.md#feature_216-provider-credential-verification-api). SDK usage guide: [public_docs/sdk/embedder-guide.md §12](public_docs/sdk/embedder-guide.md#12-provider-credential-verification--verifyprovidercredential-feature_216-v0745).
 
 ### Performance
 
@@ -2491,7 +2641,7 @@ shared names — the new name is required for the coding-plan provider to start.
 
 ### Added
 
-- **FEATURE-SDK-MODEL-CAPS — Expose Per-Model Capabilities Without API Key** (2 commits `7f627d0c` feat + `c37b0a13` fix, shipped 2026-05-25). SDK consumers (KodaX Space etc.) need to list providers + their models with context-window / reasoning info in popout UIs — but the pre-v0.7.43 path forced instantiation of each `KodaXProvider` class, which throws on missing API key. Static metadata was hidden behind runtime credentials, an architectural mismatch — that data is KodaX-maintained, not negotiated with the upstream. **Fix** (2-part): (1) Promote capability metadata (`contextWindow` / `maxOutputTokens` / `thinkingBudgetCap` / `supportsThinking` / full `KodaXModelDescriptor[]`) from per-Provider `class.config` field initializers UP to the existing `KODAX_PROVIDER_SNAPSHOTS` constant — Provider classes now derive their runtime `config` from the snapshot via `buildProviderConfig` (single source of truth, no drift risk; net −160 lines duplication / +30 lines metadata / byte-equivalent runtime behavior). (2) Add 9 new SDK exports reading directly from the snapshot (zero API keys touched): built-in `getProviderModelDescriptors` / `getModelCapabilities` / `listBuiltinModelCapabilities`; custom (from `~/.kodax/config.json#customProviders`) `getCustomProviderModelDescriptors` / `getCustomModelCapabilities` / `listCustomProviderModelCapabilities`; unified dispatchers `resolveProviderModelDescriptors` / `resolveModelCapabilities` / `listAllModelCapabilities`. New public type `KodaXModelCapabilities` exposed from `@kodax-ai/kodax/llm`. **`maxOutputTokens` rationale** (fix commit `c37b0a13`): the field IS reliable — it's the KodaX-side per-turn `max_tokens` request decision (bench-validated against kill-windows / decode-rate / cost-per-turn), NOT the upstream "theoretical maximum" (which is often inflated or absent — zhipu-coding / kimi-code / minimax-coding / ark-coding / deepseek `/v1/models` returns `{id, object, owned_by, created}` only). Embedders showing "expected output size" should use this value; theoretical ceilings should be looked up from the upstream provider's own docs. **Maintainer-probe scripts shipped**: `scripts/probe-upstream-model-metadata.mjs` (re-run periodically to detect upstream API improvements) + `scripts/probe-ark-tokens.mjs` (Ark-specific drill-down). **Tests**: `packages/llm/src/providers/model-capabilities.test.ts` 20/20 ✓ (no-API-key verification clears 6 env vars during assertion; snapshot drift guard asserts every `supportsThinking` provider declares `contextWindow` + every `models[]` entry is a descriptor object); full llm suite 304/304 ✓. **Bundle impact**: `dist/sdk-llm.d.ts` +1.2 kB (new types + symbols); `dist/sdk-llm.js` +400 bytes. **Architectural debt followup**: `KODAX_PROVIDER_SNAPSHOTS` still TS const compiled into bundle; capability data update path still needs `npm publish` + consumer `npm update`. FEATURE_198 (filed for v0.7.44) splits the snapshot to JSON + runtime loader for dist-patch-time updates (hot-update over network deferred to v0.7.46+). Docs: [`SDK_EMBEDDER_GUIDE.md §9`](docs/SDK_EMBEDDER_GUIDE.md#9-querying-per-model-capabilities-without-api-keys).
+- **FEATURE-SDK-MODEL-CAPS — Expose Per-Model Capabilities Without API Key** (2 commits `7f627d0c` feat + `c37b0a13` fix, shipped 2026-05-25). SDK consumers (KodaX Space etc.) need to list providers + their models with context-window / reasoning info in popout UIs — but the pre-v0.7.43 path forced instantiation of each `KodaXProvider` class, which throws on missing API key. Static metadata was hidden behind runtime credentials, an architectural mismatch — that data is KodaX-maintained, not negotiated with the upstream. **Fix** (2-part): (1) Promote capability metadata (`contextWindow` / `maxOutputTokens` / `thinkingBudgetCap` / `supportsThinking` / full `KodaXModelDescriptor[]`) from per-Provider `class.config` field initializers UP to the existing `KODAX_PROVIDER_SNAPSHOTS` constant — Provider classes now derive their runtime `config` from the snapshot via `buildProviderConfig` (single source of truth, no drift risk; net −160 lines duplication / +30 lines metadata / byte-equivalent runtime behavior). (2) Add 9 new SDK exports reading directly from the snapshot (zero API keys touched): built-in `getProviderModelDescriptors` / `getModelCapabilities` / `listBuiltinModelCapabilities`; custom (from `~/.kodax/config.json#customProviders`) `getCustomProviderModelDescriptors` / `getCustomModelCapabilities` / `listCustomProviderModelCapabilities`; unified dispatchers `resolveProviderModelDescriptors` / `resolveModelCapabilities` / `listAllModelCapabilities`. New public type `KodaXModelCapabilities` exposed from `@kodax-ai/kodax/llm`. **`maxOutputTokens` rationale** (fix commit `c37b0a13`): the field IS reliable — it's the KodaX-side per-turn `max_tokens` request decision (bench-validated against kill-windows / decode-rate / cost-per-turn), NOT the upstream "theoretical maximum" (which is often inflated or absent — zhipu-coding / kimi-code / minimax-coding / ark-coding / deepseek `/v1/models` returns `{id, object, owned_by, created}` only). Embedders showing "expected output size" should use this value; theoretical ceilings should be looked up from the upstream provider's own docs. **Maintainer-probe scripts shipped**: `scripts/probe-upstream-model-metadata.mjs` (re-run periodically to detect upstream API improvements) + `scripts/probe-ark-tokens.mjs` (Ark-specific drill-down). **Tests**: `packages/llm/src/providers/model-capabilities.test.ts` 20/20 ✓ (no-API-key verification clears 6 env vars during assertion; snapshot drift guard asserts every `supportsThinking` provider declares `contextWindow` + every `models[]` entry is a descriptor object); full llm suite 304/304 ✓. **Bundle impact**: `dist/sdk-llm.d.ts` +1.2 kB (new types + symbols); `dist/sdk-llm.js` +400 bytes. **Architectural debt followup**: `KODAX_PROVIDER_SNAPSHOTS` still TS const compiled into bundle; capability data update path still needs `npm publish` + consumer `npm update`. FEATURE_198 (filed for v0.7.44) splits the snapshot to JSON + runtime loader for dist-patch-time updates (hot-update over network deferred to v0.7.46+). Docs: [`SDK_EMBEDDER_GUIDE.md §9`](public_docs/sdk/embedder-guide.md#9-querying-per-model-capabilities-without-api-keys).
 - **FEATURE_197 — Read-Only Markdown Agent Discovery: `discoverMarkdownAgents` SDK API (FEATURE_191 follow-up)** (1 commit, shipped 2026-05-24). KodaX Space (SDK 消费方) 2026-05-24 反馈：F191 `loadAgentsFromMarkdown` 触发 admission + 全局 registry 注册 side effect，他们想做 "agent picker" UI（用户 preview 已有 markdown agents 后再选择性激活），现有 loader 形态不匹配。`listConstructedAgentsWithSource()` 虽然技术上能 list 但是 `@internal` 标记的（[`agent-resolver.ts:159-164`](packages/coding/src/construction/agent-resolver.ts#L159-L164) 明确写 "NOT yet a stable SDK surface; embedders SHOULD continue using `listConstructedAgents()`"），不能给 SDK consumer 用。F035 `discoverSkills(root?, opts?)` 是 pure read-only 形态，F191 没有对应的 read-only counterpart 是 SDK surface 设计 gap。**Fix**：抽 `parseMarkdownAgentFile(filePath)` shared helper（loader 和 discover 共用 parser，loader 行为 byte-identical），新增 `discoverMarkdownAgents(opts): Promise<{agents: DiscoveredMarkdownAgent[], failed: MarkdownLoadFailure[]}>` 公开 API：扫描同 two-tier path (user → project) → 返回 metadata `{name, description, source: 'markdown:user' | 'markdown:project', path, tools?, model?}`，**零 admission / 零 registration / 零全局 registry mutation**。Last-write-wins 与 loader parity（project 同名 shadow user）。Tools 字段返回 raw 名字不带 `builtin:` 前缀（discovery 暴露用户写的形态，ref-prefix 逻辑移到 loader 内 inline `.map(ref:)` 应用）。**Validation 边界**：discover 不验 admission（unknown tool ref / handoff cycle 都 surface），admission 仍在 `loadAgentsFromMarkdown` 兜底 — 与 F035 discoverSkills 不验 skill admission 形态对齐。**测试**：13 既有 F191 loader test 全过（parser 抽取无行为变化）+ 15 新 F197 unit test 覆盖 empty/missing-frontmatter/missing-name/missing-description/empty-body/project-shadows-user/tools-array/tools-csv/model-passthrough/admission-not-validated/loader-roundtrip-parity；**Read-only 硬契约**断言（`listConstructedAgents().length` discover 前后不变 + `resolveConstructedAgent(name)` discover 后仍 `undefined`）锁定 "discover 不能误注册" 边界。**Round-trip parity**断言 `discover.agents.length === loader.loaded` + 失败路径 set 相等 + 名字 set 相等 — 同 parser 共用保证 SDK consumer 用 discover preview 决定的 set 与最终 loader 激活的 set 一致。**Public surface**：`discoverMarkdownAgents` + `DiscoveredMarkdownAgent` + `DiscoverMarkdownAgentsResult` 从 `@kodax-ai/coding` 一路 reexport 到 `@kodax-ai/kodax` + `@kodax-ai/kodax/coding` 子路径。**Eval $0** — pure file-system + YAML parse, no LLM-facing change. 28/28 tests pass, tsc clean. 详见 [v0.7.43.md §FEATURE_197](docs/features/v0.7.43.md#feature_197-read-only-markdown-agent-discovery--discovermarkdownagents-sdk-apif191-follow-up).
 - **FEATURE_195 — Sidecar Verifier UI Silent Accept: Default-Hide Accept Verdict Evidence Entry + Transcript-Mode Opt-In** (1 commit `1b53150e`, shipped 2026-05-24). User 2026-05-24 实战 session 截图（"你好 → 你好!" 对话）显示 sidecar verifier accept verdict 的 `reason` 文本以 `> [Evaluator] ...` event-item 渲染到 transcript，背离 FEATURE_184 (v0.7.42, ADR-030) "silent accept" 设计意图（accept verdict 应只走 session.jsonl + artifact，UI 端仅看 `[AMA Verifying]` spinner）。3-step pipeline 漏 silent 到 UI 层：(a) [`verifier-recorder-bridge.ts:89-104`](packages/coding/src/agent-runtime/middleware/sidecar-verifier/verifier-recorder-bridge.ts#L89) 历史 backward-compat 写 `role:'evaluator'` 入 recorder；(b) [`payload-builder.ts:249-298`](packages/coding/src/task-engine/_internal/managed-task/payload-builder.ts#L249) recorder 进 evidence.entries；(c) [`InkREPL.tsx:574-624`](packages/repl/src/ui/InkREPL.tsx#L574) `buildManagedTaskTranscriptItems` 无差别 render 全部 evidence.entries 为 event-item。**Fix**：单 commit REPL render filter — `shouldFilterSidecarAcceptEntry(entry, verifierLog)` helper + extend `buildManagedTaskTranscriptItems(result, options?: { verifierLog?: boolean })`；filter 规则 `role==='evaluator' AND signal==='COMPLETE' AND !verifierLog ⇒ filter`；revise/blocked verdict 因 signal 不是 `'COMPLETE'` 自然 fall-through。Default 读 `process.env.KODAX_VERIFIER_LOG === '1'` (复用 F184 Phase D.3 已有 env var)；config 入口同时支持 `verifierLog: true` in `~/.kodax/config.json`。**数据层 0 改动**：`recorder.verdict` 仍写 session.jsonl + artifact —— replay / debug / scorecard / `kodax sessions` resume 全完整。**测试**：8 新 unit test 覆盖 4 verdict state (accept-no-userAnswer / accept-with-userAnswer / revise / blocked) × 2 mode (default / verifierLog=true)。**Root cause refinement during impl**：立项 doc 假设 H0_DIRECT trivial-chat `decidedByAssignmentId='evaluator'`，实际生产 `payload-builder.ts:218-219` 三元 `harness === 'H0_DIRECT' ? 'direct' : verdictStatus ? 'evaluator' : 'worker'` 让 H0_DIRECT 是 `direct`（最高优先级）——所有 fixture 已对齐生产路径用 `direct`。**Eval $0**：无 LLM-facing prompt change；UI render filter 是 deterministic 行为，unit test 覆盖 sufficient。**Concurrent-thread safety**：0 文件 overlap with F194 (改 `packages/{mcp,skills,tracing,session-lineage}`)；atomic stage + commit + push 同 Bash 调用 per `feedback_concurrent_thread_git_race`。详见 [v0.7.43.md §FEATURE_195](docs/features/v0.7.43.md#feature_195-sidecar-verifier-ui-silent-accept--default-hide-accept-verdict-evidence-entry--transcript-mode-opt-in) + ADR-030 §F195/F196 cross-reference。
 - **FEATURE_196 — Sidecar Verifier Content-Aware Fire Gate: Action-Surface Detector + Conversational User-Intent Skip** (4 commits `10b8b290` → `c25ff99c` → `af7bc588` → this commit, shipped 2026-05-24). FEATURE_184 (v0.7.42, ADR-030) 在 Worker text-only termination 时无差别 fire sidecar verifier，包括 "你好" 这种零 action-surface trivial-chat 也跑 3-10s + LLM cost。F184 设计动机是抓 zhipu intent-vs-action floor（Worker 说 "明白，我用 todo_create..." 但没真调 tool），不是 trivial-chat 内容审查器；trivial chat 没有可 verify 的"声称完成"surface。F196 在 [`runner-driven.ts`](packages/coding/src/task-engine/runner-driven.ts) `composedStopHook` `!isIdleYieldTurn` 分支 `observer.sidecarStarted()` 之前加 deterministic 前置 gate `composeGateDecision(ctx, process.env)`，`fire===false` 直返 `extensionTurnCompleteHook(ctx)` 不进 sidecar；F184 fire 路径保持 byte-identical。**Gate 逻辑** (新模块 [`packages/coding/src/agent-runtime/middleware/sidecar-verifier/gate.ts`](packages/coding/src/agent-runtime/middleware/sidecar-verifier/gate.ts) ~213 LoC)：(1) Layer 1 `detectActionSurface` — 看 last assistant message 有无 `tool_use` content block，有则 fire (action-surface)；(2) Layer 2 `detectConversationalIntent` — greeting prefix regex (中英双语 + 通用 punctuation 👋 🙏) AND 长度 ≤ 20 codepoint AND 无 imperative verb (中文单字查/写/修/改/删/搜... + 中文多字 + 英文 imperative)，三合取真则 skip (conversational)；(3) escape hatch `KODAX_VERIFIER_ALWAYS=1` 强制 fire；(4) 默认 fire（保守失败 — F184 跑一遍 cost < 漏抓 zhipu floor）。`KODAX_VERIFIER_LOG=1` stderr `[sidecar-gate] {fire|skip}: <reason>` 复用 F195 env var。**测试**：23 unit (`gate.test.ts` — 6 actionSurface + 11 conversationalIntent + 6 composeGateDecision) + 3 integration (`runner-driven.test.ts` FEATURE_196 describe block — trivial-greeting skip / mutation-tool fire / imperative+zero-action fire) 全 pass。**Layer 2 eval — SHIP gate ALL EXCEEDED**（4 case × 5 canonical alias × 1 run = 60 panel cells + pilot 12 cells）：(a) C1 greeting skip 5/5 alias **100%** (≥95% 立项门槛) / (b) C2 imperative fire 5/5 alias **100%** (≥95%) / (c) C3 long-message fire 5/5 alias **100%** (=100%) / (d) C4 no-greeting fire 5/5 alias **100%** (=100%) / (e) 5/5 alias meet (a)+(b) → **SHIP**。Eval cost **~$2 actual vs $10-15 budget** (under-spend ~8×) — gate logic deterministic（`composeGateDecision` is pure function），Layer 1 unit tests authoritative；Layer 2 scope 收窄到 tuple realism only（"do real Worker LLM outputs across 5 provider families produce `KodaXContentBlock[]` shapes that `lastAssistantHasToolUse` detector handles?" + "do real model families respond to canonical user-message inputs with response patterns case categories assume?"）。**3-judge audit 跳过** per EVAL_GUIDELINES.md §Layer 1 justification：gate decision per cell 是 `actualDecision === c.expectedDecision` 严格等值，无 LLM 歧义空间，3-judge majority 适用 LLM-judge 场景不适用 deterministic gate eval (raw text 抽查 spot-check 6 行已在 commit-3 message 记录)。**Eval drivers retained as permanent regression sweep**：`tests/feature-196-sidecar-content-gate.eval.ts` + `benchmark/datasets/feature-196-sidecar-content-gate/cases.ts` 入 repo；raw dumps 留 `<tmpdir>/kodax-eval-dumps/feature-196-sidecar-content-gate/` per `feedback_eval_dumps_stay_in_temp` 不入 repo；mkdirSync per flush survive Windows tmpdir race per `feedback_audit_dump_dir_vanishes`。**Behavior change for users**：trivial-chat (greeting + 零 tool call + ≤20 codepoint) 无 sidecar latency (省 3-10s tail + LLM cost)；imperative + zero-action (zhipu intent-vs-action floor) 仍 fire 保 F184 contract；mutation + worker tool_use 仍 fire；`KODAX_VERIFIER_ALWAYS=1` env opt-back-in 强制 fire (debug / audit)。详见 [v0.7.43.md §FEATURE_196](docs/features/v0.7.43.md#feature_196-sidecar-verifier-content-aware-gate--action-surface-detector--conversational-user-intent-skip) + ADR-030 §F195/F196 cross-reference。

package/README.md

@@ -220,7 +220,7 @@ and diagnostics without activating the backend or requesting elevation.
 Per-command sandbox routing remains internal and is not shown in normal command
 history. SDK embedders can use the same capability independently through
 `@kodax-ai/kodax/sandbox`; see the
-[SDK sandbox guide](docs/SDK_EMBEDDER_GUIDE.md#30-standalone-sandbox-sdk-v0778).
+[SDK sandbox guide](public_docs/sdk/embedder-guide.md#30-standalone-sandbox-sdk-v0778).
 
 Credential-shaped environment variables are filtered from model-issued shell
 commands by default. To expose exact host variables to those command targets,
@@ -415,7 +415,7 @@ const result = await runKodaX(
 ```
 
 > **Embedding KodaX inside another app?** (KodaX Space, IDE extensions, custom CLIs)
-> See [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) for the runtime-mutation
+> See [public_docs/sdk/embedder-guide.md](public_docs/sdk/embedder-guide.md) for the runtime-mutation
 > surface (`startKodaX` + `RunningSession`), MCP popout manager API (`McpManager`),
 > Skill `` !`cmd` `` host hook, and per-app data dir namespacing (`getAppDataDir`).
 
@@ -546,13 +546,14 @@ home credential paths and the complete resolved agent home without turning
 ordinary external reads into an allowlist. See the
 [v0.7.78 design](docs/features/v0.7.78.md), the
 [release checklist](docs/release.md#v0778-release-verification), and
-[SDK guide sections 29–30](docs/SDK_EMBEDDER_GUIDE.md#29-evidence-gated-background-skill-learning-feature_263-v0778).
+[SDK guide sections 29–30](public_docs/sdk/embedder-guide.md#29-evidence-gated-background-skill-learning-feature_263-v0778).
 
 The release closure also preserves intent across adjacent surfaces: static
 Skill instructions load in Edit/Plan without granting later side effects,
-dynamic Skill commands require an explicit host-controlled executor, root AMA
-uses the governed `memory_intent` lifecycle (including explicit intent captured
-before a later cancellation), Workflow Actor waits remain
+dynamic Skill commands require an explicit host-controlled executor, root AMA
+handles explicit remember/correct/forget requests immediately through the
+governed `memory_intent` control plane while exceptional or inferred changes
+remain reviewable, Workflow Actor waits remain
 unbounded unless the workflow sets a deadline, and Runtime Auto capability v4
 advertises `fallbackPersistsEngine:false` across embedded, Worker, and daemon
 hosts. Actor ownership additionally uses Runtime identity rather than PID alone,
@@ -609,7 +610,7 @@ before KodaX reports them as delivered. Every delivered item exposes its
 restart. A multi-input safe-boundary drain keeps each prompt as a separate user
 message and maps it to its own entry. Runtime-owned persistence or provenance
 failure fails the delivery closed rather than emitting an unverifiable event.
-FEATURE_287 remains planned for v0.7.88; this is a non-Feature patch. See the
+FEATURE_287 remains planned for v0.7.93; this is a non-Feature patch. See the
 [v0.7.81 release checklist](docs/release.md#v0781-release-preparation).
 
 **v0.7.82 Runtime causality release:** Daemon capability discovery now composes
@@ -621,7 +622,7 @@ trusted Abort remains terminal causality before credential redaction without
 overriding a real completion or independent failure. Input submission resolves
 the admitted authoritative Run before reading mutable Session history, so
 active interrupt and after-turn admission do not produce a transient
-`data_changed` rejection. FEATURE_287 remains planned for v0.7.88; this is a
+`data_changed` rejection. FEATURE_287 remains planned for v0.7.93; this is a
 non-Feature patch. See the [v0.7.82 release checklist](docs/release.md#v0782-release-preparation).
 
 **v0.7.83 Windows daemon containment release:** Windows daemon startup creates
@@ -631,9 +632,30 @@ exports `waitForRuntimeDaemonShutdown()` and capability
 `daemonShutdownVerification:1`; CLI stop waits for both daemon and supervisor
 exit. Legacy uncontained daemons are not reported as verified and are not
 silently upgraded in place. The Worker owner-lease portion of Issue 256 remains
-scheduled for v0.7.84, and FEATURE_287 remains planned for v0.7.88. See the
+scheduled for v0.7.85, and FEATURE_287 remains planned for v0.7.93. See the
 [v0.7.83 release checklist](docs/release.md#v0783-release-preparation).
 
+**v0.7.84 Actor settlement recovery release:** Agent progress persistence is
+now bounded to one in-flight write plus one latest replacement, so terminal
+settlement cannot wait behind an unbounded progress backlog. A same-owner Stop
+can reconcile a late Actor snapshot after a durability timeout, durably quiesce
+remaining children, and retry the repair. Promise success/failure facts remain
+authoritative over fallback callbacks after repair; stale durable unknown state
+cannot rewind a local terminal Run or duplicate cancellation effects. No-op
+quiescence avoids an unnecessary Session rewrite. See the
+[v0.7.84 release checklist](docs/release.md#v0784-release-preparation).
+
+**v0.7.85 release:** this release ships the F289/F290 Memory review and
+lesson/verdict pipeline, F291 Session-scoped Runtime Event Journals, and F292
+conversation-first Memory management with the additive experimental SDK
+management facade. It also includes Actor settlement convergence, Agent Home
+and learned-root guardrails, terminal startup replay avoidance, idle
+repo-intelligence Worker retirement, Windows sandbox/ACL hardening, and the
+matching regression guides. These include intentional runtime and system-code
+changes. Issue 256's remaining Worker owner-lease boundary is still open and
+is scheduled for v0.7.86; this release does not claim descendant-closure proof
+for that unresolved portion. See the [v0.7.85 release checklist](docs/release.md#v0785-release-preparation).
+
 The v0.7.77 release also adds an opt-in, host-configurable Shell Execution Contract.
 Runtime Session settings or an individual Run can select `pwsh`, Windows
 PowerShell, `cmd`, `bash`, `zsh`, or an explicit Git Bash executable; KodaX
@@ -645,7 +667,7 @@ before profile/setup code and again before the command starts. Credential-shaped
 variables are also filtered on the legacy platform-shell path; explicit names
 in user-level `sandbox.envPass` are restored only for the final command target.
 When `shellExecution` is absent, the established interpreter path is unchanged. See
-[SDK Embedder Guide section 28](docs/SDK_EMBEDDER_GUIDE.md#28-host-configurable-shell-execution-contract-v0777)
+[SDK Embedder Guide section 28](public_docs/sdk/embedder-guide.md#28-host-configurable-shell-execution-contract-v0777)
 and the [Issue 214 regression guide](docs/test-guides/ISSUE_214_v0.7.77_REGRESSION_GUIDE.md).
 
 Kimi Code requests also receive a stable, opaque prompt-cache affinity key
@@ -687,10 +709,10 @@ silently fall back to inline Coder.
 For the full host-integration contract, including inline/Worker/daemon selection,
 multi-client permission handling, config/catalog/MCP admin APIs, artifacts,
 context diagnostics, and daemon protocol schemas, see
-[docs/SDK_EMBEDDER_GUIDE.md §17](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-worker-isolation-and-local-daemon-feature_253-feature_257).
 
 The Space/IDE shared-daemon contract is documented in
-[SDK Embedder Guide section 23](docs/SDK_EMBEDDER_GUIDE.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769).
+[SDK Embedder Guide section 23](public_docs/sdk/embedder-guide.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769).
 
 **v0.7.72–v0.7.73 Runtime permission contract:** Auto Mode is owned by the Runtime session,
 not by a UI hook. It reuses its LLM/rules guardrail across turns, classifies
@@ -703,7 +725,7 @@ the Accept-edits safety boundary; they never change the engine to rules.
 Runtime permission prompts offer opaque, exact
 allow-once/session/persistent grant suggestions; persistent grants are
 daemon-owned and revisioned. Host plan exit is exposed only when the host
-supplies an approval callback. See the [Runtime Auto Mode integration guide](docs/SDK_EMBEDDER_GUIDE.md#24-runtime-owned-auto-mode-and-plan-approval-bridges-v0772v0773).
+supplies an approval callback. See the [Runtime Auto Mode integration guide](public_docs/sdk/embedder-guide.md#24-runtime-owned-auto-mode-and-plan-approval-bridges-v0772v0773).
 
 ## Repo Intelligence
 
@@ -804,7 +826,7 @@ KodaX has two layers that consumers should understand separately:
 | `packages/agent`  | `@kodax-ai/kodax/skills`  | **Narrow subset** | Skills system only — `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` / ... (26 exports = pre-v0.7.43 `@kodax-ai/skills` complete API) | Skill loaders, IDE plugins |
 | `packages/agent`  | `@kodax-ai/kodax/mcp`     | **Narrow subset** | MCP only — `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` / ... (23 exports) | MCP server hosts |
 | `packages/agent`  | `@kodax-ai/kodax/media`   | **Narrow subset** | Structured image/file/video input-artifact helpers (22 exports) | Desktop hosts and multimodal clients |
-| `packages/agent`  | `@kodax-ai/kodax/experimental-memory` | **Experimental subset** | Thin F228-backed `MemoryAgent` / `MemorySession` contracts for scoped recall, deliberate query, observations, and outcomes | SDK hosts explicitly evaluating FEATURE_260 |
+| `packages/agent`  | `@kodax-ai/kodax/experimental-memory` | **Experimental subset** | Thin F228-backed `MemoryAgent` / `MemorySession` lifecycle plus additive `MemoryManagementAgent` list/remember/forget | SDK hosts explicitly evaluating FEATURE_260 / FEATURE_292 |
 | `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 |
@@ -828,21 +850,21 @@ KodaX has two layers that consumers should understand separately:
 
 **Context-Efficient Tool Results + Workflow Quality Preflight (FEATURE_251 + FEATURE_252, v0.7.61; corrected 2026-07-14)**: local tools collect complete output and apply only contract-equivalent normalization that is strictly shorter; command-specific lossy Bash filters are off by default, and compound Bash uses no semantic adapter. One owner evaluates the complete parallel-result batch against the final provider request: it solves the largest final input `Pmax` for which `Pmax + output reserve + max(2048, 3% of Pmax) <= context window`, then admits only the remaining physical capacity. Results stay verbatim whenever they fit; only real overflow persists the complete value and emits `KODAX_RESULT_INCOMPLETE`. History keeps the same physical-capacity safety rule: no default lossy microcompaction below capacity, summary-first at pressure, and typed failure without silent deletion when a recoverable request cannot be formed. FEATURE_272 supersedes FEATURE_251 only for the default major-compaction trigger. FEATURE_252's deterministic pre-start workflow contract lint is unchanged. See [docs/features/v0.7.61.md](docs/features/v0.7.61.md) and [docs/ADR.md ADR-050](docs/ADR.md).
 
-**Reliable Always-On Context Compaction (FEATURE_272, v0.7.74)**: automatic major compaction cannot be disabled. Its percentage trigger defaults to 75% and clamps to 15-90%; optional `triggerTokens` is inactive when omitted/zero, otherwise the smaller percentage, absolute, and physical-capacity threshold wins. The protected raw tail is 20% of that effective trigger. One transaction summarizes the complete eligible prefix, preserves every genuine user request through an exact ledger, and emits success only after a physically valid token reduction and awaited durable commit. Before raw bodies are evicted, the Session owner durably flushes their exact lineage; stable entry IDs merge the sidecar and slim Session without duplicates. Root and persistent child Agents can recover omitted user/assistant/tool details through bounded `session_history_search` → `session_history_read`, with children isolated to hidden worker Sessions and never granted root-history access. SDK/Runtime clients use revision-bound `transcriptSearch`, pages, and lossless chunks. Hidden reasoning, system instructions, and synthetic checkpoints are excluded from model search. See [the feature design](docs/features/v0.7.74.md), [SDK guide §25](docs/SDK_EMBEDDER_GUIDE.md#25-always-on-context-compaction-and-bounded-transcript-recovery-v0774), and [ADR-057](docs/ADR.md#adr-057-large-compaction-is-an-always-on-context-scoped-full-coverage-transaction).
+**Reliable Always-On Context Compaction (FEATURE_272, v0.7.74)**: automatic major compaction cannot be disabled. Its percentage trigger defaults to 75% and clamps to 15-90%; optional `triggerTokens` is inactive when omitted/zero, otherwise the smaller percentage, absolute, and physical-capacity threshold wins. The protected raw tail is 20% of that effective trigger. One transaction summarizes the complete eligible prefix, preserves every genuine user request through an exact ledger, and emits success only after a physically valid token reduction and awaited durable commit. Before raw bodies are evicted, the Session owner durably flushes their exact lineage; stable entry IDs merge the sidecar and slim Session without duplicates. Root and persistent child Agents can recover omitted user/assistant/tool details through bounded `session_history_search` → `session_history_read`, with children isolated to hidden worker Sessions and never granted root-history access. SDK/Runtime clients use revision-bound `transcriptSearch`, pages, and lossless chunks. Hidden reasoning, system instructions, and synthetic checkpoints are excluded from model search. See [the feature design](docs/features/v0.7.74.md), [SDK guide §25](public_docs/sdk/embedder-guide.md#25-always-on-context-compaction-and-bounded-transcript-recovery-v0774), and [ADR-057](docs/ADR.md#adr-057-large-compaction-is-an-always-on-context-scoped-full-coverage-transaction).
 
-**Mailbox-Driven Agent Coordination (FEATURE_273, v0.7.74)**: `wait_agent` is now a true model-facing mailbox yield with one bounded `timeout_ms`, not an Actor progress/event reader. It wakes for scoped Agent messages or completions, root user input, interruption, or timeout; progress remains available to UI/SDK snapshot, replay, and long-poll consumers without resampling the parent model. The tool returns only a wake acknowledgement, while authenticated Agent evidence and structured task metadata enter the next safe model boundary once. Unacknowledged root completions survive a hard restart, same-process Runtime rebuilds deduplicate by child turn ID, and acknowledged or legacy historical completions are not replayed. Use `list_agents` for tree state and `agent_output` for a targeted known result. See [the feature design](docs/features/v0.7.74.md#feature_273-mailbox-driven-agent-wait-and-telemetrycontrol-separation), [SDK guide §26](docs/SDK_EMBEDDER_GUIDE.md#26-agent-mailbox-control-versus-sdk-event-telemetry-v0774), and [ADR-058](docs/ADR.md#adr-058-model-agent-wait-is-mailbox-control-not-event-telemetry).
+**Mailbox-Driven Agent Coordination (FEATURE_273, v0.7.74)**: `wait_agent` is now a true model-facing mailbox yield with one bounded `timeout_ms`, not an Actor progress/event reader. It wakes for scoped Agent messages or completions, root user input, interruption, or timeout; progress remains available to UI/SDK snapshot, replay, and long-poll consumers without resampling the parent model. The tool returns only a wake acknowledgement, while authenticated Agent evidence and structured task metadata enter the next safe model boundary once. Unacknowledged root completions survive a hard restart, same-process Runtime rebuilds deduplicate by child turn ID, and acknowledged or legacy historical completions are not replayed. Use `list_agents` for tree state and `agent_output` for a targeted known result. See [the feature design](docs/features/v0.7.74.md#feature_273-mailbox-driven-agent-wait-and-telemetrycontrol-separation), [SDK guide §26](public_docs/sdk/embedder-guide.md#26-agent-mailbox-control-versus-sdk-event-telemetry-v0774), and [ADR-058](docs/ADR.md#adr-058-model-agent-wait-is-mailbox-control-not-event-telemetry).
 
 **Active-Run Interrupt Input (v0.7.74)**: embedded Runtime and the shared daemon advertise `interruptInput:1`. `runtime.runs.submitInput()` queues an immutable, ordered input for the current active Actor Run; all inputs admitted before one safe Runner boundary are delivered FIFO as separate user messages in the next LLM request, without creating continuation Runs. Queued/delivered state is visible in typed Run snapshots/events, delivery is acknowledged against the exact consumed IDs, and terminal cleanup prevents undelivered input from leaking into later Runs.
 
-**External Agent SDK Plane (FEATURE_258, v0.7.67)**: `/agent` exports the protocol-neutral executor, registration, policy, credential-broker, artifact-policy, catalog, and durable task contracts. `/runtime` exposes the installed plane through `admin.agentRegistrations`, `agents`, and `agentTasks`, with the same DTO service methods over embedded and daemon clients. Executor factories are host functions: install them in an inline owner or while creating a new in-process daemon owner; they cannot be injected through an existing daemon connection or across a Runtime Worker boundary. Plane shutdown is terminal: pending waits and all later service calls reject. Restricted Workflow scripts preserve validated `phase` and external `target` routing. See the [complete owner/consumer recipes and safety contract](docs/SDK_EMBEDDER_GUIDE.md#18-external-agent-executor-plane-feature_258-v0767).
+**External Agent SDK Plane (FEATURE_258, v0.7.67)**: `/agent` exports the protocol-neutral executor, registration, policy, credential-broker, artifact-policy, catalog, and durable task contracts. `/runtime` exposes the installed plane through `admin.agentRegistrations`, `agents`, and `agentTasks`, with the same DTO service methods over embedded and daemon clients. Executor factories are host functions: install them in an inline owner or while creating a new in-process daemon owner; they cannot be injected through an existing daemon connection or across a Runtime Worker boundary. Plane shutdown is terminal: pending waits and all later service calls reject. Restricted Workflow scripts preserve validated `phase` and external `target` routing. See the [complete owner/consumer recipes and safety contract](public_docs/sdk/embedder-guide.md#18-external-agent-executor-plane-feature_258-v0767).
 
-**Cost-Disciplined Workflow SDK (FEATURE_259, v0.7.67)**: SDK callers configure run-scoped `modelTiers` and `workflow.maxConcurrency`, while workflow authors express semantic `fast` / `balanced` / `deep` intent. Terminal workflow events expose resolved tier/source/fallback/usage/duration facts, and each durable `run.json` contains an `efficiencyReport` with token coverage, role/tier starts, packet-read topology, review waves, and quality-gate outcomes. See the [routing and telemetry contract](docs/SDK_EMBEDDER_GUIDE.md#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767).
+**Cost-Disciplined Workflow SDK (FEATURE_259, v0.7.67)**: SDK callers configure run-scoped `modelTiers` and `workflow.maxConcurrency`, while workflow authors express semantic `fast` / `balanced` / `deep` intent. Terminal workflow events expose resolved tier/source/fallback/usage/duration facts, and each durable `run.json` contains an `efficiencyReport` with token coverage, role/tier starts, packet-read topology, review waves, and quality-gate outcomes. See the [routing and telemetry contract](public_docs/sdk/embedder-guide.md#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767).
 
-**Paged Session Listing (FEATURE_261, v0.7.67)**: both `/session` `listSessions()` and `runtime.sessions.list()` accept an exact `surface` filter and opaque continuation `cursor`; each returned summary carries the cursor for the next page. Filtering happens before the page limit, so a host does not need to over-fetch mixed surfaces. See the [pagination recipes](docs/SDK_EMBEDDER_GUIDE.md#19-session-surface-filtering-and-cursor-pagination-feature_261-v0767).
+**Paged Session Listing (FEATURE_261, v0.7.67)**: both `/session` `listSessions()` and `runtime.sessions.list()` accept an exact `surface` filter and opaque continuation `cursor`; each returned summary carries the cursor for the next page. Filtering happens before the page limit, so a host does not need to over-fetch mixed surfaces. See the [pagination recipes](public_docs/sdk/embedder-guide.md#19-session-surface-filtering-and-cursor-pagination-feature_261-v0767).
 
-**Experimental Memory Agent SDK (FEATURE_260, v0.7.68)**: `/experimental-memory` exposes the thin agent-layer `MemoryAgent` and scoped `MemorySession` lifecycle over the existing governed F228 plane. Passive recall is zero-wait; `query()` is read-only and deliberate; durable changes still require the proposal/preview/fingerprint/apply path. The Action LLM remains the final decision maker, recalled content stays low-authority, and safety/scope gates remain deterministic. See the [direct session and boundary guide](docs/SDK_EMBEDDER_GUIDE.md#21-experimental-governed-memory--experimental-memory-feature_260-v0768).
+**Experimental Memory Agent SDK (FEATURE_260 + FEATURE_292)**: `/experimental-memory` exposes the source-compatible `MemoryAgent`/`MemorySession` lifecycle plus the additive `MemoryManagementAgent` facade when `createMemoryAgent()` receives a `MemoryManagementController`. That facade provides governed `list()`, `remember()`, and `forget()` through the same plane used by the conversation-first product surface. Passive recall is zero-wait; `query()` is read-only and deliberate; recalled content stays low-authority, and safety/scope gates remain deterministic. See the [direct session and boundary guide](public_docs/sdk/embedder-guide.md#21-experimental-governed-memory--experimental-memory-feature_260--feature_275--feature_292-v0768v0785).
 
-**Bidirectional A2A 1.0 (FEATURE_267, v0.7.69)**: `/a2a` discovers allowed Agent Cards and installs a JSON-RPC/SSE executor through the existing F258 plane. Configured outbound Agents are also registered automatically as `external:<name>` in embedded CLI and user-daemon Runtimes, so the main Agent can orchestrate them without host code. One `a2a.json` may hold many outbound registrations and at most one inbound server, which publishes either the Runtime default or one validated `~/.kodax/agents/*.md` Agent behind an authenticated Runtime facade. The built-in listener is loopback-only and will not return a port blocked by Fetch-compatible clients; public deployment uses `handle()` behind host-owned TLS and authorization. A2A 0.3, gRPC, HTTP+JSON, push notifications, and automatic public exposure are not advertised. See the [client/server recipes and security boundaries](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769).
+**Bidirectional A2A 1.0 (FEATURE_267, v0.7.69)**: `/a2a` discovers allowed Agent Cards and installs a JSON-RPC/SSE executor through the existing F258 plane. Configured outbound Agents are also registered automatically as `external:<name>` in embedded CLI and user-daemon Runtimes, so the main Agent can orchestrate them without host code. One `a2a.json` may hold many outbound registrations and at most one inbound server, which publishes either the Runtime default or one validated `~/.kodax/agents/*.md` Agent behind an authenticated Runtime facade. The built-in listener is loopback-only and will not return a port blocked by Fetch-compatible clients; public deployment uses `handle()` behind host-owned TLS and authorization. A2A 0.3, gRPC, HTTP+JSON, push notifications, and automatic public exposure are not advertised. See the [client/server recipes and security boundaries](public_docs/sdk/embedder-guide.md#22-bidirectional-a2a-10--a2a-feature_267-v0769).
 
 **A2A interoperability and authentication hardening** keeps a discovered
 interface on the trusted Agent Card origin and sends credentials only when one
@@ -1077,9 +1099,9 @@ All 13 SDK entries (root + 12 subpaths) share internal code via ESM chunk splitt
 For the complete host-facing contract — including embedded/Worker/daemon ownership,
 external-agent registration and task control, session cursor pagination, workflow
 model-tier routing, and efficiency telemetry — see the
-[SDK Embedder Integration Guide](docs/SDK_EMBEDDER_GUIDE.md).
+[SDK Embedder Integration Guide](public_docs/sdk/embedder-guide.md).
 
-> **ESM-only.** The SDK is published as ES Modules. In a CommonJS context (Electron main process, legacy Webpack CJS bundles, `require()`-based code) you must use `await import(...)` instead of `require()`. See [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles) for the canonical recipe + the technical reason most subpaths cannot ship a dual ESM/CJS build.
+> **ESM-only.** The SDK is published as ES Modules. In a CommonJS context (Electron main process, legacy Webpack CJS bundles, `require()`-based code) you must use `await import(...)` instead of `require()`. See [public_docs/sdk/embedder-guide.md §5](public_docs/sdk/embedder-guide.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles) for the canonical recipe + the technical reason most subpaths cannot ship a dual ESM/CJS build.
 
 For CLI users, provider defaults live in `~/.kodax/config.json`. For library users, API keys are still read from environment variables; if you need custom base URLs or provider aliases, use `registerCustomProviders()` as shown above.
 
@@ -1424,7 +1446,7 @@ import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';      // A2A 1.0 clie
 import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in experimental memory SDK
 ```
 
-> The SDK is **ESM-only**. CommonJS consumers (Electron main / Webpack CJS / `require()` callers) must use `await import('@kodax-ai/kodax/...')` — see [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles).
+> The SDK is **ESM-only**. CommonJS consumers (Electron main / Webpack CJS / `require()` callers) must use `await import('@kodax-ai/kodax/...')` — see [public_docs/sdk/embedder-guide.md §5](public_docs/sdk/embedder-guide.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles).
 
 ### `@kodax-ai/kodax/llm` — LLM Abstraction
 
@@ -1575,7 +1597,7 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 | 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 |
-| Experimental governed memory | `@kodax-ai/kodax/experimental-memory` | Scoped `MemoryAgent` / `MemorySession` recall and outcome contracts |
+| Experimental governed memory | `@kodax-ai/kodax/experimental-memory` | Governed `MemoryAgent` list/remember/forget and scoped `MemorySession` recall/outcome contracts |
 
 ---
 
@@ -1859,7 +1881,7 @@ KodaX uses an **English-first** comment style with selective Chinese brief notes
 ## Documentation
 
 - [README_CN.md](README_CN.md) - Chinese Documentation
-- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK hosting, shared Runtime daemon, Auto Mode, v0.7.74 compaction/history recovery, Agent telemetry, and active-run input contracts
+- [public_docs/sdk/embedder-guide.md](public_docs/sdk/embedder-guide.md) - SDK hosting, shared Runtime daemon, Auto Mode, v0.7.74 compaction/history recovery, Agent telemetry, and active-run input contracts
 - [docs/release.md](docs/release.md) - Standalone binary build & release pipeline
 - [docs/PRD.md](docs/PRD.md) - Product Requirements
 - [docs/ADR.md](docs/ADR.md) - Architecture Decisions