@byokit/openclaw 0.6.3 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.9.0 (2026-10-09)
+
+- Dependency update: pins @byokit/relay 0.6.0.
+- Dependency update: pins @byokit/link 0.8.0.
+- SECURITY: (from @byokit/pair 0.9.0) pinning and approval semantics. A compact QR's pending grant pins the key the code handshake authenticated, kept after Noise message 2 and before the device's identity goes out in message 3; if saving it fails, pairing stops before the computer learns the device. A device using `onPending` says so inside the handshake, and only then does the computer keep a yes given after its socket dropped, granting only the device key that handshake authenticated; any other device that leaves still gets no grant. A computer with another key at the same address is still refused, and a version 1 `pendingGrant` refuses a `host` that differs from its QR.
+- FIX: (from @byokit/pair 0.9.0) a phone killed while the person at the computer decides now resumes against the pinned computer, for compact and version 1 QRs alike. `pairWithOffer` takes `onPending(grant)`, which hands over the pending grant to keep before the computer can approve this device, and `pendingGrant` accepts a compact QR given the authenticated `host` key, and `parseOffer` reads a compact QR for inspection (expiry, addresses, name, role) without one. Before, `pendingGrant` refused compact QRs, and even a version 1 pending grant never came online after a real kill. A socket that drops once the computer has taken the code now ends pairing with `unreachable` instead of trying the next address, where the spent code or ticket could only be refused as `wrong-code` or `expired`. A socket that closes while `onPending` is still saving ends pairing at once with that close; a version 1 `onPending` that never settles times out. The compact QR is unchanged: 109 characters for one relay address and the name Umer.
+- FIX: (from @byokit/pair 0.9.0) the pairing picture's words match what the host now prints: scan the code, or type the shown code where the phone page asks for it, with no raw address to type.
+- FIX: (from @byokit/pair 0.9.0) the browser pairing test closes only the Chromium processes it spawned — over that browser's own private CDP pipe — instead of signalling a whole process group, so a killed or timed-out test can no longer take out or leave behind the wrong process tree. `BYOKIT_CHROME` is the single documented key that selects the test browser.
+
+- Cut first-install wall time ~3x (freeze ~20x) by dropping the 37,999 per-entry `fsync`s from `freeze()`: entries are chmodded read-only in bounded batches, one filesystem-wide `sync -f` flush runs where available (Linux, ~2 s measured vs ~110 s of per-file fsync transactions), and the manifest is read from the built tree once. Durability rule: `docs/runtime-kits.md` 5.16.
+- FEAT: Name the engine's learning switch: `learning()`, `setLearning(mode | 'default')` and `restoreLearning(captured)` over the config key `skills.workshop.autonomous.mode` (`off | propose | auto`, engine default `auto` when absent), as a typed, file-backed veneer on the one-key pair — valid on a stopped home, before boot and after `stop()`. Absence is a value (`{ present: false }`); an unknown mode throws listing the accepted values, a stored value outside the enum makes `learning()` throw naming it, both writers throw when `KitOptions.config` also passes `skills`, and `restoreLearning` reads back and throws on mismatch. The README also documents the supported repair of a retained home killed without `stop()` (orphan gateway, stale lock, reseal, exit-78 doctor repair) and cross-references the separate auth-store seal size bound.
+
+## 0.8.0 (2026-10-09)
+
+- Forward actual thinking-token progress and report Gateway acceptance as `started`; reuse bounded, file-witnessed member admission status so ready runs avoid redundant sign-in checks without skipping authority checks. Device state uses the same live readiness boundary; `providerStatus` preserves unknown versus empty sign-in status.
+- FIX: On the Claude CLI route the printed `## Tooling` list now uses the Claude wire catalog names (`mcp__openclaw__<tool>`), so a listed tool can be called exactly as printed. Every other route keeps the stock prompt byte-identical, and already-prefixed names are never prefixed again.
+- The deprecated `anthropic` provider alias on route `anthropic-cli` stays readable as `route.deprecatedProvider` (`'anthropic'`); its removal moves to 0.9.0.
+- FIX: `OpenClawKit.abort` always returns a Promise, including after an engine drop; cancellation failures remain catchable without changing healthy abort results.
+- FIX: `ensureMember` resolves only once `agents.list` shows the member (bounded ~5 s wait, then a plain error naming the member), so a turn sent right after it is no longer rejected as `unknown agent id` while the engine hot-reloads its roster.
+
+## 0.7.0 (2026-10-08)
+
+- FIX: Unreadable sealed sign-ins now fail closed with `AuthStoreUnreadableError` and recovery words, leaving `auth-store.sealed` byte-identical for original-key or backup repair and retry instead of starting signed out with a replacement store.
+
 ## 0.6.3 (2026-10-07)
 
 - Dependency update: pins @byokit/relay 0.5.3.

package/README.md

@@ -30,6 +30,8 @@ phone page that pairs, signs in with ChatGPT, runs and answers approvals, see
 `engine/patches.json` declares the exact upstream tarball integrity, commit, unique edits and before/after file
 hashes. The Gateway Workshop review patch writes content-free, durable usage facts only when the kit sets its
 accounting environment. The separately bundled worker and all other detached kinds remain uncovered.
