@kodax-ai/kodax 0.7.76 → 0.7.77

package/dist/types-chunks/{types.d-sRLugmjy.d.ts → types.d-RdWRfUEs.d.ts}

@@ -1,4 +1,4 @@
-import { k as KodaXMessage, a1 as KodaXToolDefinition, F as KodaXReasoningMode, a9 as KodaXWireReasoningEffort, a3 as KodaXToolResultContentItem, Y as KodaXThinkingBlock, I as KodaXRedactedThinkingBlock } from './types.d-CSmF0t0n.js';
+import { k as KodaXMessage, a1 as KodaXToolDefinition, F as KodaXReasoningMode, a9 as KodaXWireReasoningEffort, a3 as KodaXToolResultContentItem, Y as KodaXThinkingBlock, I as KodaXRedactedThinkingBlock } from './types.d-DIpZJKUl.js';
 
 type AgentActorState = 'running' | 'idle' | 'closed';
 type AgentTurnState = 'accepted' | 'running' | 'completed' | 'failed' | 'interrupted';
@@ -195,10 +195,14 @@ interface AgentExecutionResult {
     readonly artifacts?: readonly string[];
     readonly artifactDetails?: readonly AgentArtifactDescriptor[];
     readonly structured?: AgentMetadataValue;
+    /** Runtime-observed completion facts merged into the durable Turn metadata. */
+    readonly turnMetadata?: Readonly<Record<string, AgentMetadataValue>>;
 }
 interface AgentMutationOptions {
     /** Optimistic Actor revision checked inside the serialized durable mutation. */
     readonly expectedRevision?: number;
+    /** Optimistic tree revision checked inside the serialized durable mutation. */
+    readonly expectedTreeRevision?: number;
 }
 interface AgentTurnExecutor {
     execute(input: AgentExecutionInput): Promise<AgentExecutionResult>;
@@ -223,7 +227,7 @@ interface AgentActorStore {
 /** Runtime-bound actor control surface. The caller path is minted by Runtime. */
 interface AgentActorClient {
     readonly callerPath: string;
-    spawn(input: AgentSpawnInput): Promise<AgentTurnRef>;
+    spawn(input: AgentSpawnInput, options?: AgentMutationOptions): Promise<AgentTurnRef>;
     send(targetPath: string, content: string, classification?: AgentDataClassification, forwardedMessageId?: string): Promise<AgentMailboxMessage>;
     followup(targetPath: string, objective: string, metadata?: Readonly<Record<string, AgentMetadataValue>>, options?: AgentMutationOptions): Promise<AgentFollowupResult>;
     interrupt(targetPath: string, reason?: string, scope?: AgentInterruptScope): Promise<void>;
@@ -974,10 +978,16 @@ interface MemoryDecisionTraceReceipt {
     readonly decisionRevision: string;
     readonly policyVersion: string;
     readonly candidateSetFingerprint: string;
+    readonly candidateIds: readonly string[];
+    readonly selectedCandidateIds: readonly string[];
+    readonly injectedEvidenceRefs: readonly string[];
+    readonly triggers?: readonly ('tool_failure' | 'verification_failure' | 'context_compacted')[];
     readonly candidateRefs: readonly string[];
     readonly selectedRefs: readonly string[];
     readonly injectedRefs: readonly string[];
-    readonly selectionModes: readonly ('task_hint' | 'exact' | 'semantic_prefetch' | 'deliberate_query')[];
+    readonly selectionModes: readonly ('task_hint' | 'exact'
+    /** @deprecated Retained for source compatibility; F275 no longer emits this mode. */
+     | 'semantic_prefetch' | 'semantic_intervention' | 'deliberate_query')[];
     readonly actionSignature?: string;
     readonly throughSequence: number;
 }
@@ -1791,6 +1801,13 @@ interface RunnerLlmResult {
     readonly text: string;
     readonly toolCalls?: readonly RunnerToolCall[];
     readonly stopReason?: string;
+    /**
+     * Provider-visible input messages synthesized by the LLM adapter for this
+     * exact generation (for example a runtime reminder). Runner commits them
+     * immediately before the generated assistant message so the authoritative
+     * transcript remains a faithful prefix of the next provider request.
+     */
+    readonly injectedInputMessages?: readonly AgentMessage[];
     /**
      * v0.7.26 parity: extended-thinking blocks from the provider stream.
      * Must be preserved on the assistant message so (a) session resume can
@@ -2123,6 +2140,32 @@ interface RunOptions {
         /** Executed tool names from the iteration that reached this boundary. */
         readonly lastTurnToolNames: readonly string[];
     }) => Promise<readonly AgentMessage[]>;
+    /**
+     * Active-run input continuation owned by an embedder that accepts input
+     * against a specific in-flight run.
+     *
+     * Unlike `beforeNextTurn`, this hook is consulted at a terminal candidate:
+     * a no-tool model response or a terminal tool signal. Runner synchronously
+     * closes admission as soon as it recognizes the candidate, then drains input
+     * that was already accepted. A non-empty drain is committed to the
+     * transcript, admission reopens, and the same run continues.
+     * Lifecycle continuations may reserve only a small fixed number of turns
+     * beyond the configured iteration cap; the final absolute turn keeps
+     * admission closed.
+     *
+     * REPL hosts should omit this option so their existing round boundary keeps
+     * ownership of queued follow-ups.
+     */
+    readonly terminalContinuation?: {
+        readonly closeInputWindow: () => void;
+        readonly reopenInputWindow: () => void;
+        readonly drain: (ctx: {
+            readonly agent: Agent;
+            readonly transcript: readonly AgentMessage[];
+            readonly iteration: number;
+            readonly lastTurnToolNames: readonly string[];
+        }) => Promise<readonly AgentMessage[]>;
+    };
     /**
      * FEATURE_166 (v0.7.41 follow-up) — agent-switch hook.
      *
@@ -2921,7 +2964,7 @@ interface MemoryPackInput {
     readonly includeSensitive?: boolean;
     readonly includeSnippets?: boolean;
     readonly ignoreMemory?: boolean;
-    readonly purpose?: 'automatic' | 'deliberate_query';
+    readonly purpose?: 'automatic' | 'deliberate_query' | 'intervention';
 }
 interface MemoryPackHint {
     readonly ref: MemoryItemRef;

package/dist/types-chunks/{utils.d-D0wPxz8y.d.ts → utils.d-CDduqbFw.d.ts}

@@ -1,9 +1,9 @@
-import { k as KodaXMessage, F as KodaXReasoningMode, d as KodaXCustomProviderConfig, p as KodaXProviderCapabilityProfile } from './types.d-CSmF0t0n.js';
-import { O as KodaXContextTokenSnapshot, aj as KodaXSkillDynamicContextPolicy, t as KodaXAgentMode, a6 as KodaXRepoIntelligenceMode, a1 as KodaXOptions, ak as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-r1beOESM.js';
-import { bX as KodaXSessionUiHistoryItem, bM as KodaXSessionLineage, bD as KodaXSessionArtifactLedgerEntry, bn as KodaXExtensionSessionState, bm as KodaXExtensionSessionRecord, bT as KodaXSessionRuntimeInfo, eb as WorkflowProcessSource } from './types.d-sRLugmjy.js';
-import { d as AgentsFile, r as AutoModeStats, x as KodaXMcpServersConfig } from './guardrail.d-qjuKJZ31.js';
+import { k as KodaXMessage, F as KodaXReasoningMode, d as KodaXCustomProviderConfig, p as KodaXProviderCapabilityProfile } from './types.d-DIpZJKUl.js';
+import { O as KodaXContextTokenSnapshot, an as KodaXSkillDynamicContextPolicy, t as KodaXAgentMode, a7 as KodaXRepoIntelligenceMode, a1 as KodaXOptions, ao as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-pZdu6qt7.js';
+import { bX as KodaXSessionUiHistoryItem, bM as KodaXSessionLineage, bD as KodaXSessionArtifactLedgerEntry, bn as KodaXExtensionSessionState, bm as KodaXExtensionSessionRecord, bT as KodaXSessionRuntimeInfo, eb as WorkflowProcessSource } from './types.d-RdWRfUEs.js';
+import { d as AgentsFile, r as AutoModeStats, x as KodaXMcpServersConfig } from './guardrail.d-B0PwAZVR.js';
 import * as readline from 'readline';
-import { R as PermissionMode, L as LearningBinding, E as LearningSurfaceSnapshot } from './public-api.d-CX4B11qY.js';
+import { R as PermissionMode, L as LearningBinding, E as LearningSurfaceSnapshot } from './public-api.d--fF88JrC.js';
 import { SpawnSyncReturns } from 'child_process';
 
 /**

package/docs/SDK_EMBEDDER_GUIDE.md

@@ -28,13 +28,13 @@ are NOT obvious from inspecting the type definitions alone:
 18. [External-agent executor plane](#18-external-agent-executor-plane-feature_258-v0767)
 19. [Session surface filtering and cursor pagination](#19-session-surface-filtering-and-cursor-pagination-feature_261-v0767)
 20. [Cost-disciplined workflow routing and telemetry](#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767)
-21. [Experimental governed memory — `/experimental-memory`](#21-experimental-governed-memory--experimental-memory-feature_260-v0768)
+21. [Experimental governed memory — `/experimental-memory`](#21-experimental-governed-memory--experimental-memory-feature_260--feature_275-v0768v0777)
 22. [Bidirectional A2A 1.0 — `/a2a`](#22-bidirectional-a2a-10--a2a-feature_267-v0769)
 23. [Shared Coder daemon for Space and IDE hosts](#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769)
 24. [Runtime-owned Auto Mode and plan-approval bridges](#24-runtime-owned-auto-mode-and-plan-approval-bridges-v0772v0773)
-25. [Always-on context compaction and bounded transcript recovery](#25-always-on-context-compaction-and-bounded-transcript-recovery-v0774)
-26. [Agent mailbox control versus SDK event telemetry](#26-agent-mailbox-control-versus-sdk-event-telemetry-v0774)
-27. [Windows GUI background subprocess visibility](#27-windows-gui-background-subprocess-visibility-v0775)
+25. [Always-on context compaction and bounded transcript recovery](#25-always-on-context-compaction-and-bounded-transcript-recovery-v0774)
+26. [Agent mailbox control versus SDK event telemetry](#26-agent-mailbox-control-versus-sdk-event-telemetry-v0774)
+27. [Windows GUI background subprocess visibility](#27-windows-gui-background-subprocess-visibility-v0775)
 
 §1–§3 (and the Phase-7/8 MCP-popout surface in §1) land in v0.7.42
 under FEATURE_186 (see [ADR-032](ADR.md#adr-032-sdk-embedder-surface-closure-feature_186-v0742)).
@@ -2775,11 +2775,11 @@ await runtime.mcp.upsertServer('filesystem', {
 });
 await runtime.mcp.reloadServers();
 
-const commands = await runtime.catalog.commands(process.cwd());
-const skills = await runtime.catalog.skills({ projectRoot: process.cwd() });
-```
-
-This is the intended path for KodaX Space, IDE adapters, and settings UIs:
+const commands = await runtime.catalog.commands(process.cwd());
+const skills = await runtime.catalog.skills({ projectRoot: process.cwd() });
+```
+
+This is the intended path for KodaX Space, IDE adapters, and settings UIs:
 session defaults go through `sessions.updateSettings()`, one-turn overrides go
 through `runs.start({ options })`, and daemon/profile config goes through
 `config`, `catalog`, and `mcp`.
@@ -2799,12 +2799,19 @@ engine:
 Hosts that set `capabilities.contextDiagnostics: true` can read:
 
 ```ts
-const budget = await runtime.diagnostics.latestContextBudget({ sessionId });
-const exposure = await runtime.diagnostics.latestToolExposure({ sessionId });
-```
-
-These diagnostics are designed for status panels and debugging. They should not
-contain raw sensitive tool input/output.
+const budget = await runtime.diagnostics.latestContextBudget({ sessionId });
+const exposure = await runtime.diagnostics.latestToolExposure({ sessionId });
+const cache = await runtime.diagnostics.latestProviderCacheDiagnostic({ sessionId });
+```
+
+Pass `{ sessionId, contextKind: 'child', agentId }` to query one logical child
+even though its physical transcript uses an isolated Session. Diagnostic
+payloads carry `contextId` and, for children, `parentContextId`; reconnecting
+hosts can use the same latest APIs instead of fabricating identity fields.
+These diagnostics are designed for status panels and debugging. Budget
+snapshots contain counts, and cache diagnostics contain hashes plus
+Provider-reported usage; they do not contain raw prompt or sensitive tool
+input/output.
 
 ### Protocol schema and versioning
 
@@ -3219,7 +3226,7 @@ workflow's structured findings, verification results, and quality gates.
 
 ---
 
-## 21. Experimental governed memory — `/experimental-memory` (FEATURE_260, v0.7.68)
+## 21. Experimental governed memory — `/experimental-memory` (FEATURE_260 + FEATURE_275, v0.7.68–v0.7.77)
 
 KodaX has one durable memory plane: the F228 Memory Control Plane. FEATURE_260
 adds a thin, opt-in agent/session API over that plane; it does not add a second
@@ -3280,11 +3287,53 @@ await session.complete({
 await session.close();
 ```
 
-`recall()` is synchronous: exact observations/hints can be returned immediately,
-while an optional semantic prefetch finishes for a later matching decision.
-`query()` is deliberate and read-only; one distinct query is admitted per
-decision epoch, and the result is bounded to at most three prompt-safe hints and
-512 estimated tokens. `undefined` means there is no governed reminder to inject.
+`recall()` is synchronous and exact. `query()` is deliberate and read-only; one
+distinct query is admitted per decision epoch, and the result is bounded to at
+most three prompt-safe hints and 512 estimated tokens. `undefined` means there
+is no governed reminder to inject.
+
+### Sparse foreground intervention (FEATURE_275, v0.7.77)
+
+`MemorySession.intervene()` replaces the old timing-ineffective semantic
+prefetch. It is awaited only after `tool_failure`, `verification_failure`, or a
+durably committed `context_compacted` event, then supplies at most three
+prompt-safe, low-authority evidence items to the next Action-LLM request. The
+candidate set is rebuilt from current objective/open todos, recent governed
+observations, and a fresh F228 pack. Exact selection is deterministic; stale,
+unknown, malformed, timed-out, cancelled, or failed semantic results are
+discarded without blocking the coding run.
+
+Top-level coding runs wire the deterministic path automatically and make zero
+selector calls by default. An inline host that deliberately wants semantic
+selection can provide the coding-owned forced-tool runner:
+
+```ts
+import {
+  createCodingMemoryInterventionRunner,
+  runKodaX,
+} from '@kodax-ai/kodax/coding';
+import { resolveProvider } from '@kodax-ai/kodax/llm';
+
+const memoryRecallRunner = createCodingMemoryInterventionRunner({
+  provider: resolveProvider('zhipu-coding'),
+  model: 'glm-5.2',
+});
+
+await runKodaX(
+  {
+    provider: 'zhipu-coding',
+    model: 'glm-5.2',
+    memoryRecallRunner,
+  },
+  'Finish the repository migration and verify it.',
+);
+```
+
+`memoryRecallRunner` is a process-local function binding. Worker and daemon DTO
+options reject it instead of silently dropping it; configure the binding
+inside the Runtime owner or keep this run inline. The selector can return only
+exact IDs from the closed offered set and is capped at three calls per memory
+Session.
 
 ### Evidence, tracing, and persistence boundaries
 
@@ -3294,9 +3343,11 @@ decision epoch, and the result is bounded to at most three prompt-safe hints and
   material. `rewind()` removes observations after a sequence boundary.
 - `complete()` can emit an Outcome Digest through `persistOutcomeDigest` and run
   bounded episode review through `reviewEpisode`; cancellation creates neither.
-- `onTrace` receives policy-versioned `MemoryDecisionReceipt` metadata that links
-  candidates, selection, injection, and later outcome influence. Receipts are
-  trace-only and contain no hidden reasoning.
+- `onTrace` receives policy-versioned `MemoryDecisionReceipt` metadata that links
+  offered `candidateIds`, validated `selectedCandidateIds`, exposed
+  `injectedEvidenceRefs`, triggers, and later outcome influence. Receipts are
+  trace-only and contain no hidden reasoning; exposure is not proof of
+  causality.
 - Durable memory mutation remains owned by F228's
   proposal/preview/fingerprint/apply flow. `/memory` is the CLI governance
   surface; direct file/shell writes to managed memory roots are denied.
@@ -3945,13 +3996,17 @@ complete ordered batch. Exact operation retries return the same `inputId`.
 The accepted result's `runId` is the existing owning Run (equal to
 `afterRunId`), not a newly created continuation.
 
-Interrupt admission closes when the Runner publishes its final completion or
-terminal error signal, or when the Run's supplied `abortSignal` aborts, even if
-the outer Run is still settling. Non-terminal observer diagnostics do not close
-the window. A submission after closure returns `accepted:false` with
-`reason:'interrupt_window_closed'` and is not queued. Keep the original input
-available for retry after the Run ends; do not silently change its delivery to
-`after_turn`. As a final race/recovery
+Interrupt admission closes when the Runner publishes its final completion or
+terminal error signal, or when the Run's supplied `abortSignal` aborts, even if
+the outer Run is still settling. Non-terminal observer diagnostics do not close
+the window. Same-Run lifecycle continuations also have a fixed internal
+allowance beyond the configured iteration ceiling; the Runner closes admission
+before its final absolute generation so repeated submissions cannot keep one
+Run alive indefinitely. The allowance never expands an admitted manifest's
+`maxIterations` governance cap. A submission after closure returns
+`accepted:false` with `reason:'interrupt_window_closed'` and is not queued. Keep
+the original input available for retry after the Run ends; do not silently
+change its delivery to `after_turn`. As a final race/recovery
 guard, inspect terminal Run status: any `interruptInputs` entry whose state is
 `terminal` was not delivered. Reconcile it by `inputId` and present a visible
 non-delivery outcome rather than leaving a pending queue indicator.
@@ -3968,13 +4023,13 @@ const interrupted = await runtime.runs.submitInput({
 
 Run status exposes acceptance/start/queue times, authenticated origin,
 `sessionOrder`, and a single terminal fact. Important terminal codes include
-`runtime_restarted`, `daemon_crashed`, `credential_unavailable`,
-`host_not_dispatched`, `host_outcome_unknown`, and
-`control_history_untrusted`. Managed tasks that require user input use
-`terminal.code = 'blocked'`; surface `terminal.message` when present instead of
-replacing it with a generic run failure. Respect `effectOutcome`; `unknown` must
-never be presented as success or automatically retried. After a lost response,
-query `runtime.operations.get({ operationId, journalEpoch })`; applied receipts
+`runtime_restarted`, `daemon_crashed`, `credential_unavailable`,
+`host_not_dispatched`, `host_outcome_unknown`, and
+`control_history_untrusted`. Managed tasks that require user input use
+`terminal.code = 'blocked'`; surface `terminal.message` when present instead of
+replacing it with a generic run failure. Respect `effectOutcome`; `unknown` must
+never be presented as success or automatically retried. After a lost response,
+query `runtime.operations.get({ operationId, journalEpoch })`; applied receipts
 include the canonical result. Permission grants remain daemon-owned and
 revisioned.
 
@@ -4609,49 +4664,123 @@ parent transcript commits and acknowledges the completion, later restores do
 not replay it. Legacy snapshots without the explicit pending set do not infer
 replay work from historical mailbox content.
 
-This separation changes no Actor event capability or daemon version: existing
-SDK snapshot, replay, and long-poll clients keep their telemetry surface. It
-only prevents high-frequency progress from becoming a model control signal.
+This separation changes no Actor event capability or daemon version: existing
+SDK snapshot, replay, and long-poll clients keep their telemetry surface. It
+only prevents high-frequency progress from becoming a model control signal.
+
+---
+
+## 27. Windows GUI background subprocess visibility (v0.7.75)
+
+KodaX SDK hosts do not need to add process-wide console suppression around the
+Runtime. In the v0.7.75 release candidate, Runtime Worker-reachable
+non-interactive/background child processes request `windowsHide: true` at their
+own spawn boundary. The covered paths include:
+
+- memory and Git metadata probes;
+- provider CLI execution and ACP servers;
+- LSP acquisition and language servers;
+- clipboard helpers, worktrees, review commands, and extension commands;
+- managed-task checkpoints and sandbox helpers.
+
+The contract is intentionally narrow. Explicit external editors, terminal
+commands, and PTY sessions remain interactive. POSIX-only `ps`, `tmux`, and
+sandbox branches are reviewed bundle-audit exceptions rather than Windows
+visibility paths.
+
+`npm run build:bundle` audits every statically identifiable child-process call
+reachable from `dist/runtime-worker.js`. The packaged Electron daemon smoke then
+runs 20 ordinary queries with a Win32 probe and checks that the expected Git
+children never own a visible console window. These checks validate the SDK
+boundary, but they do not replace product-level validation in the packaged host.
+KodaX Space should install the exact v0.7.75 tarball and complete
+[`ISSUE_205_v0.7.75_REGRESSION_GUIDE.md`](test-guides/ISSUE_205_v0.7.75_REGRESSION_GUIDE.md)
+on Windows 10 and Windows 11 as a non-blocking product validation follow-up.
+This follow-up does not gate SDK packaging, tagging, or publication.
 
 ---
 
-## 27. Windows GUI background subprocess visibility (v0.7.75)
+## 28. Host-configurable Shell Execution Contract (v0.7.77)
 
-KodaX SDK hosts do not need to add process-wide console suppression around the
-Runtime. In the v0.7.75 release candidate, Runtime Worker-reachable
-non-interactive/background child processes request `windowsHide: true` at their
-own spawn boundary. The covered paths include:
+The shared daemon is long-lived, so its startup `process.env.PATH` is not a
+reliable description of every project's toolchain. A host can opt a Session
+into a serializable shell contract:
 
-- memory and Git metadata probes;
-- provider CLI execution and ACP servers;
-- LSP acquisition and language servers;
-- clipboard helpers, worktrees, review commands, and extension commands;
-- managed-task checkpoints and sandbox helpers.
+```ts
+await runtime.sessions.updateSettings(session.id, {
+  executionCwd: projectDirectory,
+  shellExecution: {
+    version: 1,
+    shell: {
+      kind: 'pwsh',             // pwsh | powershell | cmd | bash | zsh
+      profile: 'default',
+    },
+    environment: {
+      inherit: 'filtered',
+      // Trusted host code, not model input. Use it for a directory-aware
+      // activation command when the shell profile does not switch on cwd.
+      setup: 'fnm use --silent-if-unchanged',
+      windowsPath: 'registry',
+    },
+    cache: {
+      ttlMs: 30_000,
+      refreshToken: 'toolchain-revision-1',
+    },
+    probeTimeoutMs: 10_000,
+  },
+});
+```
 
-The contract is intentionally narrow. Explicit external editors, terminal
-commands, and PTY sessions remain interactive. POSIX-only `ps`, `tmux`, and
-sandbox branches are reviewed bundle-audit exceptions rather than Windows
-visibility paths.
+An individual Run can supply `options.context.shellExecution`; a concrete Run
+contract overrides the Session setting. An omitted value or explicit
+`undefined` does not erase the Session setting. Use a `null` Session patch to
+remove it.
 
-`npm run build:bundle` audits every statically identifiable child-process call
-reachable from `dist/runtime-worker.js`. The packaged Electron daemon smoke then
-runs 20 ordinary queries with a Win32 probe and checks that the expected Git
-children never own a visible console window. These checks validate the SDK
-boundary, but they do not replace product-level validation in the packaged host.
-KodaX Space should install the exact v0.7.75 tarball and complete
-[`ISSUE_205_v0.7.75_REGRESSION_GUIDE.md`](test-guides/ISSUE_205_v0.7.75_REGRESSION_GUIDE.md)
-on Windows 10 and Windows 11 as a non-blocking product validation follow-up.
-This follow-up does not gate SDK packaging, tagging, or publication.
+The contract supports an optional absolute `shell.executable` (for example Git
+Bash) and bounded fixed `shell.args`. Command/file/persistence/profile/server
+and working-directory control flags are rejected from those fixed arguments.
+`environment.set` is for non-secret host variables. `denyPatterns` can remove
+additional names but cannot weaken the built-in Provider credential deny set.
+`inherit: "none"` retains only the OS variables required to start the selected
+shell. On Windows, `windowsPath: "registry"` re-reads current Machine/User
+environment values instead of reusing the daemon's startup PATH.
+
+Resolution is two-stage and uses the effective cwd:
+
+1. sanitize the bootstrap environment, including credentials for built-in,
+   custom, active, inactive, and stacked runtime Providers;
+2. start the selected shell, load the requested profile/setup, capture a
+   random-framed environment, validate and sanitize it again;
+3. execute the actual command through that same explicit interpreter.
+
+The cache is in-memory and isolated by normalized contract, canonical cwd,
+Session scratch identity, credential deny names, and refresh generation. TTL
+is bounded to ten minutes; zero disables caching. Daemon restart clears it.
+`clearShellExecutionEnvironmentCache()` is available for an in-process owner
+that needs immediate global invalidation.
+
+Native children, nested Actor turns, Workflow child paths, and deterministic
+build/test/lint evaluators inherit the effective contract. Runtime exact-command
+permission grants bind the interpreter family and contract fingerprint, so a
+grant created under cmd cannot silently authorize the same command after a
+switch to PowerShell or Bash.
+
+Configured-shell failures are visible and fail closed: KodaX does not reinterpret
+the command through another shell. When `shellExecution` is absent, KodaX keeps
+the pre-v0.7.77 platform-shell behavior for compatibility. See
+[`ISSUE_214_v0.7.77_REGRESSION_GUIDE.md`](test-guides/ISSUE_214_v0.7.77_REGRESSION_GUIDE.md)
+for cross-project, cache, cancellation, credential, and Windows argv checks.
 
 ---
 
 ## See also
-
-- [README.md](../README.md) — end-user CLI quick start
+
+- [README.md](../README.md) — end-user CLI quick start
 - [docs/ADR.md ADR-024](ADR.md#adr-024-npm-发布物正名-kodax-aikodax--sdk-subpath-exports-形式化-v0739) — SDK subpath architecture rationale
 - [docs/ADR.md ADR-032](ADR.md#adr-032-sdk-embedder-surface-closure-feature_186-v0742) — FEATURE_186 design record (all 8 phases)
 - [docs/ADR.md ADR-057](ADR.md#adr-057-large-compaction-is-an-always-on-context-scoped-full-coverage-transaction) — v0.7.74 compaction and exact-history ownership
-- [docs/ADR.md ADR-058](ADR.md#adr-058-model-agent-wait-is-mailbox-control-not-event-telemetry) — mailbox control versus Actor telemetry
-- [docs/features/v0.7.42.md FEATURE_186](features/v0.7.42.md#feature_186-sdk-embedder-surface-closure--kodax-space-gap-list--mcp-popout) — gap-by-gap landing matrix
+- [docs/ADR.md ADR-058](ADR.md#adr-058-model-agent-wait-is-mailbox-control-not-event-telemetry) — mailbox control versus Actor telemetry
+- [docs/features/v0.7.42.md FEATURE_186](features/v0.7.42.md#feature_186-sdk-embedder-surface-closure--kodax-space-gap-list--mcp-popout) — gap-by-gap landing matrix
 - [docs/features/v0.7.74.md](features/v0.7.74.md) — v0.7.74 release-candidate design and verification record
 - [docs/features/v0.7.75.md](features/v0.7.75.md) — v0.7.75 Windows GUI and Sidecar/Runtime stabilization candidate
+- [docs/features/v0.7.77.md](features/v0.7.77.md) — v0.7.77 adaptive-quality, governed-memory, and release-hardening record

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodax-ai/kodax",
-  "version": "0.7.76",
+  "version": "0.7.77",
   "description": "KodaX lightweight coding agent - TypeScript implementation with 16 built-in LLM provider aliases, published as a Node-free single-file CLI and SDK",
   "type": "module",
   "private": false,
@@ -79,6 +79,7 @@
     "dev:mem-snapshot": "node scripts/mem-diag-launch.cjs 2",
     "probe:reasoning": "tsx scripts/probe-reasoning.ts",
     "probe:max-tokens": "node scripts/probe-max-tokens.mjs",
+    "probe:prompt-cache": "node scripts/probe-prompt-cache.mjs",
     "start": "node --max-old-space-size=4096 --require ./scripts/production-env.cjs dist/kodax_bootstrap.js",
     "build:binary": "node scripts/build-binary.mjs",
     "build:binary:all": "node scripts/build-binary.mjs --all",

package/scripts/kodax-bin.cjs

@@ -1,29 +1,29 @@
 #!/usr/bin/env node
-/**
- * KodaX bin entry — CJS shim.
- *
- * Purpose: set NODE_ENV=production BEFORE any ESM module is evaluated.
- * Background: when users invoke `kodax` via `npm link` / global install,
- * node runs this bin directly without the --require preload used by
- * `npm run dev` / `npm run start`. ESM static imports are hoisted and
- * evaluated before module-body code runs, so setting NODE_ENV inside
- * `src/kodax_cli.ts` is too late — React would already have loaded its
- * development reconciler, leaking ~100 MB/turn of profiling objects.
- *
- * This CJS file runs synchronously first, requires the env preload,
- * then dynamic-imports the lightweight compiled bootstrap.
- *
- * Opt back into development by setting KODAX_DEV=1.
- */
-'use strict';
-
-require('./production-env.cjs');
-
-import('../dist/kodax_bootstrap.js').then(
-  ({ runKodaXBootstrapAsEntry }) => runKodaXBootstrapAsEntry(),
-).catch((err) => {
-  // Surface unexpected errors with a full stack — this path should be rare.
-  // eslint-disable-next-line no-console
-  console.error(err);
-  process.exit(1);
-});
+/**
+ * KodaX bin entry — CJS shim.
+ *
+ * Purpose: set NODE_ENV=production BEFORE any ESM module is evaluated.
+ * Background: when users invoke `kodax` via `npm link` / global install,
+ * node runs this bin directly without the --require preload used by
+ * `npm run dev` / `npm run start`. ESM static imports are hoisted and
+ * evaluated before module-body code runs, so setting NODE_ENV inside
+ * `src/kodax_cli.ts` is too late — React would already have loaded its
+ * development reconciler, leaking ~100 MB/turn of profiling objects.
+ *
+ * This CJS file runs synchronously first, requires the env preload,
+ * then dynamic-imports the lightweight compiled bootstrap.
+ *
+ * Opt back into development by setting KODAX_DEV=1.
+ */
+'use strict';
+
+require('./production-env.cjs');
+
+import('../dist/kodax_bootstrap.js').then(
+  ({ runKodaXBootstrapAsEntry }) => runKodaXBootstrapAsEntry(),
+).catch((err) => {
+  // Surface unexpected errors with a full stack — this path should be rare.
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});

package/scripts/production-env.cjs

@@ -1,25 +1,25 @@
-/**
- * Preload script — must execute before any ESM module evaluation.
- * Loaded via: node --require ./scripts/production-env.cjs ...
- *
- * React ships two runtimes: development (with PerformanceMeasure tracking,
- * prop diff strings, component profiling) and production (zero overhead).
- * Development mode creates ~100 MB/turn of profiling objects that are never
- * released, causing inevitable OOM after 10-20 conversation rounds.
- *
- * Default to production. Set KODAX_DEV=1 to opt-in to development mode.
- */
-'use strict';
-
-if (!process.env.NODE_ENV) {
-  process.env.NODE_ENV = process.env.KODAX_DEV === '1' ? 'development' : 'production';
-}
-
-// Bootstrap hardening must run before the first application ESM import.
-// ELECTRON_RUN_AS_NODE is a one-shot exec-boundary switch and is never kept.
-delete process.env.ELECTRON_RUN_AS_NODE;
-if (process.env.KODAX_DISABLE_HARDENING !== '1') {
-  delete process.env.LD_PRELOAD;
-  delete process.env.DYLD_INSERT_LIBRARIES;
-  delete process.env.DYLD_LIBRARY_PATH;
-}
+/**
+ * Preload script — must execute before any ESM module evaluation.
+ * Loaded via: node --require ./scripts/production-env.cjs ...
+ *
+ * React ships two runtimes: development (with PerformanceMeasure tracking,
+ * prop diff strings, component profiling) and production (zero overhead).
+ * Development mode creates ~100 MB/turn of profiling objects that are never
+ * released, causing inevitable OOM after 10-20 conversation rounds.
+ *
+ * Default to production. Set KODAX_DEV=1 to opt-in to development mode.
+ */
+'use strict';
+
+if (!process.env.NODE_ENV) {
+  process.env.NODE_ENV = process.env.KODAX_DEV === '1' ? 'development' : 'production';
+}
+
+// Bootstrap hardening must run before the first application ESM import.
+// ELECTRON_RUN_AS_NODE is a one-shot exec-boundary switch and is never kept.
+delete process.env.ELECTRON_RUN_AS_NODE;
+if (process.env.KODAX_DISABLE_HARDENING !== '1') {
+  delete process.env.LD_PRELOAD;
+  delete process.env.DYLD_INSERT_LIBRARIES;
+  delete process.env.DYLD_LIBRARY_PATH;
+}

package/dist/chunks/agent-7X5CFET2.js

@@ -1,2 +0,0 @@
-// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{Ea as i,Ka as j,da as d,ea as e,fa as f,j as c,ua as g,wa as h}from"./chunk-OD6LVXU6.js";import"./chunk-IDCGNQ4H.js";import"./chunk-PXKSE54E.js";import"./chunk-7FJNLJLF.js";import"./chunk-D3T24FJW.js";import{sb as a,tb as b}from"./chunk-VWSLC2WO.js";import"./chunk-Y3AMP22L.js";import"./chunk-COQYLD4U.js";import"./chunk-EI4JBQKL.js";import"./chunk-ONUPGMER.js";export{e as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,f as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,c as emitResilienceDebug,d as estimateProviderPayloadBytes,j as runKodaX,i as saveSessionSnapshot,a as validateAndFixToolHistory};

package/dist/chunks/argument-completer-3NHIKB4N.js

@@ -1,2 +0,0 @@
-// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{Ja as a,Ka as b}from"./chunk-HS3XHF3R.js";import"./chunk-4PWPNCNK.js";import"./chunk-RDXRM3UI.js";import"./chunk-TGMBHGZO.js";import"./chunk-SMT2JSM3.js";import"./chunk-OSF3H4RR.js";import"./chunk-OD6LVXU6.js";import"./chunk-IDCGNQ4H.js";import"./chunk-PXKSE54E.js";import"./chunk-7FJNLJLF.js";import"./chunk-D3T24FJW.js";import"./chunk-VWSLC2WO.js";import"./chunk-Y3AMP22L.js";import"./chunk-COQYLD4U.js";import"./chunk-EI4JBQKL.js";import"./chunk-ONUPGMER.js";export{a as ArgumentCompleter,b as createArgumentCompleter};