@kodax-ai/kodax 0.7.84 → 0.7.86

package/CHANGELOG.md

@@ -6,7 +6,220 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
-No changes yet.
+---
+
+## [0.7.86] - 2026-08-14
+
+> Git tag and GitHub Release are created by the release workflow. npm
+> publication remains a separate manual operator step.
+
+### Fixed
+
+- Windows sandbox doctor and required Shell calls now surface actionable ACL
+  crash-recovery guidance for legacy or corrupt owner markers instead of a
+  generic unavailable result. Sandbox setup is serialized with owner admission
+  and cannot mutate account, guard, or WFP state while any sandbox owner or
+  unresolved poison marker exists for the shared Windows sandbox account. New owner markers
+  remain readable by older runtimes, while atomic-write staging files are kept
+  outside the legacy marker directory.
+- Windows workspace Shell sessions now derive bounded read grants from each
+  command's final PATH and shell executable. Existing lexical and canonical
+  directories are admitted exactly; junction targets receive only the minimum
+  traversal ancestors below their profile application root, so version managers,
+  shims, virtual environments, and sibling runtime files work without naming
+  individual tools or exposing broad Documents/AppData vendor trees. Windows
+  shares one effective policy scope across compatible commands and confirms ACL
+  reset before switching to an incompatible scope. Standalone SDK calls,
+  workspace sessions, and duplicate SDK module copies use the same machine-wide
+  policy-owner protocol across Runtime profiles and KodaX homes, so incompatible
+  grants cannot combine through the shared Windows sandbox identity. The
+  target receives a case-normalized environment and preserves the Windows
+  verbatim-argument contract, so
+  profile-managed executables and quoted path arguments survive both broker layers.
+- Auto-started Runtime clients now require sandbox execution capability v3, so
+  an idle daemon from KodaX 0.7.85 or the earlier v2 execution policy is replaced only after its durable shutdown
+  outcome and Windows Job supervisor prove the old process tree is empty. A
+  daemon without that verification contract remains fail-closed and must be
+  stopped explicitly before the repaired Shell chain is exposed.
+- The first upgrade from a Runtime that predates the machine-wide Windows
+  sandbox-owner protocol requires all unmanaged legacy KodaX/Space processes
+  (including standalone SDK processes using another KodaX home) to be stopped.
+  Those binaries cannot participate in the new global owner lock; current and
+  future runtimes are serialized machine-wide after the transition.
+- Clean Windows workspace-session shutdown now honors the sandbox runtime's full
+  ACL reset budget before escalating to process-tree termination, while unclean
+  or unverified exits remain durably fail-closed.
+- Windows Shell sessions now share one ACL policy group when their normalized
+  workspace, Agent Home access, additional filesystem permissions, toolchain
+  scopes, and network policy are identical. Compatible commands can run in
+  parallel across independent KodaX processes; the last policy-group member confirms
+  reset before releasing its owner. Different policies fall back immediately
+  to the already-authorized ordinary execution path instead of blocking on a
+  machine-wide sandbox fence. Preparation failures use the same fallback, while
+  a command that started or may have started is never replayed implicitly.
+- Filesystem-effect coordinator handoff now waits through the lock protocol's
+  30-second stale-owner safety window. Slow or rapid cross-process handoffs no
+  longer fail at five seconds, while real cross-category effect conflicts keep
+  their existing one-second fail-closed admission boundary.
+- Runtime Shell containment is now sandbox-first rather than sandbox-required.
+  Auto[LLM] remains the single authorization decision, successful allow results
+  are cached only for the same Runtime-session intent revision, and unavailable
+  sandbox infrastructure uses normal permission enforcement without another
+  classifier call. Catastrophic root deletion, disk formatting/raw disk writes,
+  fork bombs, and Agent Home root/control-plane destruction remain deterministic
+  hard denials. The obsolete public `failClosed` switch has been removed.
+- The packaged Electron regression smoke now runs 20 Runtime Shell commands
+  through a profile-added junction toolchain, resolves the packaged Node binary
+  through its version-manager ancestry, exercises a quoted `cmd.exe` path, and
+  keeps its probe I/O inside the admitted workspace.
+- Packaged Electron hosts on Windows now keep Electron's Node bootstrap mode
+  across the internal filesystem-effect gate without leaking it to user
+  commands. Sandbox readiness uses KodaX's staged runner outside ASAR, failed
+  workspace sessions are retired, stale ACLs are recovered before startup and
+  after the last compatible sandbox owner exits, and an execution with missing
+  attestation is reported without replaying a possibly side-effecting command.
+- Sandbox stop now waits for process-tree termination proof before ACL recovery;
+  undrained Shell effects and spawn/cleanup failure combinations are reported as
+  lifecycle safety errors. Windows ACL owner markers admit only an exact shared
+  policy group for the machine sandbox identity, and crash recovery is serialized
+  across Runtime profiles.
+- Inline Runtime owner recovery now removes only a provably abandoned inline
+  owner fence before restoring daemon policy. Live, unreadable, legacy-kind,
+  daemon-kind, and unverifiable owners remain fail-closed, while a failed
+  inline-owner release remains retryable.
+- Runtime owner records and learning-file locks now retain an OS process-start
+  identity, so a reused PID cannot keep stale ownership alive.
+- Windows sandbox lifecycle failures now wait for termination proof, preserve
+  cleanup evidence, fence later filesystem effects, and never replay a command
+  whose effect process was not proven drained.
+- POSIX sandbox workspace sessions now latch an unconfirmed process-tree or
+  cleanup failure and reject replacement sessions until the safety state is
+  reset, matching the fail-closed lifecycle contract across platforms. Fresh
+  `KODAX_HOME` policy roots are initialized before policy identity is captured,
+  concrete admissions wait only for their workspace-local warm-up within the
+  existing Shell abort/deadline, and a failed lease cleanup retires the invalid
+  cached session before replacement.
+
+---
+
+## [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.
 
 ---
 
@@ -2022,7 +2235,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
@@ -2369,7 +2582,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.)
 
@@ -2448,7 +2661,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
 
@@ -2520,7 +2733,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。