+The Claude CLI route also uses the bundled [Tooling-name correction](../../docs/runtime-kits.md#516-bundled-engine-patches-and-engine-started-usage);
+apps do not need consumer tool aliases.
 The full upstream MIT notice ships in [engine/OPENCLAW-LICENSE](engine/OPENCLAW-LICENSE).
 
 Each `prepare()` verifies the **entire** selected engine tree, including unpatched files. The kit installs stock
@@ -130,7 +132,7 @@ For an owner who explicitly offers keys, `kit.addKey('ana', { authChoice: 'opena
 `ok`, `invalid` or `not_included`. Label the option **API key (billed per use)**. Select only `routes()` rows with
 `keyEntry: true`; API rows remain `offer: false`. Each route also carries its engine `revision`, `checked` date,
 label and key error word names. Submit the input directly, clear the field afterwards, and never log or save it in
-app state. The kit never returns engine key-check errors or the key. `ui-core/kits` supplies `keyStep`/`keyView`
+app state. The kit never returns engine key-check errors or the key. [`@byokit/ui/kits`](../ui/README.md) supplies `keyStep`/`keyView`
 for entry, checking, success and failure states, using the kit's `key.*` words.
 
 To use the saved key for one run, pass `auth: 'apiKey'`. The key lives in the member's separate
@@ -142,9 +144,23 @@ because the engine's profile pins can rotate. The `byokit-key-` member prefix is
 replaces the previous key; a failed replacement leaves this option unavailable. If the normal agent already has
 an API key added through pass-through calls, `addKey` returns `invalid` and leaves that key untouched.
 
+`OpenClawKit.abort` always returns a Promise. Await it or attach `.catch(...)`: an unavailable engine, transport
+failure or invalid API-key session key rejects with the original error, never throws synchronously, and is not
+reported as successful cancellation. Healthy cancellation ends the run as defined in
+[the run contract](../../docs/runtime-kits.md#58-runs-members-and-streams).
+
 A run spec also takes `system`, `images` (`{ data, mimeType }[]`), `thinking` and `tools`, a subset of the app tools
 (`KitOptions.tools` names) this run may call; any other app tool is refused at the gate before `ToolHost.gate` sees
-it. Tool events carry the engine's call `id`, the `input` on `start` and the `output` and `error` on `end`. A run that
+it. Run events report `started` when the Gateway accepts the request (not when it finishes), and forward
+actual `thinking` progress as `{ type: 'thinking', tokens }`. Silent routes invent no progress; cached replays
+without a new accepted frame emit no `started`. Handle these frames explicitly rather than treating every
+non-text/tool frame as an end.
+Live readiness reads (`providers`, `signedIn`, or device `state()`) prepare admission for the next run, avoiding
+redundant checks while authority remains reusable. `providerStatus(member)` returns `undefined` for unknown
+status rather than `[]`; `providers` maps unknown to `[]`, and `signedIn` to `false`.
+See [the admission contract](../../docs/runtime-kits.md#58-runs-members-and-streams) for lifetime, expiry,
+file witnesses, invalidation and remote-revocation limits.
+Tool events carry the engine's call `id`, the `input` on `start` and the `output` and `error` on `end`. A run that
 ends ok carries `usage` (the engine's token total for the run, and `costUsd` when it priced the model) and
 `planWindow` (the subscription's quota windows as the engine last read them), each only when the engine reports it.
 `openclawDevice(link).run(message, o)` takes the same options over the link, and `state()` adds the kit and engine
@@ -331,7 +347,7 @@ Entries:
 | `RouteView`, `RouteFacts`, `JsonValue`, `UsageClient`, `DayUsageClient` (`.`) | The types `routes()`, `routes(facts)` and the usage readers return or take, nameable without a cast |
 | `openclawDevice(link)` (`./device`) | Portable client: state, routes, sign-in, runs, steer, abort, approvals, events, sealed notices, pass-through `call`. `OpenClawDevice` and `DeviceEndFrame` name what it returns |
 | `LinkRefused`, `openNotice` (`./device`) | The host's own refusal as an error; opens a sealed approval notice |
-| `words`, `stateWords`, `toAccountView` (`.`, `./device`) | The kit's sentences, so a phone shows the words the computer does; `toAccountView` feeds `@byokit/ui-core`'s `phaseOf` |
+| `words`, `stateWords`, `toAccountView` (`.`, `./device`) | The kit's sentences, so a phone shows the words the computer does; `toAccountView` feeds [`@byokit/ui`](../ui/README.md)'s `phaseOf` |
 | `openclawLink(kit, o)` (`./link`) | `handle` / `stream` / `allow` for a `@byokit/link` `Host`, checked per member, plus `onAction` for relay push actions. `OpenClawLinkOptions` / `OpenClawLinkHost` name both sides |
 | `serve(o)` (`./link`) | Binds the link host per reach and returns its URLs (`OpenClawServeOptions` / `OpenClawServeHandle`) |
 | `fakeGateway`, `openclawContract`, `startModelStub`, `useModelStub` (`./testing`) | In-memory Gateway, the contract suite and the scripted model for tests. `fakeGateway`'s script is typed per method (`FakeScript`, `FakeHandler`), and a recorded `StubCall` carries a typed `StubRequest` |
@@ -375,6 +391,57 @@ back out), the write is atomic in `prepare()`'s exact shape, and the engine appl
 your app does **not** also pass in `KitOptions.config`: that option is merged over the saved file on every boot and
 wins. Don't interleave a narrow set with `patchConfig`, which rewrites the whole config through the Gateway.
 
+## Engine learning state
+
+The engine's learning switch is the config key `skills.workshop.autonomous.mode` (`off | propose | auto`; engine
+default `auto` when absent). `off` keeps only the suggestion nudge, `propose` creates pending proposals, `auto`
+applies captured proposals and runs the scanner-gated cleanup; the engine projects a system-owned cron job
+`skill-collection-review-<agentId>` per workspace agent, enabled only on `auto`. The kit names it — file-backed like
+the pair above, so it works on a stopped home, before boot and after `stop()`:
+
+```ts
+import { OpenClawKit } from '@byokit/openclaw';
+
+const kit = new OpenClawKit({ stateDir: './openclaw-state' });
+
+kit.learning();                                  // { present: false } | { present: true, mode: 'off' | 'propose' | 'auto' }
+const before = kit.learning();                   // capture before maintenance
+kit.setLearning('off');                          // returns the state it replaced
+kit.setLearning('default');                      // remove the key: the engine default (auto) applies again
+kit.restoreLearning(before);                     // writes the capture, reads it back, throws on mismatch
+```
+
+Absence is a value (`{ present: false }`), never "probably default". An unknown mode throws listing the accepted
+values (`off|propose|auto`, plus `default` for `setLearning`), a stored value outside the enum makes `learning()`
+throw naming it, and both writers throw when the app also passes a `skills` key in `KitOptions.config` (that option
+wins at every boot). A home that was never prepared surfaces the file read's ENOENT: `prepare()` once first.
+
+## Retained home killed without stop()
+
+A host crash or `kill -9` skips `stop()` cleanup. The next `prepare()` (the next `start()`) repairs the home
+itself — no manual file surgery:
+
+- It stops a leftover Gateway only after verifying it is a same-user orphan of this root (matching pid, identity,
+  start time, exe/cwd and env), and only when the auth-store lock's owner is dead; then it seals the leftover live
+  `state/` and `home/` trees back into the store under the acquired lock. Anything ambiguous (a live lock owner, an
+  unverifiable pid, another writer alive, shutdown timeout) fails closed with `EngineAlreadyRunningError` instead.
+- A stale `auth-store.lock/` with a dead owner is recovered through a `recovery/` marker; interrupted
+  `cleanup`/`restoring` transitions are completed from the authenticated snapshot; empty live trees are treated as
+debris.
+- An engine exit code 78 means the engine asked for repair: the kit's own repair path runs
+  `doctor --fix --yes` with `doctorContext()`'s exact env.
+
+What a killed home leaves behind: live plaintext `state/` and `home/` (never resealed), `auth-store.lock/` with a
+dead owner pid, `gateway.pid` and `gateway.identity` (a still-live orphan Gateway is the dangerous case),
+`openclaw.json` with its `.bak.*` journal, `engine-set`, `plugin/`, `workspaces/`, `usage/`, `tmp/`, `npm-cache/`
+and `install-home/`. None of these is safe to edit by hand, and `auth-store.sealed` above all: never hand-edit it —
+restore an authentic backup under the lock instead (see the credential sealing section). Keep backups before any
+manual intervention.
+
+If a leftover `home/` carries large regenerable tool caches, resealing can exceed the runtime string bound and
+abort; that seal size bound is a separate, known limitation (tracked as the auth-store seal size demand), not
+fixed by the recovery path — move only regenerable cache trees aside (keeping backups) and retry `start()`.
+
 ## App-owned task recovery
 
 If your app requeues interrupted tasks itself, declare their namespaces **before starting the kit**:
@@ -484,8 +551,18 @@ Without `authSeal`, engine credentials remain plaintext. With it, successful `pr
 only a sealed snapshot, `auth-store.sealed`, for the sealed credential paths; regenerable caches stay on
 disk unsealed. The adapter authenticates the snapshot
 before any restoration; a missing adapter rejects. A store the key cannot open (a wrong key,
-damaged or tampered bytes) or whose payload is not a credential snapshot is kept aside as
-`auth-store.sealed.unreadable-<ms>` and the engine starts signed out (`why: 'sign-in-reset'`); sign in again. Files restored for the engine
+damaged or tampered bytes) or whose payload is not a credential snapshot stays unchanged at
+`auth-store.sealed`. Both `prepare()` and `start()` reject with exported `AuthStoreUnreadableError`
+(`code: 'auth-store-unreadable'`, `reason: 'auth-failed' | 'invalid-snapshot'`). The kit reports
+`{ phase: 'failed', why: 'auth-store-unreadable' }`; show `stateWords(kit.state)`, not a sign-in prompt.
+Restore access to the original seal/key (and the original service/stateDir binding if the adapter uses
+one), then retry `start()` with that adapter. Do not generate/rotate a key to repair an unreadable store.
+If the bytes are damaged, stop all writers, acquire the host writer lock, and restore an authentic
+backup with its matching key before retrying. There is no automatic reset or overwrite.
+For stores kept aside by an older kit, restore the original `.unreadable-*` snapshot to
+`auth-store.sealed` only while stopped under that lock, preserving both it and any replacement as
+backups first; use the original seal. Without the matching key or an authentic backup the kit cannot
+recover the sign-in. Files restored for the engine
 have mode 0600 and directories 0700. File symlinks are sealed only when their fully resolved targets are
 regular files inside the isolated engine root; they restore as regular files at the link paths. Outside-root,
 dangling and directory symlinks (including loops), sockets, FIFOs and devices are skipped.
@@ -540,4 +617,4 @@ frozen (docs/runtime-kits.md §5).
 
 Apache-2.0. See [LICENSE](LICENSE); the bundled engine's MIT text is [engine/OPENCLAW-LICENSE](engine/OPENCLAW-LICENSE).
 
