@kodax-ai/kodax 0.7.66 → 0.7.68

package/CHANGELOG.md

@@ -4,9 +4,186 @@ All notable changes to this project will be documented in this file.
 
 > Full history for versions prior to v0.7.0: [CHANGELOG_ARCHIVE.md](docs/CHANGELOG_ARCHIVE.md)
 
-## [Unreleased]
-
-## [0.7.66] - 2026-07-10
+## [Unreleased]
+
+## [0.7.68] - 2026-07-12
+
+> Scope note: this release delivers **FEATURE_260**, the KodaX Memory Agent,
+> as a thin experimental SDK and governed runtime extension over the existing
+> F228 Memory Control Plane. It does not add a second memory database, a
+> resident specialist agent, filesystem memory actions, or online self-modification.
+
+### Added
+
+- **Thin experimental Memory Agent SDK.** Added
+  `@kodax-ai/agent/experimental-memory` and the root `/experimental-memory`
+  entry with scoped `MemorySession` lifecycle, zero-wait passive recall,
+  read-only deliberate `query()`, bounded observations, and episode outcomes.
+- **Deliberate governed recall for the Action LLM.** A session-bound
+  `memory_recall` tool exposes only one `need` field, returns prompt-safe
+  low-authority evidence from the same F228 plane, and keeps identity, scope,
+  revision, and sequence outside model input.
+- **Auditable memory decisions and outcomes.** Trace-only
+  `MemoryDecisionReceipt` records candidate/selected/injected refs and policy
+  version; accepted Outcome Digests can conservatively link influence without
+  storing hidden reasoning or creating a second event store.
+- **Bounded episode review and promotion.** Timed-out review work persists in a
+  scoped inbox for bounded next-session drain and revalidation. Promotion now
+  consults compatible claims before choosing create, evidence update,
+  condition refinement, conflict, no-action, reject, or quarantine.
+
+### Changed
+
+- **Memory applicability is exact and fail-closed.** Tenant, user, agent,
+  workspace, project, and branch identity participate in deterministic scope
+  checks; sibling/cross-user/cross-tenant fallback is prohibited.
+- **Memory policy is source-versioned and cache-safe.** `f260-v0.7.68.2`
+  binds production reminder rules, evidence rendering, and deliberate-recall
+  tool bytes. Passive reminders only affect the dynamic suffix; deliberate
+  queries add a normal tool-call/result tail while preserving earlier provider
+  cache bytes.
+- **Safety-critical boundaries remain deterministic.** Secret filtering,
+  memory-file mutation guards, poisoning/source-evidence checks, and governed
+  proposal/preview/fingerprint/apply remain zero-violation code gates rather
+  than probabilistic LLM recall thresholds.
+- **Self-knowledge follows the v0.7.68 capability surface.** `kodax_manual`
+  now has a dedicated governed-memory topic, names all 43 built-in slash
+  commands under a two-way drift guard, and documents the current 10 SDK
+  subpaths plus Runtime and `/experimental-memory` ownership boundaries.
+
+### Fixed
+
+- **Post-review Memory Agent release hardening.** Repository identity now strips
+  Git remote userinfo/query credentials before scoped or legacy persistence;
+  managed-path guards are Windows-case-safe, protect governance sidecars, and
+  fail closed for non-read-only shell access to addressed memory roots. Episode
+  reviews use atomic processing claims with stale recovery, while proposal and
+  lifecycle stores serialize concurrent read-modify-write updates. Eval manifest
+  schema v2 binds untracked file bytes in addition to the tracked patch, corrupt
+  raw JSON fails loudly, and summary review state points to the separate
+  main-session review artifact instead of remaining permanently pending.
+- **Runtime daemon state replacement is atomic.** Daemon lifecycle updates now
+  stage and rename `daemon.json` instead of truncating it in place, preventing
+  shutdown polling from mistaking a partial write for completed cleanup and
+  leaving an orphaned `stopping` process under full-suite load.
+
+### Performance
+
+- **The preregistered v2 memory-routing panel passes all release gates.** On
+  `ark/v4flash`, general immediate recall passed 59/60 (98.3%), high-value
+  recall 40/40, must-silent 200/200 (Wilson lower 98.1%), paired routing lift
+  was +73.3 percentage points with zero control regression, and bounded
+  two-decision recovery passed 20/20. The 520-cell panel represented 782,721
+  tokens and an estimated $0.004447 against the $0.02 cap. Main-session blinded
+  review recommends ship for routing value while documenting that the panel is
+  not an end-to-end task-completion claim.
+
+## [0.7.67] - 2026-07-11
+
+> Scope note: a stabilization and agent-efficiency release. **FEATURE_258**
+> adds the protocol-neutral external-agent executor plane, **FEATURE_259**
+> makes workflow/review orchestration more focused and cost-disciplined, and
+> the bounded corrective **FEATURE_261** delivers searchable session resume
+> plus safe ACP-session cleanup. GitHub source/binary release work is included;
+> npm publication remains a separate operator step.
+
+### Added
+
+- **External Agent Executor Plane and dispatchable catalog.** Host-injected
+  executors now share a protocol-neutral registration/catalog/task contract,
+  redacted policy-filtered discovery, durable task ledger, recovery, and a
+  reference executor. Worker tools, Workflow, Embedded Runtime, and daemon
+  clients discover and dispatch the same canonical agent IDs.
+- **External-agent SDK and daemon surfaces.** Runtime sessions expose catalog,
+  start/continue/cancel/reconcile, event, and task-result operations with
+  versioned schemas, configuration revisions, credential-presence checks, and
+  public in-process daemon-factory bootstrap support.
+- **Focused scoped-review workflow.** `/review --workflow` now uses immutable
+  review packets, one primary per scope, an additional authoritative primary
+  only for risk-flagged packets, batched fresh verification for candidate
+  findings, stable finding IDs, capable synthesis, and an audit artifact.
+- **Explicit model-tier intent and route telemetry.** Workflow and substantive
+  child briefs carry focused scope/constraints/evidence/output fields plus
+  explicit `fast` / `balanced` / `deep` intent. Runtime reports the resolved
+  source, fallback, effort, usage, duration, packet-read topology, and token
+  coverage without fabricating missing external usage.
+- **Searchable session resume picker.** Running `kodax -r` without an ID now
+  opens an interactive TUI with incremental search, keyboard selection, title
+  completion, pagination, and the full selected session ID. An explicit value
+  resolves a complete ID first, then a unique exact title; duplicate titles
+  open a narrowed picker rather than silently selecting one.
+- **Session listing filters and cursors.** SessionManager, Runtime SDK, and
+  daemon protocol listings now accept an exact `surface` filter and an opaque
+  continuation `cursor`, applied before the requested page limit.
+
+### Changed
+
+- **Resident workflow context is smaller and discoverable.** The turn-resident
+  `run_workflow` hint stays below the deferred-tool budget while the full
+  authoring contract remains available through `tool_search`. Recorded
+  workflow-shaped plans start directly instead of being expanded into duplicate
+  todo/dispatch scaffolding.
+- **Review handoffs are structured and conservative.** Positive observations
+  are not findings; missing evidence remains `not-verifiable` rather than being
+  promoted into a defect; unreasoned severity overrides retain the original
+  severity instead of failing the review.
+- **Eval execution is value-driven and bounded.** Main-session evidence review
+  determines whether a candidate has material value over baseline; executor
+  aliases are not reused as judge models. Raw reuse, per-call/round/token/cost
+  caps, one bounded structured repair, and provider/model concurrency lanes
+  prevent runaway panels.
+- **SDK embedder documentation matches the v0.7.67 public surface.** The guide
+  now covers external-agent owner/consumer setup and safety boundaries, Runtime
+  registration/catalog/task services, exact-surface session pagination,
+  run-scoped workflow tiers, live route facts, and durable efficiency reports;
+  the English/Chinese subpath tables reflect all 10 published SDK entries.
+
+### Fixed
+
+- **Restricted Workflow scripts preserve the public Agent routing contract.**
+  `phase` and FEATURE_258 `target` values now cross the script host boundary
+  with fail-loud validation, so generated/saved workflows can route the same
+  canonical external Agent IDs as direct Workflow and Worker dispatch.
+- **Executor-plane shutdown is terminal and waiter-safe.** Closing the plane is
+  idempotent, rejects pending task waits, and prevents later registration,
+  catalog, or task operations from recreating executors after owner shutdown.
+- **Review/eval trust boundaries fail loudly without replacing real results.**
+  Built-in scoped-review outputs are validated against their declared schemas;
+  local ledger mirror failures retain the authoritative child result/error;
+  Feature 259 baseline reconstruction now requires every exact rewrite and no
+  longer leaks candidate-only briefing fields into the baseline.
+- **Runtime tests no longer leave detached Node processes behind.** The config
+  suite explicitly shuts down its auto-started daemon owner before deleting
+  temporary state, and long-running process fixtures self-exit if an abnormal
+  test-runner termination prevents normal managed cleanup.
+- **External tasks keep identity and terminal state across failures.** A remote
+  start followed by ledger failure preserves its executor reference as
+  `unknown`; in-flight tasks retain immutable executor bindings across catalog
+  updates; task-level mutation queues prevent late callbacks from overwriting a
+  terminal snapshot; Workflow external waits honor `timeoutMs`.
+- **External task safety and policy boundaries fail closed.** Executor
+  availability, health, capability, concurrency, credential presence,
+  configuration revision, target side effects, and read-only intent are checked
+  before start without exposing secret values.
+- **ACP tests no longer pollute real user sessions.** ACP harnesses now use an
+  isolated temporary runtime home and session store, with a guard that rejects
+  paths under the real user home. ACP sessions remain provisional until the
+  first valid prompt instead of persisting an empty `ACP Session` during
+  protocol setup.
+- **Empty ACP pollution can be audited and recovered safely.**
+  `kodax -s cleanup-acp` previews only strict empty ACP matches; explicit
+  `--apply-session-cleanup` archives them reversibly instead of deleting data.
+
+### Performance
+
+- **Feature 259 controlled comparison validates the review optimization.** The
+  proposed topology passed 8/8 Layer-3 oracle cells versus 6/8 baseline, reduced
+  total model tokens 16.9% and output tokens 49.1%, and on standard reviews
+  reduced median tokens 57.2%, primary starts 75%, and duplicate packet reads
+  83.3%. High-risk multi-area reviews intentionally spend more calls for fresh
+  verification and explicit packet coverage.
+
+## [0.7.66] - 2026-07-10
 
 > Scope note: the runtime migration was developed across the v0.7.64-v0.7.66
 > planning slots and is released as one v0.7.66 cut; v0.7.64 and v0.7.65 were

