@kodax-ai/kodax 0.7.69 → 0.7.71

package/docs/SDK_EMBEDDER_GUIDE.md

@@ -1296,7 +1296,7 @@ import {
 ```ts
 interface KodaXModelCapabilities {
   provider: string;                 // 'anthropic' | 'kimi' | 'ark-coding' | <custom-name>
-  model: string;                    // model id (e.g. 'claude-sonnet-4-6', 'kimi-k2.6')
+  model: string;                    // model id (e.g. 'claude-sonnet-4-6', 'kimi-k2.7-code')
   displayName: string;              // human label — falls back to model id
   supportsThinking: boolean;        // native reasoning is available?
   reasoningCapability: 'native-budget' | 'native-effort' | 'native-toggle' | 'prompt-only' | 'none' | 'unknown'; // legacy mechanism label
@@ -1328,8 +1328,8 @@ for (const caps of listAllModelCapabilities()) {
 ```ts
 import { resolveModelCapabilities } from '@kodax-ai/kodax/llm';
 
-const caps = resolveModelCapabilities('kimi', 'kimi-k2.6');
-// => { contextWindow: 256_000, supportsThinking: true, reasoningProfile: { defaultEffort: 'high', ... }, ... }
+const caps = resolveModelCapabilities('kimi', 'kimi-k2.7-code');
+// => { contextWindow: 262_144, supportsThinking: true, reasoningProfile: { defaultEffort: 'high', ... }, ... }
 ```
 
 For picker/status UIs, use `reasoningProfile.supportedEfforts` and
@@ -1466,11 +1466,11 @@ and loaded into the in-memory `KODAX_PROVIDER_SNAPSHOTS` export. When upstream
 providers publish a new model or change a context-window cap, the JSON file is
 the patch site — the new value flows to runtime (via `buildProviderConfig`) AND
 to SDK consumers (via the getters) in a single edit. The current snapshot is
-dated 2026-06-14 and includes the GPT-5.4, Kimi K2.7 Code, GLM-5.2, MiniMax
+dated 2026-07-16 and includes the GPT-5.4, Kimi K2.7 Code / HighSpeed, GLM-5.2, MiniMax
 M3/M2.7, DeepSeek V4, and Doubao Seed 2.0 route refreshes where supported. The
 test suite at
 [`packages/llm/src/providers/model-capabilities.test.ts`](../packages/llm/src/providers/model-capabilities.test.ts)
-locks in specific values (e.g. kimi-k2.6 at 256K, deepseek-v4-pro at 1M)
+locks in specific values (e.g. the public Kimi lineup at 262,144 tokens, deepseek-v4-pro at 1M)
 so accidental drift is caught at PR time.
 
 The probe scripts that surveyed upstream APIs live at
@@ -1954,7 +1954,7 @@ Cli-bridge providers (`gemini-cli`, `codex-cli`) return their CLI binary's known
 
 ### Reference
 
-- Source: `packages/llm/src/providers/verify-credential.ts` (orchestrator + classifier) + `verify-credential.test.ts` (19 unit tests) + `verify-credential-integration.test.ts` (10 real-key tests, gated on `KODAX_INTEGRATION_TEST=1`).
+- Source: `packages/llm/src/providers/verify-credential.ts` (orchestrator + classifier) + `verify-credential.test.ts` (27 unit tests) + `verify-credential-integration.test.ts` (12 gated real-key/fake-key tests, enabled by `KODAX_INTEGRATION_TEST=1`).
 - Data: `packages/llm/src/providers/provider-capabilities.json` `verifyStrategy` field per provider.
 - Design notes + probe matrix: [docs/features/v0.7.45.md FEATURE_216](features/v0.7.45.md#feature_216-provider-credential-verification-api).
 
@@ -2348,7 +2348,7 @@ The important creation options are:
 | `worker.resourceLimits` | unset | Optional V8 heap/stack limits; requires `isolation: 'worker'`. |
 | `worker.shutdownTimeoutMs` | `2000` | Grace before the parent terminates the Runtime Worker. |
 | `requirements.hardDispose` | `false` | Rejects inline and daemon forms; prevents an accidental weaker ownership form. |
-| `homeDir` | OS user home | Root for `.kodax` config/state and default sessions. Use a private value in tests. |
+| `homeDir` | unset | When omitted, use the exact resolved `KODAX_HOME`. When set, this is the base directory that owns `.kodax`, with the same meaning as CLI `daemon --home`; daemon state/config live under `<homeDir>/.kodax`. |
 | `profile` | `'default'` | Daemon uniqueness and runtime configuration namespace. |
 | `sessionsDir` | `<homeDir>/.kodax/sessions` | Explicit session storage override. |
 | `daemonStartupTimeoutMs` | `60000` | Total cold-start/concurrent-owner wait budget. |
@@ -2429,10 +2429,20 @@ no explicit `daemonEndpoint` or `daemonTransport` is supplied it starts or reuse
 the local profile daemon. `connectKodaXRuntime()` is attach-only unless
 `autoStart: true` is passed.
 
-SDK auto-start allows `daemonStartupTimeoutMs` (default 60 seconds) and
-`daemonConnectTimeoutMs`. The longer startup budget covers cold machines and
-concurrent test/desktop startup without weakening PID, endpoint, token, or
-runtime-identity validation.
+SDK auto-start allows `daemonStartupTimeoutMs` (default 60 seconds) and
+`daemonConnectTimeoutMs`. The longer startup budget covers cold machines and
+concurrent test/desktop startup without weakening PID, endpoint, token, or
+runtime-identity validation.
+
+`homeDir` and `KODAX_HOME` deliberately name different levels. Runtime SDK and
+CLI daemon `--home` accept the **base directory that contains `.kodax`**;
+lower-level `KODAX_HOME` points at the **data directory itself** and need not be
+named `.kodax`. To share the default CLI daemon, omit `homeDir`; this honors the
+exact resolved `KODAX_HOME`. Passing `os.homedir()` explicitly instead selects
+`<os.homedir()>/.kodax`, regardless of an ambient custom `KODAX_HOME`. For an
+isolated embedder namespace, pass a private base directory and expect data at
+`<homeDir>/.kodax`. Passing `~/.kodax` as `homeDir` would instead select
+`~/.kodax/.kodax` and a different daemon namespace.
 
 ### Worker-hosted embedded usage
 
@@ -2575,7 +2585,7 @@ Every `KodaXRuntime` exposes the same service set in inline, Worker, and daemon
 | `artifacts` | Create/get/delete runtime artifact references for file/image/video inputs. |
 | `status` | Runtime snapshot with sessions, runs, permissions, workflows, and daemon counters. |
 | `diagnostics` | Latest context-budget and tool-exposure decisions for GUI/debug surfaces. |
-| `admin.agentRegistrations` | List/upsert/remove redacted external-agent registrations. With no plane, list is empty and mutations fail clearly. |
+| `admin.agentRegistrations` | List/upsert, atomically set `enabled` while preserving the full registration, or remove redacted external-agent registrations. Owner/revision-conditional mutation prevents a stale manager from changing a same-ID replacement. With no plane, list is empty and mutations fail clearly. |
 | `agents` | Check `enabled`, list/describe policy-filtered dispatchable agents, and preflight a selected route. |
 | `agentTasks` | Start/list/get/wait/continue/cancel/reconcile durable external-agent tasks and read their ordered event stream. |
 
@@ -2915,7 +2925,7 @@ fail clearly. Set
 
 | Surface | Methods | Contract |
 |---|---|---|
-| `runtime.admin.agentRegistrations` | `list`, `upsert`, `remove` | Durable owner configuration. List results expose `credentialConfigured`, never a credential value. With no plane, `list()` is empty and mutations fail clearly. |
+| `runtime.admin.agentRegistrations` | `list`, `upsert`, `setEnabled`, `remove` | Durable owner configuration. `setEnabled` preserves the complete captured executor registration while changing admission. Mutations accept both `expectedConfigurationRevision` and `expectedManagementOwner`; `setEnabled` can also atomically `claimOwner` on an unowned registration and rejects another owner. List results expose `managementOwner` and `credentialConfigured`, never a credential value. The same contract is carried across the daemon transport. With no plane, `list()` is empty and mutations fail clearly. |
 | `runtime.agents` | `enabled`, `listDispatchable`, `describe`, `preflight` | Applies health, capability, effect, concurrency, credential-presence, configuration-revision, and host-policy checks before dispatch. |
 | `runtime.agentTasks` | `start`, `list`, `get`, `events`, `wait`, `sendInput`, `cancel`, `reconcile` | Durable snapshots and append-only events for external tasks. The task keeps the immutable registration/executor binding captured at start. |
 
@@ -2926,12 +2936,34 @@ is valid only while the task reports `input-required` or `auth-required`.
 `reconcile()` asks the bound executor for authoritative remote state after an
 owner restart or uncertain failure.
 
+For external tasks, the built-in stores persist an internal full registration
+snapshot before the public task ledger. It is keyed by Agent ID and revision,
+is never returned by task or daemon APIs, and lets an admitted task keep using
+its original executor route after registration update/removal and Runtime
+restart. The internal form fixes `enabled: true` and omits management ownership
+and health diagnostics. The task's public route summary is validated against that internal
+snapshot before recovery. Terminal task state is durable before the last
+unreferenced snapshot is removed; startup cleans crash-window orphans.
+
+Custom `AgentExecutorPlaneStore` implementations should implement
+`loadTaskRegistrationSnapshots()` and `saveTaskRegistrationSnapshots()` as a
+pair and give one Runtime exclusive write ownership of that store. Omitting
+both remains compatible, but restart recovery then succeeds only while the
+exact current registration still exists. Store only non-secret executor config
+or secret references in `executorConfig`/`credentialRef`; the broker resolves
+the current referenced credential just in time, so removing a registration is
+not equivalent to revoking that credential at its issuer.
+
 The owner plane has a terminal close contract. Closing it rejects every pending
 `wait()` (including a wait without `timeoutMs`), disposes its executor instances,
 and makes subsequent registration, catalog, preflight, and task calls reject
-with `Agent executor plane is closed.` Repeated `close()` calls are safe. SDK
-hosts should stop accepting work before closing the owner and must not retain a
-plane service as a reusable handle after Runtime shutdown.
+with `Agent executor plane is closed.` One overall deadline covers admitted
+work plus executor disposal: the default is 30 seconds, and direct
+`createAgentExecutorPlane()` hosts may supply a positive finite
+`closeTimeoutMs`. A timeout rejects visibly even though already-admitted cleanup
+may finish in the background. Repeated `close()` calls are safe. SDK hosts
+should stop accepting work before closing the owner and must not retain a plane
+service as a reusable handle after Runtime shutdown.
 
 Restricted Workflow scripts use the same route as direct SDK calls. Both
 `wf.spawnAgent()` and `wf.runAgent()` validate and forward
@@ -2948,8 +2980,18 @@ silently falling back to the native child backend.
   each artifact before it materializes in the host boundary.
 - External agents may declare workspace effect `none` or `proposal`; direct
   workspace mutation is intentionally not a valid external registration.
-- Use `expectedConfigurationRevision` to prevent dispatching against a stale
-  endpoint/configuration seen by an earlier catalog read.
+- Use `expectedConfigurationRevision` for dispatch. For registration mutations,
+  compare both it and `expectedManagementOwner` so a same-revision ownership
+  change cannot be overwritten from an earlier catalog read. Config managers
+  should set a stable `managementOwner`; they may atomically claim an unowned
+  legacy registration while disabling it, but must not mutate a registration
+  owned by another manager.
+- Treat `configurationRevision` as the stable identity of immutable execution
+  content, not as a small counter. The same content may deterministically reuse
+  the same revision across remove/re-add or Runtime restart, but different
+  endpoint, protocol, executor/auth config, capabilities, effects, Skills,
+  modalities, or resource limits must never reuse it. Built-in A2A
+  configuration derives it from content.
 - A remote start followed by uncertain local persistence is recorded as
   `unknown` with its executor reference preserved; reconcile it rather than
   blindly starting a duplicate. Stable idempotency keys protect retries.
@@ -3208,6 +3250,24 @@ time/body/redirects, and strips authorization on a cross-origin redirect. A
 custom `fetch` option is a trusted transport override: the embedder then owns
 equivalent DNS-to-connection binding in that transport or proxy.
 
+The selected interface must remain on the Card's trusted origin. KodaX parses
+typed Card-level and Skill-level security declarations: requirement objects are
+alternatives (OR), every scheme inside one object is conjunctive (AND), and an
+empty requirement is anonymous. A configured credential is used only when one
+complete requirement is satisfiable; protected Skills that the configured
+profile cannot satisfy are not advertised to the Runtime catalog.
+
+The built-in profiles are HTTP Bearer and OAuth 2.0 Client Credentials. The
+OAuth profile pins the Card scheme, issuer, exact token endpoint, client ID,
+secret reference, scopes, optional RFC 8707 resource, and client authentication
+method. The external Authorization Server—not the Agent and not KodaX—issues
+the access token. KodaX resolves the client secret only for refresh, keeps an
+expiring token in process memory, coalesces refreshes, and retries one RPC once
+with a fresh token after `401`. Card, Agent RPC, and token endpoints remain
+separate safe-fetch trust boundaries, so a remote Agent cannot redirect a task
+payload to the token origin. API key, Basic, interactive OAuth, OIDC, mTLS, and
+multi-scheme AND requirements fail explicitly in the built-in client.
+
 ```ts
 import {
   createA2AAgentExecutorFactory,
@@ -3217,7 +3277,8 @@ import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
 
 const client = {
   networkPolicy: {
-    allowedOrigins: ['https://reviewer.example'],
+    // Card/RPC and OAuth token endpoints are separate trust boundaries.
+    allowedOrigins: ['https://reviewer.example', 'https://identity.example'],
     allowPrivateAddresses: false,
     requestTimeoutMs: 10_000,
     maxResponseBytes: 1_048_576,
@@ -3240,8 +3301,13 @@ const runtime = await createKodaXRuntime({
     factories: [createA2AAgentExecutorFactory(client)],
     credentialBroker: {
       async withCredential(ref, use) {
-        if (ref !== 'a2a/reviewer') throw new Error('Unknown credential reference.');
-        return use(process.env.A2A_REVIEWER_TOKEN ?? '');
+        const value = ref === 'a2a/reviewer'
+          ? process.env.A2A_REVIEWER_TOKEN
+          : ref === 'a2a/reviewer-client-secret'
+            ? process.env.A2A_REVIEWER_CLIENT_SECRET
+            : undefined;
+        if (!value) throw new Error(`Missing credential for reference: ${ref}.`);
+        return use(value);
       },
     },
     policy: ({ registration }) => ({ allowed: registration.effects.remote === 'read' }),
@@ -3260,10 +3326,40 @@ const started = await runtime.agentTasks.start({
 const terminal = await runtime.agentTasks.wait(started.taskId, 60_000);
 ```
 
+For OAuth, replace the legacy `credentialRef` input with the structured form;
+the same F258 `credentialBroker` must resolve `clientSecretRef`. The shared
+network policy must admit both origins, while each Card, RPC, and token request
+is still narrowed to its own exact origin:
+
+```ts
+const discovered = await discoverA2ARegistration({
+  agentId: 'external:a2a-reviewer',
+  agentCardUrl: 'https://reviewer.example/.well-known/agent-card.json',
+  authentication: {
+    type: 'oauth2-client-credentials',
+    scheme: 'enterprise-oauth',
+    issuer: 'https://identity.example/',
+    tokenUrl: 'https://identity.example/oauth/token',
+    clientId: 'kodax-reviewer',
+    clientSecretRef: 'a2a/reviewer-client-secret',
+    scopes: ['a2a.invoke'],
+    resource: 'https://reviewer.example/',
+    clientAuthentication: 'client-secret-basic',
+  },
+  effects: { remote: 'read' },
+}, client);
+```
+
 The executor supports durable task start/get, input continuation, cancel,
 reconcile, SSE events, and polling fallback. An ambiguous start is not retried
 automatically. A `credentialRef` is resolved just in time by the F258 broker;
 the registration, task store, and diagnostics never contain the credential.
+Authenticated SSE uses that same broker. JSON-RPC ID/version and task/context
+correlation are validated before an event is accepted; if a stream ends
+normally before a terminal snapshot, the executor resumes bounded polling.
+Streamed `artifactUpdate` chunks are accumulated by artifact ID according to
+`append`, and direct Message file Parts are preserved as authorized artifact
+references.
 
 ### Built-in configured path (no host code)
 
@@ -3277,6 +3373,24 @@ kodax a2a test reviewer
 kodax a2a call reviewer "Review this document"
 ```
 
+The no-code OAuth path stores only the environment-variable name for the client
+secret. It can be staged disabled and hot-activated later:
+
+```bash
+export A2A_REVIEWER_CLIENT_SECRET='provisioned-out-of-band'
+# PowerShell: $env:A2A_REVIEWER_CLIENT_SECRET='provisioned-out-of-band'
+# PowerShell: use one line or replace each trailing \ with a backtick.
+kodax a2a add reviewer https://reviewer.example/.well-known/agent-card.json \
+  --disabled --effect read --oauth-scheme enterprise-oauth \
+  --oauth-issuer https://identity.example/ \
+  --oauth-token-url https://identity.example/oauth/token \
+  --oauth-client-id kodax-reviewer \
+  --oauth-client-secret-env A2A_REVIEWER_CLIENT_SECRET \
+  --oauth-scope a2a.invoke --oauth-resource https://reviewer.example/
+kodax a2a enable reviewer
+kodax a2a disable reviewer
+```
+
 Embedded CLI Runtimes and the user-owned daemon automatically reconcile these
 entries as `external:<name>`. Discovery/update failure retains that entry's
 last-known-good registration; another entry can still update. The environment
@@ -3284,15 +3398,113 @@ broker resolves `credentialEnv` only at call time. Automatic Runtime
 registration accepts public HTTPS and exact loopback targets; explicit private
 network access remains an operator action on the direct CLI/SDK path.
 
+`enabled` is desired state in `a2a.json`, not a fabricated cross-process live
+flag. `a2a list` reports configured entries and that desired state. The owning
+Runtime's `admin.agentRegistrations.list()` is authoritative for applied
+registrations. Automatic reconciliation handles disables/removals first,
+skips unchanged peers, performs no Card or token request for disabled entries,
+and rediscovers before re-enable. Once the owning Runtime observes and applies
+the revision, disable blocks all new starts, including an explicit
+`external:<name>` target, but does not cancel or break an already admitted task.
+The CLI mutation returning is not cross-process acknowledgement. A failed
+activation remains retryable through the owning
+`ConfiguredA2ARuntimeHandle.reload()` even when the disk revision is unchanged;
+the passive `kodax integrations reload` command validates only its own process.
+
+`kodax a2a test` performs Card discovery and security planning only. It never
+requests an OAuth access token; token acquisition starts at `a2a call` or the
+first Runtime dispatch.
+
 Inbound publication is also no-code:
 
 ```bash
 export KODAX_A2A_TOKEN='replace-with-a-long-random-token'
+# PowerShell: $env:KODAX_A2A_TOKEN='replace-with-a-long-random-token'
 kodax a2a expose                    # Runtime default Agent
 kodax a2a expose document-agent     # ~/.kodax/agents/document-agent.md
 kodax a2a serve --port 8765
 ```
 
+The fixed token above is the compatibility profile. For dynamic production
+tokens, configure KodaX as an OAuth Resource Server and point it at an external
+issuer:
+
+```bash
+kodax a2a expose document-agent --auth oauth2-jwt \
+  --oauth-scheme enterprise-oauth \
+  --oauth-issuer https://identity.example/ \
+  --oauth-audience https://kodax.example/a2a \
+  --oauth-jwks-url https://identity.example/.well-known/jwks.json \
+  --oauth-token-url https://identity.example/oauth/token \
+  --oauth-metadata-url https://identity.example/.well-known/oauth-authorization-server \
+  --required-scope a2a.invoke
+kodax a2a serve --port 8765
+```
+
+The Authorization Server authenticates clients, provisions client IDs/secrets,
+issues/rotates/revokes tokens and, for JWT access tokens, signs them and
+publishes metadata/JWKS. The calling A2A
+client obtains a token out of band or with Client Credentials and sends it in
+the Bearer header. KodaX validates JWT type, asymmetric signature, issuer,
+audience, lifetime, subject, and required scopes before task lookup, then maps
+`sub` to the A2A principal. Missing/invalid credentials return `401`; a valid
+token without the required scope returns `403 insufficient_scope`. KodaX does
+not hold the issuer signing key or expose token, refresh, client-registration,
+login, or consent endpoints. Opaque-token introspection and mTLS deployments
+must use a host authentication adapter or reverse proxy. Offline JWT/JWKS
+validation also cannot observe immediate per-token revocation: use short access
+token lifetimes, signing-key rotation, or an introspecting proxy/adapter when
+that property is required.
+
+#### Upgrade retained pre-realm tasks
+
+Realm-aware task ownership intentionally has no normal-request legacy fallback:
+an authority switch must never adopt tasks merely because it reuses a subject.
+If a v0.7.70 task store must remain addressable after upgrading, stop the A2A
+server and first inspect an exact-owner migration plan:
+
+```bash
+kodax a2a migrate-tasks
+kodax a2a migrate-tasks --apply --confirm-server-stopped
+
+# OAuth identity is token-specific, so provide the known historical subject.
+kodax a2a migrate-tasks --subject trusted-orchestrator
+```
+
+The configured Bearer profile supplies its fixed `principalId`; OAuth requires
+`--subject`. Dry-run does not rewrite `tasks.json`. Apply rekeys only exact
+matches, preserves unmatched records, and refuses a live task-store owner.
+Custom SDK hosts can plan multiple known owners without exposing raw tokens:
+
+```ts
+import { migrateA2ALegacyTaskOwners } from '@kodax-ai/kodax/a2a';
+
+const mappings = [{
+  securityRealm: 'oauth2-jwt:https://identity.example/',
+  subject: 'trusted-orchestrator',
+}] as const;
+const plan = migrateA2ALegacyTaskOwners({
+  dataDir: '/var/lib/kodax/a2a', mappings, apply: false,
+});
+
+// After the host/operator verifies the plan:
+if (plan.matchedLegacyTaskCount > 0) {
+  migrateA2ALegacyTaskOwners({
+    dataDir: '/var/lib/kodax/a2a', mappings, apply: true,
+  });
+}
+```
+
+The SDK also accepts `tenant` when a custom authentication adapter historically
+returned one. Two mappings that claim the same legacy owner for different
+realms are ambiguous and rejected; split or guessed ownership is never applied.
+
+`a2a serve` resolves its Runtime provider in this order: explicit CLI option,
+environment, core configuration, then the built-in default. Provider-compatible
+model selection follows the normal hosted Runtime rule. A selected Markdown
+Agent may declare its own validated `provider`; remote A2A input cannot choose
+or override provider, model, reasoning, profile, workspace, or tools.
+
 `expose` validates a named user Markdown Agent before writing its reference.
 `serve` loads configured MCP and Extensions before it resolves the execution
 binding or opens a socket. Native workspace read tools are admitted by
@@ -3305,10 +3517,14 @@ projection and never reveal the private Skill inventory.
 The running server pins Agent, Skill, workspace, tool registration, process and
 store revisions. Card/auth/limits can hot reload; execution-authority changes
 require an explicit restart. Managed contexts live below
-`~/kodax_a2a_server_workspace/<profile>/contexts/`. Exact Skill scripts require
+  `~/kodax_a2a_server_workspace/<runtime-profile>/contexts/<context-key>/`. Exact Skill scripts require
 `process: isolated`, an admitted `scripts/...` path, and a passing
 `kodax sandbox doctor`; KodaX never falls back to an unsandboxed shell.
 
+Every concrete file reached by `read`, `grep`, or `glob` is checked against the
+bound workspace. Child runs inherit ceilings for native reads, tools, Skills,
+and Skill scripts; they cannot expand the parent's admitted authority.
+
 ### Publish one KodaX Agent
 
 Publication is host-owned and opt-in. The public card describes only the
@@ -3316,7 +3532,10 @@ configured Agent, media types, and skills. Authentication runs before task
 lookup; authorization runs per operation; task visibility is principal-scoped.
 
 ```ts
-import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';
+import {
+  createBearerEnvA2AAuthentication,
+  createKodaXA2AServer,
+} from '@kodax-ai/kodax/a2a';
 import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
 
 const runtime = await createKodaXRuntime({ mode: 'embedded', isolation: 'inline' });
@@ -3332,16 +3551,12 @@ const server = createKodaXA2AServer({
     inputModes: ['text/plain'],
     outputModes: ['text/plain'],
   },
-  authentication: {
-    securitySchemes: { bearer: { httpAuthSecurityScheme: { scheme: 'Bearer' } } },
-    securityRequirements: [{ schemes: { bearer: { list: [] } } }],
-    async authenticate(request) {
-      return request.headers.get('authorization') === `Bearer ${process.env.KODAX_A2A_TOKEN}`
-        ? { subject: 'trusted-orchestrator', scopes: ['a2a'] }
-        : null;
-    },
-  },
-  async authorize({ principal }) { return principal.scopes.includes('a2a'); },
+  authentication: createBearerEnvA2AAuthentication({
+    type: 'bearer-env',
+    tokenEnv: 'KODAX_A2A_TOKEN',
+    principalId: 'trusted-orchestrator',
+  }),
+  async authorize({ principal }) { return principal.scopes.includes('a2a:invoke'); },
   limits: {
     maxRequestBytes: 1_048_576,
     maxPartBytes: 524_288,
@@ -3359,9 +3574,9 @@ const server = createKodaXA2AServer({
 const localBaseUrl = await server.listen({ hostname: '127.0.0.1', port: 0 });
 ```
 
-Production hosts route `GET /.well-known/agent-card.json` and JSON-RPC `POST /`
-to `server.handle(request)` behind their own TLS terminator. `POST /a2a` remains
-an accepted compatibility alias. `listen()` waits for durable recovery before
+Production hosts route `GET /.well-known/agent-card.json` and canonical
+JSON-RPC `POST /a2a` to `server.handle(request)` behind their own TLS
+terminator. `POST /` remains an accepted compatibility alias. `listen()` waits for durable recovery before
 it resolves. A host that wires `handle()` directly may explicitly await
 `server.whenReady()` before it starts accepting traffic; `handle()` also waits
 for the same recovery promise. The durable edge store supports get/list,
@@ -3375,12 +3590,28 @@ default). When that bound is reached the response contains the current working
 task; it does not cancel the Runtime run, and clients can continue with
 `GetTask` or `SubscribeToTask`.
 
+When a task enters `INPUT_REQUIRED`, the next accepted input answers the pending
+interaction on the original Runtime run; it does not start a replacement run.
+History length and list filters are validated and bounded. Task listing uses a
+stable opaque cursor, while per-principal retention prunes only the oldest
+terminal records. Terminal subscriptions and failed-start resources are closed
+by their owning lifecycle.
+
 Remote messages are ordinary user inputs. They cannot select provider, model,
 profile, tools, working directory, permission mode, or Runtime configuration.
 URL parts are rejected; inline raw/data parts are bounded and materialized under
 the server-owned data directory. Responses expose final approved output only,
 not system prompts, reasoning deltas, tool payloads, credentials, or local paths.
 
+Generated files are published only through the trusted output broker: a normal
+tool or Extension stages a file in the context's `.kodax-a2a-staging` area, or
+a successfully admitted `run_skill_script` promotes one of its declared
+outputs. The server rechecks that the result is a regular non-symlink file in
+the real bound workspace and applies part-size/output-mode limits before
+inlining it. A declaration from a failed Skill run, an ordinary `write`/`edit`
+elsewhere in the workspace, and a local path in model text never become A2A
+artifacts implicitly.
+
 The normative baseline is A2A repository commit
 `2183794bfb9b67af4aee1be0a0ef726050642873`, protocol `1.0`, with
 `specification/a2a.proto` SHA-256
@@ -3410,12 +3641,28 @@ from renderer or model output. `connectKodaXRuntime()` is attach-only unless `au
 An explicit inline rollback policy blocks auto-start until the owner policy is
 explicitly changed back to daemon.
 
+For Electron, `homeDir` is still the CLI-style base directory, not
+`process.env.KODAX_HOME`. Packaged/asar applications may use `autoStart: true`
+directly; the SDK launches only the daemon child in Electron's Node execution
+mode and does not mutate the application's environment or start a second GUI
+instance. `ELECTRON_RUN_AS_NODE` exists only at the child exec boundary and is
+removed before daemon application code loads, so Bash, MCP, LSP, sandboxed
+commands, and ordinary external processes do not inherit Electron Node mode.
+
+Packaged auto-start requires Electron's `RunAsNode` fuse, which Electron enables
+by default. If an embedder deliberately disables that fuse, the packaged
+executable cannot serve as a detached Node host: start the daemon with an
+ordinary Node/CLI process and use attach-only mode instead. A packaged
+`autoStart: true` timeout includes this fuse requirement in its diagnostic; the
+SDK does not relaunch the GUI or silently fall back to an inline Runtime.
+
 ```ts
 import { connectKodaXRuntime } from '@kodax-ai/kodax/runtime';
 
 const runtime = await connectKodaXRuntime({
   profile: 'coder',
   autoStart: true,
+  homeDir: coderRuntimeBaseDir, // owns <coderRuntimeBaseDir>/.kodax
   clientInfo: {
     name: 'kodax-space',
     version: '0.1.32',
@@ -3445,6 +3692,7 @@ const runtime = await connectKodaXRuntime({
     daemonSafeRunInput: 1,
     sharedSessionSettings: 1,
     durableRecoveryQueries: 1,
+    daemonManagement: 1,
   },
 });
 ```
@@ -3532,10 +3780,13 @@ reset boundary.
 
 ### Durable mutations, stable ordering, and settings CAS
 
-Every public control mutation uses a durable operation envelope. Credential
-supply and Host Tool completion are connection-local reverse-result frames and
-are deliberately excluded from the control journal so secrets/results are not
-persisted. The SDK creates an operation ID for ordinary one-shot calls. A
+Every durable public control mutation uses an operation envelope. Credential
+and Host Tool register/revoke/supply/complete requests are reverse-bridge
+control frames and are deliberately excluded from the control journal so
+secrets/results are not persisted. They still enter the daemon management
+draining fence: once an atomic stop begins, they fail with typed `conflict` and
+cannot change reverse-bridge state. The SDK creates an operation ID for
+ordinary one-shot calls. A
 product-level retry after a lost response must reuse its own stable operation
 ID; changing its method, payload, resource, or authenticated principal is
 rejected.
@@ -3743,10 +3994,24 @@ remain valid only for embedded Runtime calls.
 
 ### Recovery queries and stop preflight
 
-`runtime.status.preflight()` returns connected-client count, active and queued
-runs, pending AskUser/permission records, blockers, and `canStop`. Treat this as
-a required check before stop or inline rollback; the query does not stop the
-daemon by itself. `runtime.operations.get()` reconciles durable mutations,
+`runtime.status.preflight()` returns the initialized logical-client count,
+active and queued runs, running/paused Workflows, every non-terminal External
+Agent task (including `unknown`), pending AskUser/permission records, blockers,
+and `canStop`. The background-work blockers are `active_workflows` and
+`active_agent_tasks`. The current facade counts as one; daemon self-connections
+and bounded health probes do not count. A second process changes the count to
+two, and its awaited `close()` makes the count converge back to one.
+
+Preflight is useful for UI, but it is not a stop authorization token. Use
+`runtime.daemon.inspect()` to obtain one consistent management revision,
+verified owner fence, owner-policy revision, and preflight projection. Only
+`runtime.daemon.stopForInline()` atomically rechecks and commits a rollback.
+The management revision also advances when the preflight projection changes,
+so a Workflow or AgentTask lifecycle transition between inspect and commit
+invalidates the stale stop. Capability details
+`daemonManagement.backgroundWorkPreflight` and
+`daemonManagement.reverseBridgeDrainingFence` identify this complete contract.
+`runtime.operations.get()` reconciles durable mutations,
 `hostTools.getInvocation()` reconciles Host Tool metadata, and
 `permissions.listGrants()` returns the daemon-owned persistent grant set.
 
@@ -3758,27 +4023,64 @@ truth.
 
 ### Owner policy, rollback, and Electron boundary
 
-Daemon and inline Coder use one profile fence. For an emergency rollback, stop
-the daemon, switch the policy with revision CAS, then acquire the inline owner:
+Daemon and inline Coder use one profile fence. Do not compose
+`status.preflight()` with a low-level unconditional stop: another client or run
+can appear between those calls. The public rollback transaction gates new
+clients and mutations, rechecks the same Runtime and management/policy
+revisions, verifies there is no other client or active/queued/pending work,
+commits sticky inline policy while that daemon still owns the fence, and then
+requests shutdown.
 
 ```ts
 import {
   acquireKodaXInlineOwner,
-  setKodaXRuntimeOwnerMode,
+  enableKodaXDaemonOwner,
+  getKodaXRuntimeOwnerState,
 } from '@kodax-ai/kodax/runtime';
 
-const policy = setKodaXRuntimeOwnerMode({
-  homeDir: kodaxHome,
-  profile: 'coder',
-  mode: 'inline',
-  expectedRevision: currentPolicyRevision,
+const management = await runtime.daemon.inspect();
+if (!management.preflight.canStop) {
+  showRollbackBlockers(management.preflight.blockers);
+  return;
+}
+
+const rollback = await runtime.daemon.stopForInline({
+  expectedRuntimeId: management.runtimeId,
+  expectedRevision: management.revision,
+  expectedOwnerPolicyRevision: management.ownerPolicy.revision,
+  operation: { operationId: loadOrCreatePendingOperationId('coder-inline-rollback') },
 });
+
+// `accepted` means inline policy is committed and shutdown is in progress.
+// Wait through the public owner-state query; never infer release from a PID.
+const shutdownDeadline = Date.now() + 30_000;
+while (getKodaXRuntimeOwnerState({ homeDir: kodaxHome, profile: 'coder' }).owner?.runtimeId
+  === rollback.runtimeId) {
+  if (Date.now() >= shutdownDeadline) throw new Error('Timed out waiting for daemon owner release.');
+  await delay(25);
+}
+const releasedOwner = getKodaXRuntimeOwnerState({ homeDir: kodaxHome, profile: 'coder' });
+if (releasedOwner.ownerStatus !== 'unowned') {
+  throw new Error('Coder profile acquired a different owner during rollback.');
+}
+await runtime.close(); // Detach only; it does not perform a second stop.
 const inlineOwner = acquireKodaXInlineOwner({ homeDir: kodaxHome, profile: 'coder' });
+
+// Later, after the inline owner has released its fence:
+inlineOwner.close();
+const daemonPolicy = enableKodaXDaemonOwner({ homeDir: kodaxHome, profile: 'coder' });
+// daemonPolicy.revision is authoritative; no expectedRevision guess is needed.
 ```
 
-The inline policy is sticky: later CLI auto-start is rejected until an explicit
-CAS changes the policy back to `daemon`. Stale-owner handling validates the
-owned lock/state and never kills a process merely because a PID was reused.
+Any management revision change, another logical client, active or queued run,
+running/paused Workflow, non-terminal/unknown AgentTask, pending
+AskUser/permission, or in-flight mutation returns structured `conflict`; the
+daemon remains running and policy remains unchanged. Draining also rejects
+credential and Host Tool state changes without journaling their secrets or
+results. The inline policy is sticky: later CLI auto-start is rejected until
+`enableKodaXDaemonOwner()` changes it back to `daemon`. `runtime.close()` still
+only detaches. Stale-owner handling validates the owned lock/state and never
+kills a process merely because a PID was reused.
 
 Keep all trusted objects in Electron Main: daemon token/endpoint, stable client
 identity, operation IDs, owner policy, keychain broker, Host Tool handlers, and