-Claude: `anthropic-cli` uses your own unmodified Claude Code login on this machine (provider `claude-cli`, plugin `anthropic`; subscription billing; `kit.signedIn(member, 'claude-cli')` is true once Claude Code is signed in, and `'anthropic'` stays the API-billed provider a Claude Code login never satisfies. Before 0.7.0 this route reported provider `anthropic`; that value is deprecated, kept as `deprecatedProvider` until 0.8.0), with login kept in Claude Code under the kit’s isolated `HOME=<stateDir>/openclaw/home` and `CLAUDE_CONFIG_DIR=<stateDir>/openclaw/home/.claude`; sign in there with `claude auth login`, then call `signIn`. Activation live-tests the route; native sign-out is through Claude Code. `apiKey` is explicit API billing (“API key (billed per use)”, `offer: false`): `signIn` asks for the key through `paste`, then engine activation verifies it. The `setup-token` choice is listed but never offered: the pinned Gateway has no app-guided sign-in for it. The kit never imports Claude credentials or implements direct Claude.ai OAuth; [Anthropic’s terms](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) apply.
+Claude: `anthropic-cli` uses your own unmodified Claude Code login on this machine (provider `claude-cli`, plugin `anthropic`; subscription billing; `kit.signedIn(member, 'claude-cli')` is true once Claude Code is signed in, and `'anthropic'` stays the API-billed provider a Claude Code login never satisfies. Before 0.7.0 this route reported provider `anthropic`; that value is deprecated, kept as `deprecatedProvider` until 0.9.0), with login kept in Claude Code under the kit’s isolated `HOME=<stateDir>/openclaw/home` and `CLAUDE_CONFIG_DIR=<stateDir>/openclaw/home/.claude`; sign in there with `claude auth login`, then call `signIn`. Activation live-tests the route; native sign-out is through Claude Code. `apiKey` is explicit API billing (“API key (billed per use)”, `offer: false`): `signIn` asks for the key through `paste`, then engine activation verifies it. The `setup-token` choice is listed but never offered: the pinned Gateway has no app-guided sign-in for it. The kit never imports Claude credentials or implements direct Claude.ai OAuth; [Anthropic’s terms](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) apply.

package/SECURITY.md

@@ -29,9 +29,10 @@ retries after unlock. Opt-in dual wrapping opens through an owner-only host key
 its protection is only as strong as that file, which must stay outside sealed-store backups.
 Unlocked keyring-only snapshots upgrade atomically under the store's exclusive lock after verifying
 the replacement decrypts to identical contents. A store the key cannot authenticate, or whose authentic
-payload is not a snapshot, is never restored, overwritten or deleted: it is kept as
-`auth-store.sealed.unreadable-<ms>` and the engine starts signed out (`why: 'sign-in-reset'`). Other sealing
-failures still reject.
+payload is not a snapshot, is never restored, renamed, overwritten or deleted: it stays byte-identical
+at `auth-store.sealed`, blocking startup without plaintext fallback. No key rotation, reset or
+new sign-in is attempted as recovery. See [credential sealing and recovery](README.md#credential-sealing-and-threat-model)
+for the public error and host repair procedure. Other sealing failures still reject.
 
 ## Secrets at rest and in memory
 

package/dist/auth-status.d.ts

@@ -5,6 +5,7 @@ export type AuthStatus = {
         status?: unknown;
         profiles?: {
             status?: unknown;
+            expiresAt?: unknown;
         }[];
         usage?: unknown;
     })[];