package/README.md

@@ -319,8 +319,14 @@ inline/Worker ownership, but only detaches one daemon client. Contradictory
 isolation options fail instead of silently selecting a weaker mode. Worker
 isolation is a V8 fault boundary, not a security sandbox.
 
+Because a daemon is intentionally persistent, tests that auto-start one must
+also run `kodax daemon stop --home <dir> --profile <name>` (or send authenticated
+`runtime.shutdown`) before deleting their temporary home. A remaining Node
+process is not safe to kill by name alone; verify its command line and owner.
+
 ```bash
 kodax daemon start
+kodax daemon stop --profile default
 kodax --runtime-mode daemon
 kodax -p "Review this repository" --runtime-mode daemon
 ```
@@ -373,7 +379,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## Architecture
 
-KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 9 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
+KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 10 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`, `/experimental-memory`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
 
 ```
 KodaX/
@@ -399,7 +405,7 @@ KodaX/
 │
 ├── src/                     # CLI entry + SDK subpath entries
 │   ├── kodax_cli.ts         # Main CLI entry point (bin: `kodax`)
-│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime}
+│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,experimental-memory}
 │
 └── package.json             # Root workspace config; release.mjs rewrites name + injects subpath exports
 ```
@@ -448,20 +454,22 @@ Source-side workspace package names (`@kodax-ai/*`). npm consumers install the s
 KodaX has two layers that consumers should understand separately:
 
 - **Source-side**: 4 workspace packages above (what developers see when reading the repo).
-- **npm-published**: a single bundled package `@kodax-ai/kodax` with 9 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
+- **npm-published**: a single bundled package `@kodax-ai/kodax` with 10 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
   - **Full-package subpaths** (`/agent`, `/llm`, `/coding`, `/repl`) — each one maps 1:1 to a source workspace and exposes its complete public API.
-  - **Narrow-subset subpaths** (`/media`, `/skills`, `/mcp`, `/session`) — each one exposes only a focused capability slice carved out of `/agent` or `/repl`. This lets consumers who only need (say) the Skills system import a much smaller surface without pulling in the full agent framework.
+  - **Narrow-subset subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/experimental-memory`) — each one exposes only a focused capability slice carved out of `/agent` or `/repl`. `/experimental-memory` is intentionally unstable and opt-in; the others are stable focused surfaces.
 
 | Source package | npm subpath | Type | What you get | Example consumer |
 |---|---|---|---|---|
-| `packages/llm`    | `@kodax-ai/kodax/llm`     | Full package | 15-alias LLM abstraction (77 exports) | Standalone LLM clients |
-| `packages/agent`  | `@kodax-ai/kodax/agent`   | Full package | Runner / fan-out / session-lineage / capabilities / tracing (202 exports) | Custom agent frameworks |
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | Full package | 15-alias LLM abstraction (108 exports) | Standalone LLM clients |
+| `packages/agent`  | `@kodax-ai/kodax/agent`   | Full package | Runner / fan-out / external-agent plane / session-lineage / capabilities / tracing (331 exports) | Custom agent frameworks |
 | `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` / ... (11 exports = pre-v0.7.43 `@kodax-ai/mcp` complete API) | MCP server hosts |
-| `packages/coding` | `@kodax-ai/kodax/coding`  | Full package | Coding agent + 50+ tools + repo-intelligence (342 exports) | Build a Claude Code-shape product |
-| `packages/repl`   | `@kodax-ai/kodax/repl`    | Full package | Ink TUI + permission modes + commands (193 exports) | Terminal-UI consumers |
-| `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... | IDE plugins and desktop hosts reading session history |
-| `src`             | `@kodax-ai/kodax/runtime` | Host API | Embedded/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics, daemon protocol schema | SDK hosts, Space/IDE clients, daemon clients |
+| `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/coding` | `@kodax-ai/kodax/coding`  | Full package | Coding agent + 50+ tools + repo-intelligence (505 exports) | Build a Claude Code-shape product |
+| `packages/repl`   | `@kodax-ai/kodax/repl`    | Full package | Ink TUI + permission modes + commands (217 exports) | Terminal-UI consumers |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... (17 exports) | IDE plugins and desktop hosts reading session history |
+| `src`             | `@kodax-ai/kodax/runtime` | Host API | Embedded/Worker/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports) | SDK hosts, Space/IDE clients, daemon clients |
 
 **Rule of thumb**: if you need Runner / Agent / fan-out, import from `/agent`. If you only need skills or mcp APIs, import from `/skills` or `/mcp` to get a smaller bundle. The narrow subsets are subsets of the full packages — they do **not** expose extra symbols.
 
@@ -479,6 +487,14 @@ KodaX has two layers that consumers should understand separately:
 
 **Tool-Output Compression + Workflow Quality Preflight (FEATURE_251 + FEATURE_252, v0.7.61)**: KodaX's own `bash` tool now compresses noisy command output **inside the tool**, so a big `git diff`, test run, package install, or `docker build` no longer spends thousands of context tokens — command-aware filters (git/test/lint/JSON + a declarative package/docker/infra long-tail) summarize the stdout/stderr body while the `Command:`/`Exit:` header stays verbatim and every lossy summary keeps a raw-recovery path; isolated measurements show ~66–99% body-token reduction. Alongside it, inline `run_workflow` gains a deterministic pre-start quality lint that hard-fails weak-model authoring contract bugs (unawaited workflow-command used as a boolean, top-level access of `result.structured` fields, literal agent fanout above manifest/host caps) before a run starts. Both are deterministic (no prompt change). See [docs/features/v0.7.61.md](docs/features/v0.7.61.md) and [docs/ADR.md ADR-050](docs/ADR.md).
 
+**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).
+
+**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).
+
+**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).
+
+**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).
+
 ---
 
 ## Features
@@ -588,6 +604,7 @@ For smaller surface and tree-shake-friendly imports, the SDK is also exposed via
 import { Runner } from '@kodax-ai/kodax/agent';                // agent runtime
 import { getProvider } from '@kodax-ai/kodax/llm';              // LLM abstraction (15 aliases)
 import { runKodaX } from '@kodax-ai/kodax/coding';              // coding tools + prompts
+import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input artifacts
 import { SkillRegistry } from '@kodax-ai/kodax/skills';         // zero-dep skill loader
 import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL config / session helpers
 import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager (v0.7.42)
@@ -595,7 +612,12 @@ import { listSessions } from '@kodax-ai/kodax/session';         // session histo
 import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/daemon runtime API
 ```
 
-All 10 SDK entries (root + 9 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+All 11 SDK entries (root + 10 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+
+For the complete host-facing contract — including embedded/Worker/daemon ownership,
+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).
 
 > **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.
 
@@ -653,10 +675,21 @@ kodax --session my-project "Summarize it"
 kodax --session my-project "How should I fix the first issue?"
 
 # Session management
-kodax --session list
-kodax --session resume "continue"
+kodax -r                    # Search, page, and select a non-empty session
+kodax -r <session-id>       # Resume a known session directly
+kodax -r "Review runtime"   # Resume a unique exact title; duplicates open the picker
+kodax --session list        # List up to 50 non-empty sessions
+kodax --session cleanup-acp # Preview strictly matched empty ACP-test pollution
 ```
 
+Bare `-r` opens an interactive picker with incremental search, arrow/PageUp/PageDown
+navigation, Tab completion, full selected-session ID display, and Enter-to-resume.
+An explicit value checks the complete session ID first, then an exact
+case-insensitive title; duplicate titles open a narrowed picker instead of
+silently choosing one. Cleanup is preview-only unless
+`--apply-session-cleanup` is also provided; matching sessions are archived rather
+than permanently deleted.
+
 ### Session Patterns
 
 ```bash
@@ -691,7 +724,7 @@ kodax                    Start the interactive REPL
 -h, --help [topic]   Show help or topic help
 -p, --print <text>   Run a single task and exit
 -c, --continue       Continue the most recent conversation in this directory
--r, --resume [id]    Resume a session by ID, or the latest session
+-r, --resume [value] Resume by ID/exact title, or open the searchable picker
 -m, --provider       Provider to use
 --model <name>       Override the model
 --reasoning <mode>   off | auto | quick | balanced | deep
@@ -882,7 +915,7 @@ await runKodaX({
 
 ## SDK Usage
 
-KodaX ships as a single npm package `@kodax-ai/kodax` with 9 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime`). Each subpath is tree-shake-friendly so consumers pull only what they need:
+KodaX ships as a single npm package `@kodax-ai/kodax` with 10 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime` + v0.7.68 `/experimental-memory`). Each subpath is tree-shake-friendly so consumers pull only what they need:
 
 ```bash
 npm install @kodax-ai/kodax
@@ -899,6 +932,7 @@ import { SkillRegistry } from '@kodax-ai/kodax/skills';           // zero-dep sk
 import { createMcpManager } from '@kodax-ai/kodax/mcp';           // MCP popout manager (v0.7.42)
 import { listSessions } from '@kodax-ai/kodax/session';           // session history helpers
 import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';     // embedded/daemon runtime API
+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).
@@ -1048,6 +1082,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 |
 
 ---
 

package/README_CN.md

@@ -213,9 +213,13 @@ import { SkillRegistry } from '@kodax-ai/kodax/skills';         // 零依赖 ski
 import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL 配置 / session 工具
 import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager（v0.7.42 起）
 import { listSessions } from '@kodax-ai/kodax/session';         // session 历史工具
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/Worker/daemon 宿主 API
+import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in 实验性记忆 SDK
 ```
 
-9 个 SDK 入口（root + 8 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+11 个 SDK 入口（root + 10 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+
+完整的宿主集成契约——包括 embedded/Worker/daemon 所有权、外部 Agent 注册与任务控制、session cursor 分页、workflow 模型分层和效率遥测——见 [SDK Embedder Integration Guide](docs/SDK_EMBEDDER_GUIDE.md)。
 
 > **SDK 是 ESM-only**。在 CommonJS 上下文（Electron main 进程、传统 Webpack CJS bundle、`require()` 调用方）必须用 `await import('@kodax-ai/kodax/...')` 代替 `require()`。详见 [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles)，含 Electron main 完整 recipe + 为什么大多数 subpath 物理上无法做 dual ESM/CJS bundle。
 
@@ -366,8 +370,13 @@ daemon 形态使用独立进程并允许多个客户端共享。`runtime.close()
 私有 inline/Worker Runtime，但对 daemon 只断开当前客户端。矛盾的隔离参数
 会直接报错，不会静默降级。Worker 是 V8 故障隔离边界，不是安全沙箱。
 
+daemon 按设计会持续驻留。测试若自动启动 daemon，删除临时 home 前还必须执行
+`kodax daemon stop --home <目录> --profile <名称>`（或发送已认证的
+`runtime.shutdown`）。不要按进程名批量结束 Node；应先核验命令行和父进程归属。
+
 ```bash
 kodax daemon start
+kodax daemon stop --profile default
 kodax --runtime-mode daemon
 kodax -p "检查这个仓库" --runtime-mode daemon
 ```
@@ -521,7 +530,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## 仓库结构
 
-KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 8 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`；ADR-024 + ADR-032 + ADR-038）。核心包：
+KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 10 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`、`/runtime`、`/experimental-memory`；ADR-024 + ADR-032 + ADR-038）。核心包：
 
 | Workspace 包 | 作用 | 主要依赖 |
 |----|------|---------|
@@ -530,26 +539,29 @@ KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 works
 | `@kodax-ai/coding` | Coding Agent:50+ 工具(含 `dispatch_child_task`/`send_message`/`task_stop`)、role prompts、agent loop、auto-continue + repo-intelligence protocol(v0.7.43 inline) | `@kodax-ai/llm`, `@kodax-ai/agent` |
 | `@kodax-ai/repl` | 完整交互式终端 UI（Ink / React、权限模式、命令系统、流式渲染） | `@kodax-ai/coding`, `ink`, `react` |
 
-根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
+根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session,runtime,experimental-memory}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
 
 ### 源码层 vs npm 发布层
 
 KodaX 有两层结构，SDK 用户需要分开理解：
 
 - **源码层**：上面 4 个 workspace 包（开发者读代码时看到的物理结构）。
-- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 8 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
+- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 10 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
   - **完整包 subpath**（`/agent`、`/llm`、`/coding`、`/repl`）—— 每个 1:1 对应一个源码包，暴露完整公开 API。
-  - **窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`）—— 从 `/agent` 或 `/repl` 切出聚焦的能力子集，让"只用 Skills/MCP/会话管理"的消费者引入更小的依赖。
+  - **窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`、`/experimental-memory`）—— 从 `/agent` 或 `/repl` 切出聚焦能力；`/experimental-memory` 明确为 opt-in 不稳定接口。
 
 | 源码包 | npm subpath | 类型 | 内容 | 典型消费者 |
 |---|---|---|---|---|
-| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 15-alias LLM 抽象 (77 exports) | 独立 LLM 客户端 |
-| `packages/agent`  | `@kodax-ai/kodax/agent`   | 完整包 | Runner / fan-out / session-lineage / capabilities / tracing (202 exports) | 自定义 agent 框架 |
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 15-alias LLM 抽象 (108 exports) | 独立 LLM 客户端 |
+| `packages/agent`  | `@kodax-ai/kodax/agent`   | 完整包 | Runner / fan-out / 外部 Agent plane / session-lineage / capabilities / tracing (331 exports) | 自定义 agent 框架 |
 | `packages/agent`  | `@kodax-ai/kodax/skills`  | **窄子集** | 仅 Skills 系统 —— `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` 等 (26 exports = v0.7.43 之前 `@kodax-ai/skills` 完整 API) | Skill 加载器、IDE 插件 |
-| `packages/agent`  | `@kodax-ai/kodax/mcp`     | **窄子集** | 仅 MCP —— `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` 等 (11 exports = v0.7.43 之前 `@kodax-ai/mcp` 完整 API) | MCP server 宿主 |
-| `packages/coding` | `@kodax-ai/kodax/coding`  | 完整包 | Coding agent + 50+ 工具 + repo-intelligence (342 exports) | 构建 Claude Code 形态产品 |
-| `packages/repl`   | `@kodax-ai/kodax/repl`    | 完整包 | Ink TUI + 权限模式 + 命令系统 (193 exports) | 终端 UI 消费者 |
-| `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` 等 | 读取 session 历史的 IDE 插件和桌面宿主 |
+| `packages/agent`  | `@kodax-ai/kodax/mcp`     | **窄子集** | 仅 MCP —— `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` 等 (23 exports) | MCP server 宿主 |
+| `packages/agent`  | `@kodax-ai/kodax/media`   | **窄子集** | 结构化图片/文件/视频输入 artifact helpers (22 exports) | 桌面宿主、多模态客户端 |
+| `packages/agent`  | `@kodax-ai/kodax/experimental-memory` | **实验性子集** | F228-backed `MemoryAgent` / `MemorySession` scope、recall、query、observation、outcome 契约 | 显式评估 FEATURE_260 的 SDK 宿主 |
+| `packages/coding` | `@kodax-ai/kodax/coding`  | 完整包 | Coding agent + 50+ 工具 + repo-intelligence (505 exports) | 构建 Claude Code 形态产品 |
+| `packages/repl`   | `@kodax-ai/kodax/repl`    | 完整包 | Ink TUI + 权限模式 + 命令系统 (217 exports) | 终端 UI 消费者 |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` 等 (17 exports) | 读取 session 历史的 IDE 插件和桌面宿主 |
+| `src`             | `@kodax-ai/kodax/runtime` | 宿主 API | Embedded/Worker/daemon facade，含 sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/外部 Agent 和 daemon schema (10 exports) | SDK 宿主、Space/IDE、daemon client |
 
 **经验法则**：需要 Runner / Agent / fan-out 时从 `/agent` 引入；只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入，bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
 
@@ -557,6 +569,14 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 
 **宿主读持久化历史（FEATURE_230 + FEATURE_234，v0.7.51；v0.7.63 hardening）**：面向「宿主读持久化状态」的 additive 闭环。**持久化工具记录回放**——resume 的会话现在会回放助手用过的工具卡片，而不是退化成纯文本。`messages` / `lineage` 仍是 canonical；`SessionData.uiHistory` 成为有界、脱敏、仅 terminal 状态的回放缓存。SDK transcript 契约明确化：`loadSession()` = 活动 model context，`loadFullTranscript()` = 带结构化条目的追加序 host scrollback（`message` / `compaction` / `branch_summary` / `rewind_marker` / `client_notice` / `task_result`）并带 clone provenance（`logicalId` / `sourceEntryId`），`uiHistory` = 可选回放缓存，工具卡片始终可从 canonical messages 重建。宿主可用 `appendClientNotice()` 持久化本地 slash 输出且不进入模型上下文；workflow/child 完成结果通过结构化 `taskResults[]` 暴露，不再要求解析 `<task-completed>` 文本。`rewind_marker` 只用于 host scrollback 审计，不进入 model-context messages。**Workflow run 宿主归属**——`WorkflowProcessTrackerOptions` / `WorkflowProcessSnapshot` 新增 host-owned 不透明 `hostMetadata?: Record<string, string>`，SDK 存储、持久化进 `run.json`、回读回显（含进程重启后）但不解释其含义，让宿主零侧表把 run 归回发起它的 session/surface。未 stamp 的旧 run 诚实回显 `hostMetadata === undefined`。详见 [docs/features/v0.7.51.md](docs/features/v0.7.51.md)。
 
+**会话恢复与 ACP 污染修复（FEATURE_261，v0.7.67）**：直接运行 `kodax -r` 会进入可搜索、上下选择、Tab 补全和翻页的交互式会话选择器，并显示当前选中项的完整 session ID；`kodax -r <值>` 优先按完整 ID 恢复，ID 不存在时再按忽略大小写的完整标题匹配。标题唯一则直接恢复，同名标题则进入只包含候选项的选择器，绝不静默选第一条。`listSessions()` / Runtime / daemon 会话列表新增 `surface` 精确过滤和不透明 `cursor` 分页。ACP session 改为收到首个有效 prompt 后才持久化，ACP 测试强制使用临时 runtime home，避免测试记录写入真实 `~/.kodax/sessions`。`kodax -s cleanup-acp` 只预览严格匹配的空 ACP 污染记录；仅显式追加 `--apply-session-cleanup` 时才归档，不做永久删除。
+
+**实验性 Memory Agent SDK（FEATURE_260，v0.7.68）**：`/experimental-memory` 暴露基于既有 F228 治理平面的薄 `MemoryAgent` 与 scoped `MemorySession`。被动 recall 零等待，`query()` 只读且由主 Action LLM 主动选择；持久化仍必须经过 proposal/preview/fingerprint/apply。召回内容保持低权限，安全与 scope 边界仍由确定性代码门禁承担。直接 session 示例与宿主边界见 [SDK Embedder Guide §21](docs/SDK_EMBEDDER_GUIDE.md#21-experimental-governed-memory--experimental-memory-feature_260-v0768)。
+
+**外部 Agent SDK plane（FEATURE_258，v0.7.67）**：`/agent` 导出协议中立的 executor、registration、policy、credential broker、artifact policy、catalog 和 durable task 契约；`/runtime` 通过 `admin.agentRegistrations`、`agents`、`agentTasks` 向 embedded 与 daemon client 提供同一组 DTO API。Executor factory 是宿主函数，只能装入 inline owner，或在创建新的 in-process daemon owner 时装入；不能通过既有 daemon 连接或 Runtime Worker 边界注入。Plane 关闭后是终态：未完成的 wait 和后续所有服务调用都会拒绝；受限 Workflow 脚本会完整校验并传递 `phase` 与外部 `target`。完整所有权、注册、preflight、启动/等待/继续/取消/对账和安全边界见 [SDK Embedder Guide §18](docs/SDK_EMBEDDER_GUIDE.md#18-external-agent-executor-plane-feature_258-v0767)。
+
+**成本受控 Workflow SDK（FEATURE_259，v0.7.67）**：SDK 调用方用 run-scoped `modelTiers` 与 `workflow.maxConcurrency` 配置路由和并发，workflow 作者只表达 `fast` / `balanced` / `deep` 语义意图。terminal workflow event 回显 tier/source/fallback/usage/duration，持久化 `run.json.efficiencyReport` 给出 token coverage、role/tier 启动数、packet-read 拓扑、review wave 和 quality gate 结果。完整配置与遥测读取方式见 [SDK Embedder Guide §20](docs/SDK_EMBEDDER_GUIDE.md#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767)。
+
 **Inline workflow authoring（FEATURE_246，v0.7.58）**：AMA/AMAW 下 Worker 现在可通过 model-callable 的 `run_workflow` 工具在会话内直接编写并运行工作流——先用自己的工具 scout 代码库，再把具体发现烤进每个 child prompt，然后走**不变的** sandbox + 静态校验 + postcondition 验证流水线。它取代 context-blind 的 `sideQuery` generator 成为主交互路径（generator 仅作为显式 `/workflow create` 命令与无 investigating Worker 的 non-interactive/CI 主机的 fallback 保留）；新增结构化 child 输出（`outputSchema`）、无 barrier 的 `wf.pipeline` 分阶段原语、同会话 resume（`resumeFromRunId`）、嵌套 `wf.workflow(...)`，`/workflow create` 重定向到 Worker 的 scout-then-author；`run_workflow` 为 async / idle-yield，不阻塞当前轮。中立的 run-lifecycle manager（`createWorkflowRunManager`）已移入 `@kodax-ai/kodax/agent` 供非 coding SDK 宿主使用。详见 [docs/features/v0.7.58.md](docs/features/v0.7.58.md) 与 [docs/ADR.md](docs/ADR.md) ADR-044/046/047/048/049。
 
 **工作流激活分层（FEATURE_248 + FEATURE_249，v0.7.59）**：三种 agent 模式现在有一致的工作流姿态。**AMAW** 携带 mode-level 的 `ORCHESTRATION DEFAULT` 常驻指令（对齐参考实现的 "ultracode" 姿态）：实质性工作——多文件调查、设计决策、任何做错代价高的任务——默认编排多个交叉验证的 agent，并有 PLAN-TIME COMMITMENT 流程修正把 orchestrate-vs-solo 决策前置到第 0 轮。**AMA** 同样 host `run_workflow` 工具但没有常驻指令——当你用自然语言请求编排时才激活，绝不因复杂度独自触发。**SA** 保持单独作业。该指令通过 `amawOrchestrationAvailable` 关闭泄漏，因此 AMA 与 SA 的 prompt 保持逐字节一致。详见 [docs/features/v0.7.59.md](docs/features/v0.7.59.md)。
@@ -580,9 +600,9 @@ KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 │   └── repl/                # @kodax-ai/repl —— Ink TUI
 ├── src/
 │   ├── kodax_cli.ts         # CLI 主入口（bin: `kodax`）
-│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session}
+│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,experimental-memory}
 ├── scripts/
-│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 8 SDK subpath + chunks）
+│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 10 SDK subpath + chunks）
 │   ├── build-binary.mjs     # Bun --compile 单文件二进制打包
 │   └── release.mjs          # ADR-024 release-time pkg name/exports 注入
 └── .github/workflows/
@@ -676,6 +696,7 @@ KodaX 现在会把 Repo Intelligence 的本地缓存分成内置引擎 profile
 ## 文档
 
 - [README.md](README.md) - 英文版 README
+- [docs/SDK_EMBEDDER_GUIDE.md](docs/SDK_EMBEDDER_GUIDE.md) - SDK 宿主集成与 v0.7.68 公共 API 契约
 - [docs/release.md](docs/release.md) - 单文件二进制构建与发布流程
 - [docs/PRD.md](docs/PRD.md) - 产品需求
 - [docs/ADR.md](docs/ADR.md) - 架构决策

package/dist/chunks/agent-DATNZOBK.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{$ as g,I as c,J as d,K as e,L as f,aa as h,ta as i,za as j}from"./chunk-HLBHSA2B.js";import"./chunk-D6QVXQNI.js";import"./chunk-PEGSHZAA.js";import"./chunk-HFM2D5BP.js";import"./chunk-C4SBXBWH.js";import"./chunk-K2NCKRVY.js";import{kb as a,lb as b}from"./chunk-67XJ4YUA.js";import"./chunk-5GL55MOH.js";import"./chunk-PZTG2C33.js";import"./chunk-ONUPGMER.js";export{d as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,e as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,f as emitResilienceDebug,c as estimateProviderPayloadBytes,j as runKodaX,i as saveSessionSnapshot,a as validateAndFixToolHistory};

package/dist/chunks/argument-completer-X7MMM7Y6.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{Ba as a,Ca as b}from"./chunk-CTHUX5ZH.js";import"./chunk-OIELNE6Z.js";import"./chunk-TOGESFRN.js";import"./chunk-KIQRCGVR.js";import"./chunk-CC4BVVE7.js";import"./chunk-KGAI32VS.js";import"./chunk-HLBHSA2B.js";import"./chunk-D6QVXQNI.js";import"./chunk-PEGSHZAA.js";import"./chunk-HFM2D5BP.js";import"./chunk-C4SBXBWH.js";import"./chunk-K2NCKRVY.js";import"./chunk-67XJ4YUA.js";import"./chunk-5GL55MOH.js";import"./chunk-PZTG2C33.js";import"./chunk-ONUPGMER.js";export{a as ArgumentCompleter,b as createArgumentCompleter};