@@ -15,3 +16,11 @@ export type AuthStatus = {
 /** Native Claude login stays in Claude Code. The pin's profile status does not include this synthetic auth;
  * setup detection asks the CLI itself, without handing credentials to the kit. */
 export declare function authStatus(request: GatewayTransport['request'], agentId: string, refresh?: boolean, native?: boolean): Promise<AuthStatus>;
+/** Admission snapshots, never credentials: per kit/agent/native route, at most 30s and never past reported expiry.
+ * Witness only app-owned file metadata (absence included); changed/unreadable state and auth/lifecycle mutations recheck.
+ * Remote revocation still comes from the real run's signed-out error (a local status read cannot prove it either).
+ */
+export declare function createAuthStatus(root: string, request: GatewayTransport['request']): {
+    read: (agentId: string, refresh?: boolean, native?: boolean, reuse?: boolean) => Promise<AuthStatus>;
+    invalidate: () => void;
+};

package/dist/auth-status.js

@@ -1,9 +1,13 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { signedInProviders, USABLE } from "./runs.js";
 /** Native Claude login stays in Claude Code. The pin's profile status does not include this synthetic auth;
  * setup detection asks the CLI itself, without handing credentials to the kit. */
 export async function authStatus(request, agentId, refresh = false, native = false) {
     const status = await request('models.authStatus', { agentId, ...(refresh ? { refresh: true } : {}) }, { timeoutMs: 20_000 });
-    if (!native)
-        return status;
+    return native ? nativeStatus(request, agentId, status) : status;
+}
+async function nativeStatus(request, agentId, status) {
     const detected = await request('openclaw.setup.detect', { agentId }, { timeoutMs: 20_000 }).catch(() => ({}));
     const rows = (status.providers ?? []).filter((row) => (typeof row === 'string' ? row : row.provider) !== 'claude-cli');
     if (detected.candidates?.some((candidate) => candidate.kind === 'claude-cli' && candidate.credentials === true)) {
@@ -11,3 +15,63 @@ export async function authStatus(request, agentId, refresh = false, native = fal
     }
     return { ...status, providers: rows };
 }
+/** Admission snapshots, never credentials: per kit/agent/native route, at most 30s and never past reported expiry.
+ * Witness only app-owned file metadata (absence included); changed/unreadable state and auth/lifecycle mutations recheck.
+ * Remote revocation still comes from the real run's signed-out error (a local status read cannot prove it either).
+ */
+export function createAuthStatus(root, request) {
+    const snapshots = new Map();
+    let generation = 0;
+    const invalidate = () => { generation++; snapshots.clear(); };
+    const witness = (agentId) => {
+        try {
+            return ['openclaw.json', `state/agents/${agentId}/agent/auth-profiles.json`,
+                'state/auth-profiles.json', 'state/agents/main/agent/auth-profiles.json',
+                'home/.claude/.credentials.json', 'home/.claude/.claude.json', 'home/.claude/settings.json',
+                'home/.claude.json', 'home/.codex/auth.json'].map(path => {
+                try {
+                    const s = statSync(join(root, path), { bigint: true });
+                    return `${s.dev}:${s.ino}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`;
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        return 'absent';
+                    throw error;
+                }
+            }).join('|');
+        }
+        catch {
+            return undefined;
+        } // unreadable witnesses never authorize reuse
+    };
+    const read = async (agentId, refresh = false, native = false, reuse = true) => {
+        const now = Date.now(), key = `${agentId}:${native}`, before = witness(agentId), epoch = generation;
+        for (const [key, snapshot] of snapshots)
+            if (snapshot.until <= now)
+                snapshots.delete(key);
+        const cached = snapshots.get(key);
+        if (reuse && !refresh && before !== undefined && cached?.witness === before && cached.until > now)
+            return cached.status;
+        snapshots.delete(key);
+        snapshots.delete(`${agentId}:false`);
+        const profiles = await authStatus(request, agentId, refresh);
+        const status = native ? await nativeStatus(request, agentId, profiles) : profiles;
+        if (before !== undefined && epoch === generation && witness(agentId) === before) {
+            for (const [route, answer] of (native ? [[false, profiles], [true, status]] : [[false, profiles]])) {
+                const usable = signedInProviders(answer);
+                if (!usable?.length || (route && !usable.includes('claude-cli')))
+                    continue;
+                let until = now + 30_000;
+                for (const row of answer.providers ?? [])
+                    if (typeof row !== 'string')
+                        for (const p of row.profiles ?? [])
+                            if (USABLE.has(String(p?.status)) && typeof p.expiresAt === 'number' && Number.isFinite(p.expiresAt))
+                                until = Math.min(until, p.expiresAt);
+                if (until > Date.now())
+                    snapshots.set(`${agentId}:${route}`, { status: answer, until, witness: before });
+            }
+        }
+        return status;
+    };
+    return { read, invalidate };
+}

package/dist/auth-store.d.ts

@@ -1,9 +1,13 @@
 import type { SealingAdapter } from '@byokit/secrets';
 /** True for the regenerable cache paths the collector never seals; tests assert these are all that stay at rest. */
 export declare function cached(name: string): boolean;
+/** Opening failed; the original snapshot stays in place for repair and retry. */
+export declare class AuthStoreUnreadableError extends Error {
+    readonly code = "auth-store-unreadable";
+    readonly reason: 'auth-failed' | 'invalid-snapshot';
+    constructor(reason: 'auth-failed' | 'invalid-snapshot');
+}
 export declare class AuthStore {
-    /** Set when an unreadable store was kept aside and the engine starts signed out; the kit clears it on sign-in. */
-    reset: boolean;
     private active;
     private owned;
     private queue;
@@ -23,8 +27,6 @@ export declare class AuthStore {
     private acquire;
     private release;
     private read;
-    /** Never overwrite or delete a store this kit cannot open: keep its bytes aside and start signed out. */
-    private setAside;
     private collect;
     /** Remove the live credential trees: `state` entirely (it is all credential state, including the
      *  runtime entries the collector skips), and in `home` exactly the sealed paths — regenerable caches

package/dist/auth-store.js

@@ -3,7 +3,7 @@
 // `home` — never the regenerable tool caches, transcripts and logs a signed-in home accumulates.
 // Sealing those too once produced a snapshot past the runtime string limit and aborted boot.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync, closeSync, fsyncSync, openSync } from 'node:fs';
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { EngineAlreadyRunningError, pidAlive as live } from "./engine-status.js";
 const encoder = new TextEncoder();
 const archive = (name) => /^(auth-profiles|auth-state|auth|oauth)\.json\.(migrated-.+|sqlite-import\..+\.bak)$/.test(name)
@@ -88,9 +88,17 @@ function snapshot(text) {
             throw new Error('invalid sealed credential parent');
     return s;
 }
+/** Opening failed; the original snapshot stays in place for repair and retry. */
+export class AuthStoreUnreadableError extends Error {
+    code = 'auth-store-unreadable';
+    reason;
+    constructor(reason) {
+        super("Saved sign-in could not be opened; auth-store.sealed is unchanged. Restore the original seal/key access or a working backup with its matching key, then retry.");
+        this.name = 'AuthStoreUnreadableError';
+        this.reason = reason;
+    }
+}
 export class AuthStore {
-    /** Set when an unreadable store was kept aside and the engine starts signed out; the kit clears it on sign-in. */
-    reset = false;
     active = false;
     owned = false;
     queue = Promise.resolve();
@@ -183,14 +191,14 @@ export class AuthStore {
         catch (error) {
             if (error?.code !== 'auth-failed')
                 throw error;
-            return this.setAside('could not be authenticated');
+            throw new AuthStoreUnreadableError('auth-failed');
         }
         let saved;
         try {
             saved = snapshot(text);
         }
         catch {
-            return this.setAside('is not a credential snapshot');
+            throw new AuthStoreUnreadableError('invalid-snapshot');
         }
         const upgraded = seal.upgrade?.(bytes);
         if (upgraded) {
@@ -200,15 +208,6 @@ export class AuthStore {
         }
         return saved;
     }
-    /** Never overwrite or delete a store this kit cannot open: keep its bytes aside and start signed out. */
-    setAside(why) {
-        const aside = `${this.file}.unreadable-${Date.now()}`;
-        renameSync(this.file, aside);
-        syncDir(this.o.root);
-        this.reset = true;
-        this.o.log?.(`sealed credential store ${why}; kept as ${basename(aside)}; sign in again`);
-        return undefined;
-    }
     collect() {
         const s = { v: 1, dirs: [], files: [] };
         const root = realpathSync(this.o.root);

package/dist/engine-patches.js

@@ -1,4 +1,5 @@
 // Internal artifact seam. Published patch semantics live only in engine/patches.json.
+import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { chmod, cp, open, readdir, rm } from 'node:fs/promises';
@@ -180,22 +181,27 @@ async function removeTemp(dir) {
     await walk(dir);
     await rm(dir, { recursive: true, force: true });
 }
+const flushFs = (dir) => new Promise(resolve => {
+    // One filesystem-wide syncfs through `sync -f` (~2 s vs ~110 s of per-file fsyncs on the reference btrfs host);
+    // durability rule: docs/runtime-kits.md 5.16.
+    if (process.platform !== 'linux')
+        return resolve();
+    const child = spawn('sync', ['-f', dir], { stdio: 'ignore' });
+    child.once('error', () => resolve());
+    child.once('exit', () => resolve());
+});
+// Freeze makes the tree read-only and returns its entries as the manifest; durability rule: docs/runtime-kits.md 5.16.
 async function freeze(dir) {
-    const entries = tree(dir);
-    // Bound descriptors/I/O while yielding the host event loop. Every regular file and directory is fsynced.
+    // Bound I/O while yielding the host event loop: chmod only, in batches. Links are left untouched (and keep
+    // their recorded mode); every file becomes 0444 and every directory 0555, exactly what the manifest records.
+    const entries = tree(dir).map(entry => entry.kind === 'link' ? entry : { ...entry, mode: entry.kind === 'dir' ? 0o555 : 0o444 });
     const paths = [...entries.filter(e => e.kind === 'file'), ...entries.filter(e => e.kind === 'dir').reverse()];
     for (let i = 0; i < paths.length; i += 16)
         await Promise.all(paths.slice(i, i + 16).map(async (entry) => {
-            const path = join(dir, entry.path);
-            await chmod(path, entry.kind === 'dir' ? 0o555 : 0o444);
-            const fd = await open(path, 'r');
-            try {
-                await fd.sync();
-            }
-            finally {
-                await fd.close();
-            }
+            await chmod(join(dir, entry.path), entry.mode);
         }));
+    await flushFs(dir);
+    return entries;
 }
 export function engineSetName(set) { return `${sha256(set.upstream.integrity).slice(0, 16)}-${set.id}`; }
 export async function prepareEngineSet(engineDir, set, install, installMatches) {
@@ -257,8 +263,8 @@ export async function prepareEngineSet(engineDir, set, install, installMatches)
             atomic(path, after);
         }
         metadata(tmp, set);
-        await freeze(tmp);
-        const bytes = JSON.stringify(tree(tmp));
+        const entries = await freeze(tmp);
+        const bytes = JSON.stringify(entries);
         // Root alone is writable while publishing metadata, then made read-only too.
         await chmod(tmp, 0o700);
         atomic(join(tmp, '.byokit-tree'), bytes);

package/dist/engine.js

@@ -5,7 +5,7 @@ import { createServer } from 'node:net';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
-import { AuthStore } from "./auth-store.js";
+import { AuthStore, AuthStoreUnreadableError } from "./auth-store.js";
 import { EngineAlreadyRunningError, pidAlive, StartedProcesses } from "./engine-status.js";
 import { EnginePatchError, atomic, prepareEngineSet, processStartTime, readPatchSet, verifyEngineSet } from "./engine-patches.js";
 import { ENGINE_VERSION } from "./constants.js";
@@ -102,6 +102,8 @@ export class Engine {
                 this.patchSet = null;
                 this.state('failed', 'engine-patch');
             }
+            if (error instanceof AuthStoreUnreadableError)
+                this.state('failed', 'auth-store-unreadable');
             throw error;
         });
         this.prepared = pending;
@@ -293,6 +295,8 @@ export class Engine {
         catch (error) {
             if (this.locked(error))
                 return undefined;
+            if (error instanceof AuthStoreUnreadableError)
+                this.state('failed', 'auth-store-unreadable');
             throw error;
         }
         try {

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
+export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
 export type { GatewayMethods } from './generated/methods.ts';
 export type { JsonValue } from './output.ts';
 export type { RouteFacts, RouteView } from './routes.ts';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
 export type { AddKeyResult } from './keys.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';
+export { AuthStoreUnreadableError } from './auth-store.ts';
 export { EngineAlreadyRunningError } from './engine-status.ts';
 export { readAgentDayUsage } from './day-usage.ts';
 export type { AgentDayUsage, DayUsageClient, EngineStartedCharge, EngineStartedKind } from './day-usage.ts';

package/dist/index.js

@@ -3,6 +3,7 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from "./constants.js";
 export { OpenClawKit } from "./kit.js";
 export { stateWords, toAccountView, words } from "./words.js";
+export { AuthStoreUnreadableError } from "./auth-store.js";
 export { EngineAlreadyRunningError } from "./engine-status.js";
 export { readAgentDayUsage } from "./day-usage.js";
 export { readAgentUsage, agentUsageOf } from "./usage.js";

package/dist/kit.d.ts

@@ -2,7 +2,7 @@ import type { SealingAdapter } from '@byokit/secrets';
 import { type AddKeyResult } from './keys.ts';
 import { type RouteView } from './routes.ts';
 import type { BrowserHost, BrowserOptions } from './browser.ts';
-import type { Approval, CallOptions, Decision, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, Member, RunEnd, RunEvent, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
+import type { Approval, CallOptions, Decision, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, LearningCapture, LearningMode, Member, RunEnd, RunEvent, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
 export type KitOptions = {
     stateDir: string;
     authSeal?: SealingAdapter;
@@ -55,6 +55,7 @@ export declare class OpenClawKit {
     private members?;
     private readonly bridge;
     private readonly keys;
+    private readonly admission;
     private readonly approvalsCtl;
     private listeners;
     private off;
@@ -99,6 +100,7 @@ export declare class OpenClawKit {
     }>;
     private signInCtx;
     routes(): RouteView[];
+    providerStatus(member: Member): Promise<string[] | undefined>;
     providers(member: Member): Promise<string[]>;
     signedIn(member: Member, provider: string): Promise<boolean>;
     signIn(member: Member, o: SignInOptions, on: (v: SignInView) => void): {
@@ -140,6 +142,10 @@ export declare class OpenClawKit {
     memoryLimited(member: Member): boolean;
     getConfigKey(key: string): unknown;
     setConfigKey(key: string, value: unknown): unknown;
+    learning(): LearningCapture;
+    setLearning(mode: LearningMode | 'default'): LearningCapture;
+    restoreLearning(captured: LearningCapture): LearningCapture;
+    private assertLearningWritable;
     doctorContext(): {
         entry: string;
         env: Record<string, string>;

package/dist/kit.js

@@ -11,15 +11,18 @@ import { gatewayTransport } from "./transport.js";
 import { createMembers } from "./members.js";
 import { keyAgentId, KEY_PREFIX, MEMBER_ID } from "./members.js";
 import { confirmRetainedLogin as confirmLogin, migrateRetainedLogin as migrateLogin } from "./migrate.js";
-import { createRuns } from "./runs.js";
+import { createRuns, signedInProviders } from "./runs.js";
+import { createAuthStatus } from "./auth-status.js";
 import { outputSchema } from "./output.js";
 import { createKeys } from "./keys.js";
 import { routes as routeTable } from "./routes.js";
-import { providers as engineProviders, signIn as startSignIn, signOut as engineSignOut } from "./signin.js";
+import { signIn as startSignIn, signOut as engineSignOut } from "./signin.js";
 import { reconcileConfig, browserToolPolicySafe, browserProfileAcknowledged, browserSessionMayRun, memoryLimited as configMemoryLimited, configKeyPath, readConfigKey, writeConfigKey } from "./config.js";
 import { createBrowserHost } from "./browser/host.js";
 import { fileSignInStore } from "./browser/store.js";
 import { launchBroker } from "./browser/broker.js";
+/** The engine's learning-mode config key (5.6 "Engine learning state"). */
+const LEARNING_KEY = 'skills.workshop.autonomous.mode';
 const operatorMethods = new Set([
     'agent',
     'agent.identity.get',
@@ -428,6 +431,7 @@ export class OpenClawKit {
     // Only the socket itself is per-connection. Approvals always reaches the live transport through this.request().
     bridge;
     keys;
+    admission;
     approvalsCtl;
     listeners = new Set();
     off = [];
@@ -644,6 +648,7 @@ export class OpenClawKit {
             ...(o.browser ? { browserConfig: () => this.browserConfig() } : {}),
             gateBuiltins: o.gateBuiltins !== false, spawnEngine: o.spawnEngine !== false,
             onState: (s) => this.setState(s), onExit: () => this.closed('engine exited') });
+        this.admission = createAuthStatus(this.engine.root, (method, params, options) => this.request()(method, params, options));
         this.keys = createKeys({ root: this.engine.root,
             restarting: () => this.current.phase === 'restarting' || this.current.phase === 'starting',
             request: (method, params, options) => this.request()(method, params, options),
@@ -684,6 +689,8 @@ export class OpenClawKit {
         slot.bridge = this.bridge;
     }
     setState(s) {
+        if (s.phase !== 'ready')
+            this.admission?.invalidate();
         this.current = { ...s, ...(this.engine.patchSet !== undefined ? { patchSet: this.engine.patchSet } : {}) };
         this.o.onState?.(this.current);
     }
@@ -736,7 +743,7 @@ export class OpenClawKit {
             await this.bridge.start();
             this.off.push(transport.onEvent((e) => this.approvalsCtl.handleEvent(e)));
             this.failures = 0;
-            this.setState(this.engine.authStore.reset ? { phase: 'ready', why: 'sign-in-reset' } : { phase: 'ready' });
+            this.setState({ phase: 'ready' });
             if (this.o.browser)
                 await this.checkBrowserTools();
             // Replays the engine's native approval lists over the now-live transport (N9).
@@ -753,6 +760,10 @@ export class OpenClawKit {
                 this.setState({ phase: 'failed', why: 'engine-already-running' });
                 throw error;
             }
+            if (error instanceof Error && 'code' in error && error.code === 'auth-store-unreadable') {
+                this.setState({ phase: 'failed', why: 'auth-store-unreadable' });
+                throw error;
+            }
             if (patchFailure) {
                 this.setState({ phase: 'failed', why: 'engine-patch' });
                 throw error;
@@ -765,6 +776,7 @@ export class OpenClawKit {
         }
     }
     async disconnect() {
+        this.admission.invalidate();
         this.off.splice(0).forEach((fn) => fn());
         const transport = this.transport;
         this.transport = undefined;
@@ -812,7 +824,14 @@ export class OpenClawKit {
     request() {
         if (!this.transport || this.current.phase !== 'ready')
             throw new Error('gateway not ready');
-        return this.transport.request.bind(this.transport);
+        const transport = this.transport;
+        return (method, params, options) => {
+            const changesAuth = /^(models\.authLogout|openclaw\.setup\.(auth\.start|activate)|wizard\.(next|cancel)|config\.(apply|patch|set)|agents\.(create|update|delete)|secrets\.(reload|store\.(set|delete))|byokit\.keys)$/.test(method);
+            if (!changesAuth || (method === 'byokit.keys' && params?.action === 'ready'))
+                return transport.request(method, params, options);
+            this.admission.invalidate();
+            return Promise.resolve().then(() => transport.request(method, params, options)).finally(() => this.admission.invalidate());
+        };
     }
     call(method, params, o) {
         if (this.o.browser && /^(config\.(apply|patch|set)|agents\.(create|update|delete)|plugins\.(install|uninstall|setEnabled|refresh))$/.test(method))
@@ -869,27 +888,26 @@ export class OpenClawKit {
     // sign-in (5.7): every body here is the module's, with this kit's transport, members and ports.
     signInCtx() {
         return { request: (method, params, o) => this.request()(method, params, o),
+            // Public readiness/sign-in reads stay live; their fresh result can prepare the next run's admission.
+            authStatus: (agentId, refresh, native) => this.admission.read(agentId, refresh, native, false),
             ensure: (member) => this.ensureMember(member), callbackPort: this.o.callbackPort ?? 1455,
             onDisconnect: (fn) => { this.signInDisconnects.add(fn); return () => { this.signInDisconnects.delete(fn); }; } };
     }
     routes() {
         return routeTable();
     }
+    async providerStatus(member) {
+        const { agentId } = await this.ensureMember(member);
+        return signedInProviders(await this.admission.read(agentId, false, true, false));
+    }
     providers(member) {
-        return engineProviders(this.signInCtx(), member);
+        return this.providerStatus(member).then((names) => names ?? []);
     }
     signedIn(member, provider) {
-        return engineProviders(this.signInCtx(), member).then((names) => names.includes(provider)).catch(() => false);
+        return this.providers(member).then((names) => names.includes(provider)).catch(() => false);
     }
     signIn(member, o, on) {
-        return startSignIn(this.signInCtx(), member, o, (view) => {
-            if (view.state === 'done' && this.engine.authStore.reset) {
-                this.engine.authStore.reset = false;
-                if (this.current.phase === 'ready')
-                    this.setState({ phase: 'ready' });
-            }
-            on(view);
-        });
+        return startSignIn(this.signInCtx(), member, o, on);
     }
     signOut(member, provider) {
         return engineSignOut(this.signInCtx(), member, provider);
@@ -910,6 +928,8 @@ export class OpenClawKit {
     runs() {
         return createRuns({
             request: (method, params, o) => this.request()(method, params, o),
+            authStatus: this.admission.read,
+            invalidateAuth: this.admission.invalidate,
             onEvent: (fn) => {
                 this.listeners.add(fn);
                 return () => {
@@ -967,7 +987,7 @@ export class OpenClawKit {
     steer(sessionKey, text, o) {
         return this.runs().steer(this.runKey(sessionKey, o), text);
     }
-    abort(sessionKey, o) {
+    async abort(sessionKey, o) {
         return this.runs().abort(this.runKey(sessionKey, o));
     }
     // approvals (5.9)
@@ -1024,5 +1044,38 @@ export class OpenClawKit {
             atomic(path, next);
         return previous;
     }
+    // The engine's learning switch, named: a typed veneer over the narrow pair above, file-backed and boot-free
+    // (5.6 "Engine learning state"). The engine itself falls back silently on a stored value outside its enum;
+    // these refuse, so a typo or a corrupted file surfaces instead of quietly flipping learning.
+    learning() {
+        const value = this.getConfigKey(LEARNING_KEY);
+        if (value === undefined)
+            return { present: false };
+        if (value !== 'off' && value !== 'propose' && value !== 'auto')
+            throw new Error(`learning: stored ${LEARNING_KEY} is ${JSON.stringify(value)}, not one of off|propose|auto`);
+        return { present: true, mode: value };
+    }
+    setLearning(mode) {
+        if (mode !== 'off' && mode !== 'propose' && mode !== 'auto' && mode !== 'default')
+            throw new Error(`setLearning: unknown learning mode ${JSON.stringify(mode)}, expected off|propose|auto|default`);
+        this.assertLearningWritable('setLearning');
+        const previous = this.learning();
+        this.setConfigKey(LEARNING_KEY, mode === 'default' ? undefined : mode);
+        return previous;
+    }
+    restoreLearning(captured) {
+        if (captured.present && captured.mode !== 'off' && captured.mode !== 'propose' && captured.mode !== 'auto')
+            throw new Error(`restoreLearning: unknown learning mode ${JSON.stringify(captured.mode)}, expected off|propose|auto`);
+        this.assertLearningWritable('restoreLearning');
+        this.setConfigKey(LEARNING_KEY, captured.present ? captured.mode : undefined);
+        const read = this.learning();
+        if (read.present !== captured.present || (read.present && captured.present && read.mode !== captured.mode))
+            throw new Error(`learning restore readback mismatch: captured ${JSON.stringify(captured)}, read ${JSON.stringify(read)}`);
+        return read;
+    }
+    assertLearningWritable(op) {
+        if (this.o.config?.skills !== undefined)
+            throw new Error(`${op}: KitOptions.config also passes skills; that option wins at every boot (5.6)`);
+    }
     doctorContext() { return this.engine.doctorContext(); }
 }

package/dist/link.js

@@ -10,9 +10,7 @@ import { reach } from '@byokit/discover';
 import { ENGINE_VERSION } from "./constants.js";
 import { b64urlDecode, b64urlEncode, sealNotice } from "./notices.js";
 import { routeFor } from "./routes.js";
-import { authStatus } from "./auth-status.js";
 import { outputSchema } from "./output.js";
-import { signedInProviders } from "./runs.js";
 import { stateWords, words } from "./words.js";
 const VIEW_OPS = new Set(['oc.state', 'oc.routes', 'oc.signin.view', 'oc.sessions', 'oc.approvals', 'oc.events',
     'oc.browser.state', 'oc.browser.signins', 'oc.browser.thumb']);
@@ -228,20 +226,6 @@ export function openclawLink(kit, o) {
         return null;
     };
     const endReason = (error) => error instanceof PublicLinkError ? error.message.slice(0, 200) : 'failed';
-    const signIns = async (member) => {
-        try {
-            const { agentId } = await kit.ensureMember(member);
-            const status = await authStatus((method, params, options) => {
-                if (method === 'models.authStatus')
-                    return kit.call(method, params, options);
-                return kit.call('openclaw.setup.detect', params, options);
-            }, agentId, false, true);
-            return signedInProviders(status);
-        }
-        catch {
-            return undefined;
-        }
-    };
     const handle = async (req, grant) => {
         const member = memberOf(grant);
         if (grant.role === 'view' && !VIEW_OPS.has(req.op))
@@ -314,7 +298,7 @@ export function openclawLink(kit, o) {
             case 'oc.state': {
                 // signedIn: the providers the device member is usably signed in to (an expired or unfinished sign-in is not),
                 // only while the engine can say: absent is unknown, never "none".
-                const signedIn = kit.state.phase === 'ready' ? await signIns(member) : undefined;
+                const signedIn = kit.state.phase === 'ready' ? await kit.providerStatus(member).catch(() => undefined) : undefined;
                 return { state: kit.state, words: stateWords(kit.state), version: KIT_VERSION, engine: ENGINE_VERSION,
                     ...(signedIn ? { signedIn } : {}) };
             }

package/dist/members.js

@@ -2,8 +2,13 @@ import { join } from 'node:path';
 export const MEMBER_ID = /^[a-z][a-z0-9-]{0,31}$/;
 export const KEY_PREFIX = 'byokit-key-';
 export const keyAgentId = (member) => `${KEY_PREFIX}${member}`;
+// The engine answers agents.create before its roster hot-reload applies (up to ~113 ms observed), so a turn sent
+// at once fails as 'unknown agent id'. ensure resolves only once agents.list shows the member.
+const VISIBLE_TIMEOUT_MS = 5_000;
+const VISIBLE_POLL_MS = 25;
 export function createMembers(ctx) {
     const cache = new Map();
+    const listed = (member) => ctx.request('agents.list').then((list) => list.agents.some((agent) => agent.id === member));
     return { ensure(member) {
             if (!MEMBER_ID.test(member) || member.startsWith(KEY_PREFIX))
                 return Promise.reject(new Error(`invalid member id: ${member}`));
@@ -12,9 +17,15 @@ export function createMembers(ctx) {
                 return existing;
             const workspace = join(ctx.root, 'workspaces', member);
             const result = (async () => {
-                const list = await ctx.request('agents.list');
-                if (!list.agents.some((agent) => agent.id === member))
+                if (!await listed(member)) {
                     await ctx.request('agents.create', { name: member, workspace });
+                    const deadline = Date.now() + VISIBLE_TIMEOUT_MS;
+                    while (!await listed(member)) {
+                        if (Date.now() >= deadline)
+                            throw new Error(`agent ${member} is not listed by agents.list after agents.create`);
+                        await new Promise((resolve) => setTimeout(resolve, VISIBLE_POLL_MS));
+                    }
+                }
                 return { agentId: member, workspace };
             })();
             cache.set(member, result);

package/dist/runs.d.ts

@@ -1,6 +1,8 @@
 import type { Bridge } from './bridge.ts';
+import { authStatus } from './auth-status.ts';
 import { outputSchema, type OutputSchema, type SchemaOutput } from './output.ts';
 import type { GatewayTransport, Member, RunEnd, RunEvent, RunSpec } from './types.ts';
+export declare const USABLE: Set<string>;
 /**
  * The providers a `models.authStatus` answer shows usable (the rule a picked account is checked by), lowercased and
  * unique; undefined while the engine has no prepared status (unknown, not none).
@@ -8,6 +10,8 @@ import type { GatewayTransport, Member, RunEnd, RunEvent, RunSpec } from './type
 export declare function signedInProviders(status: unknown): string[] | undefined;
 export declare function createRuns(ctx: {
     request: GatewayTransport['request'];
+    authStatus?: (agentId: string, refresh: boolean, native: boolean) => ReturnType<typeof authStatus>;
+    invalidateAuth?: () => void;
     onEvent: GatewayTransport['onEvent'];
     ensure(member: Member): Promise<{
         agentId: string;

package/dist/runs.js

@@ -11,7 +11,7 @@ const WAIT_CLIENT_MS = 3_610_000;
 // The `agent` request's final frame lands with the run's end; a run already over waits no longer than this for it.
 const FINAL_GRACE_MS = 5_000;
 const STATUS_MS = 5_000;
-const USABLE = new Set(['ok', 'expiring', 'static']);
+export const USABLE = new Set(['ok', 'expiring', 'static']);
 const usable = (row) => typeof row === 'string'
     || (Array.isArray(row.profiles) && row.profiles.length > 0 ? row.profiles.some((p) => USABLE.has(String(p?.status)))
         : row.status === undefined || USABLE.has(String(row.status)));
@@ -80,6 +80,12 @@ export function createRuns(ctx) {
             return undefined;
         }
     };
+    const failure = (message) => {
+        const classified = classify(message);
+        if (classified.kind === 'signed-out')
+            ctx.invalidateAuth?.();
+        return { ok: false, ...classified, message };
+    };
     const run = async (spec, on, keyAgent, preparedOutput) => {
         // Member boundary first: a member never speaks in another member's session, refused before any request.
         if (!spec.sessionKey.startsWith(`agent:${spec.member}:`))
@@ -112,7 +118,10 @@ export function createRuns(ctx) {
             if (p.stream === 'lifecycle' && p.data?.phase === 'end'
                 && p.data.aborted === true)
                 abortedByEngine = true;
-            if (p.stream === 'assistant' && typeof p.data?.text === 'string') {
+            if (p.stream === 'thinking' && count(p.data?.progressTokens)) {
+                on?.({ type: 'thinking', tokens: p.data.progressTokens });
+            }
+            else if (p.stream === 'assistant' && typeof p.data?.text === 'string') {
                 last = p.data.text;
                 on?.({ type: 'text', text: p.data.text });
             }
@@ -135,7 +144,8 @@ export function createRuns(ctx) {
                 // The picked account must be the one called: check it is signed in for this member before the run, since
                 // the engine would otherwise fail the run only after admitting it. An explicit provider/model is strict on
                 // the pinned engine (never another provider or model), so this check plus the override is the guarantee.
-                const status = (refresh) => authStatus(ctx.request, agentId, refresh, picked.provider === 'claude-cli');
+                const status = (refresh) => ctx.authStatus ? ctx.authStatus(agentId, refresh, picked.provider === 'claude-cli')
+                    : authStatus(ctx.request, agentId, refresh, picked.provider === 'claude-cli');
                 let auth = await status(false);
                 if (auth.unavailable)
                     auth = await status(true); // no prepared snapshot yet: build it once
@@ -151,8 +161,12 @@ export function createRuns(ctx) {
             const ack = new Promise((resolve) => { accepted = resolve; });
             // The run id is taken as the accepted frame lands, so no event read after it is missed.
             const onAccepted = (payload) => {
-                if (isRecord(payload) && typeof payload.runId === 'string')
+                if (isRecord(payload) && typeof payload.runId === 'string') {
+                    const first = !runId;
                     runId = payload.runId;
+                    if (first && payload.status === 'accepted')
+                        on?.({ type: 'started' });
+                }
                 accepted(payload);
             };
             const final = ctx.request('agent', {
@@ -199,11 +213,11 @@ export function createRuns(ctx) {
                 return { ok: false, aborted: true };
             const message = typeof result.error === 'string' ? result.error
                 : typeof result.message === 'string' ? result.message : '';
-            return { ok: false, ...classify(message), message };
+            return failure(message);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            return { ok: false, ...classify(message), message };
+            return failure(message);
         }
         finally {
             ended = true;
@@ -214,6 +228,6 @@ export function createRuns(ctx) {
     return {
         run,
         steer: (k, t) => ctx.request('sessions.steer', { sessionKey: k, message: t }),
-        abort: (k) => ctx.request('chat.abort', { sessionKey: k }),
+        abort: async (k) => { await ctx.request('chat.abort', { sessionKey: k }); },
     };
 }

package/dist/signin.d.ts

@@ -1,6 +1,8 @@
+import { authStatus } from './auth-status.ts';
 import type { GatewayTransport, Member, SignInOptions, SignInView } from './types.ts';
 export type SignInCtx = {
     request: GatewayTransport['request'];
+    authStatus?: (agentId: string, refresh: boolean, native: boolean) => ReturnType<typeof authStatus>;
     ensure(member: Member): Promise<{
         agentId: string;
     }>;

package/dist/signin.js

@@ -430,7 +430,8 @@ export function signIn(ctx, member, o, on) {
 /** Usable provider profiles plus native Claude Code readiness reported by the engine. */
 export async function providers(ctx, member, refresh) {
     const { agentId } = await ctx.ensure(member);
-    return signedInProviders(await authStatus(ctx.request, agentId, refresh, true)) ?? [];
+    return signedInProviders(await (ctx.authStatus ? ctx.authStatus(agentId, refresh ?? false, true)
+        : authStatus(ctx.request, agentId, refresh, true))) ?? [];
 }
 export async function signOut(ctx, member, provider) {
     const { agentId } = await ctx.ensure(member);

package/dist/testing/contract.js

@@ -65,6 +65,19 @@ export function openclawContract(make, o) {
             await kit.stop();
         }
     });
+    test('contract: a turn sent right after ensureMember is not an unknown agent', async () => {
+        const { kit } = await make();
+        try {
+            // The roster applies a beat after agents.create answers (engine hot-reload); ensureMember must wait
+            // until agents.list shows the member, so the first turn is not rejected as 'unknown agent id'.
+            await kit.ensureMember('m1');
+            const end = await kit.run({ member: 'm1', sessionKey: 'agent:m1:contract:6', message: 'hello fresh member' });
+            assert.ok(end.ok, JSON.stringify(end));
+        }
+        finally {
+            await kit.stop();
+        }
+    });
     test('contract: a member cannot run in another member\'s session', async () => {
         const { kit } = await make();
         try {

package/dist/testing/fake-gateway.d.ts

@@ -23,4 +23,6 @@ export type FakeGateway = {
 } & {
     transport: GatewayTransport;
 };
-export declare function fakeGateway(script?: FakeScript): FakeGateway;
+export declare function fakeGateway(script?: FakeScript, o?: {
+    rosterApplyMs?: number;
+}): FakeGateway;

package/dist/testing/fake-gateway.js

@@ -94,7 +94,7 @@ function bridgeRequest(path, message) {
         });
     });
 }
-export function fakeGateway(script) {
+export function fakeGateway(script, o) {
     const calls = [];
     const failures = new Map();
     const handlers = new Map();
@@ -212,8 +212,15 @@ export function fakeGateway(script) {
             agents: [...agents.values()].map((agent) => ({ id: agent.id })),
         }),
         'agents.create': (p) => {
-            ensureAgent(String(p.name), p.workspace ? String(p.workspace) : undefined);
-            return { id: String(p.name) };
+            const id = String(p.name);
+            const workspace = p.workspace ? String(p.workspace) : undefined;
+            // With rosterApplyMs the fake mirrors the pinned engine: create answers before the roster hot-reload
+            // makes the agent visible to agents.list (Crewhouse saw ~113 ms).
+            if (o?.rosterApplyMs)
+                setTimeout(() => ensureAgent(id, workspace), o.rosterApplyMs);
+            else
+                ensureAgent(id, workspace);
+            return { id };
         },
         'models.authStatus': (p) => ({
             providers: (agents.get(String(p?.agentId ?? 'main'))?.providers ?? []).map((provider) => ({ provider })),

package/dist/types.d.ts

@@ -2,6 +2,15 @@ import type { OutputSchema } from './output.ts';
 import type { GatewayEventName, GatewayEventPayload } from './generated/events.ts';
 export type { OutputSchema, SchemaOutput } from './output.ts';
 export type Member = string;
+/** The engine's learning mode: config key `skills.workshop.autonomous.mode` (5.6). */
+export type LearningMode = 'off' | 'propose' | 'auto';
+/** Exactly what `learning()` saw: absence is a value, not "probably default" (5.6). */
+export type LearningCapture = {
+    present: false;
+} | {
+    present: true;
+    mode: LearningMode;
+};
 export interface ToolSpec {
     name: string;
     description: string;
@@ -47,6 +56,11 @@ export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | und
     register?: boolean;
 }
 export type RunEvent = {
+    type: 'started';
+} | {
+    type: 'thinking';
+    tokens: number;
+} | {
     type: 'text';
     text: string;
 } | {
@@ -127,7 +141,7 @@ export type Decision = {
 };
 export type KitState = {
     phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update' | 'locked';
-    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version' | 'engine-already-running' | 'engine-patch' | 'sign-in-reset';
+    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version' | 'engine-already-running' | 'engine-patch' | 'sign-in-reset' | 'auth-store-unreadable';
     retryAt?: number;
     patchSet?: string | null;
 };
@@ -160,7 +174,7 @@ export type Route = {
         via: 'browser' | 'code';
     };
     /** @deprecated This route's `provider` before 0.7.0 (`anthropic` on `anthropic-cli`); use `provider` (`claude-cli`).
-     * Discovery data only, never a sign-in or `signedIn` id. Removed in 0.8.0, when that route's id becomes
+     * Discovery data only, never a sign-in or `signedIn` id. Removed in 0.9.0, when that route's id becomes
      * `claude-cli:cli:anthropic-cli`. */
     deprecatedProvider?: string;
     billingFrom?: 'source' | 'host';

package/dist/words.js

@@ -21,6 +21,8 @@ export function stateWords(s) {
     // 'stopped' is never on screen (4.3 covers what a person can see), so 5.14 has no row for it.
     if (s.phase === 'failed' && s.why === 'engine-already-running')
         return words('engine.alreadyRunning');
+    if (s.why === 'auth-store-unreadable')
+        return words('engine.authStoreUnreadable');
     if (s.why === 'sign-in-reset')
         return words('engine.signInAgain');
     return s.phase === 'stopped' ? '' : words(PHASE_WORDS[s.phase]);

package/dist/words.json

@@ -3,6 +3,7 @@
     "engine.starting": "Starting up…",
     "engine.repairing": "Fixing a small problem with the setup. This takes a moment.",
     "engine.locked": "Your saved sign-in is locked. Unlock your password storage, then try again.",
+    "engine.authStoreUnreadable": "Your saved sign-in couldn't be opened. It is unchanged. Restore its original key or a working backup, then retry.",
     "engine.signInAgain": "Your saved sign-in couldn't be opened, so it was kept aside. Sign in again.",
     "engine.ready": "Ready.",
     "engine.restarting": "Something stopped. Starting it again by itself.",

package/engine/patches.json

@@ -1,6 +1,6 @@
 {
   "v": 1,
-  "id": "171ce088cd516dcf",
+  "id": "ee8913bf172b63b2",
   "upstream": {
     "name": "openclaw",
     "version": "2026.8.1",
@@ -54,6 +54,17 @@
           "replace": "// BYOKit: caller-owned task prefixes never acquire automatic restart recovery ownership.\nconst byokitAppOwnedSessionPrefixes = (() => {\n\ttry {\n\t\tconst prefixes = JSON.parse(process.env.BYOKIT_APP_OWNED_SESSION_PREFIXES ?? \"[]\");\n\t\treturn Array.isArray(prefixes) && prefixes.every((prefix) => {\n\t\t\tconst agent = typeof prefix === \"string\" && /^agent:([a-z0-9-]+):/.exec(prefix);\n\t\t\treturn agent && !`agent:${agent[1]}:main`.startsWith(prefix);\n\t\t}) ? prefixes : [];\n\t} catch { return []; }\n})();\nfunction isMainRestartRecoveryCandidate(entry, sessionKey) {\n\tif (byokitAppOwnedSessionPrefixes.some((prefix) => sessionKey.startsWith(prefix))) return false;"
         }
       ]
+    },
+    {
+      "path": "dist/prepare.runtime-y2eXKhY3.js",
+      "before": "001ebad506ae9550984e3256eb1a632daa2e3ad2b6e76e2ff903979eed3d04fc",
+      "after": "f9955de9dbdc30a6675802e940015ad77db3016e84c22a7e282cc5ed4ee350f8",
+      "edits": [
+        {
+          "find": "let systemPrompt = !skipsTurnPreparation ? backendResolved.transformSystemPrompt?.({\n\t\t\tconfig: params.config,\n\t\t\tworkspaceDir,\n\t\t\tprovider: params.provider,\n\t\t\tmodelId,\n\t\t\tmodelDisplay,\n\t\t\tagentId: sessionAgentId,\n\t\t\tsystemPrompt: builtSystemPrompt\n\t\t}) ?? builtSystemPrompt : builtSystemPrompt;\n",
+          "replace": "let systemPrompt = !skipsTurnPreparation ? backendResolved.transformSystemPrompt?.({\n\t\t\tconfig: params.config,\n\t\t\tworkspaceDir,\n\t\t\tprovider: params.provider,\n\t\t\tmodelId,\n\t\t\tmodelDisplay,\n\t\t\tagentId: sessionAgentId,\n\t\t\tsystemPrompt: builtSystemPrompt\n\t\t}) ?? builtSystemPrompt : builtSystemPrompt;\n\t\t// BYOKit: Claude wire names for the Tooling list (ch-cli-tool-prefix). The Claude wire catalog\n\t\t// exposes OpenClaw tools as mcp__openclaw__<name>, so the printed Tooling list on that route must\n\t\t// use those exact names. Every other route keeps the stock prompt byte-identical; already-prefixed\n\t\t// names are never prefixed again. Order, summaries and error semantics are unchanged.\n\t\tif (!skipsTurnPreparation && isClaudeCli && promptTools.length > 0) {\n\t\t\tconst byokitBareNames = new Set(promptTools.map((tool) => tool?.name).filter((name) => typeof name === \"string\" && name.length > 0 && !name.startsWith(\"mcp__openclaw__\")));\n\t\t\tif (byokitBareNames.size > 0) {\n\t\t\t\tconst byokitLines = systemPrompt.split(\"\\n\");\n\t\t\t\tlet byokitInTooling = false;\n\t\t\t\tlet byokitToolingArmed = false;\n\t\t\t\tfor (let byokitI = 0; byokitI < byokitLines.length; byokitI++) {\n\t\t\t\t\tconst byokitLine = byokitLines[byokitI];\n\t\t\t\t\tif (byokitLine.startsWith(\"## \")) {\n\t\t\t\t\t\tbyokitInTooling = byokitLine === \"## Tooling\";\n\t\t\t\t\t\tbyokitToolingArmed = false;\n\t\t\t\t\t} else if (byokitInTooling && !byokitToolingArmed) {\n\t\t\t\t\t\tif (byokitLine === \"Tools policy-filtered. Names case-sensitive; call exact.\") byokitToolingArmed = true;\n\t\t\t\t\t} else if (byokitInTooling && byokitToolingArmed && byokitLine.startsWith(\"- \")) {\n\t\t\t\t\t\tconst byokitMatch = /^- (\\S+?)(:.*)?$/.exec(byokitLine);\n\t\t\t\t\t\tif (byokitMatch && byokitBareNames.has(byokitMatch[1])) byokitLines[byokitI] = `- mcp__openclaw__${byokitMatch[1]}${byokitMatch[2] ?? \"\"}`;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tsystemPrompt = byokitLines.join(\"\\n\");\n\t\t\t}\n\t\t}\n"
+        }
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.6.3",
+  "version": "0.9.0",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -60,14 +60,14 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.7.1",
-    "@byokit/relay": "0.5.3",
+    "@byokit/link": "0.8.0",
+    "@byokit/relay": "0.6.0",
     "@byokit/discover": "0.6.0",
     "@byokit/seal": "0.3.0",
     "@byokit/secrets": "0.5.0",
     "@openclaw/gateway-client": "2026.9.6",
     "@openclaw/gateway-protocol": "2026.8.1",
-    "ws": "8.21.3"
+    "ws": "8.22.0"
   },
   "devDependencies": {
     "@byokit/ui-core": "0.6.0"