@byokit/openclaw 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## 0.6.3 (2026-10-07)
+
+- Dependency update: pins @byokit/relay 0.5.3.
+- Dependency update: pins @byokit/link 0.7.1.
+
+- FIX: Route `anthropic-cli` now reports provider `claude-cli`, the id `signedIn`, `providers()` and runs already use for a Claude Code login, so `kit.signedIn(member, route.provider)` answers true once Claude Code is signed in. **Deprecated:** the old provider `anthropic` on this route; it stays readable as `route.deprecatedProvider` (`'anthropic'`) through 0.7.x and is removed in 0.8.0. Match this route by `provider === 'claude-cli'` (or by `choice === 'anthropic-cli'`). The route id `anthropic:cli:anthropic-cli` is kept through 0.7.x and becomes `claude-cli:cli:anthropic-cli` in 0.8.0; choice `anthropic-cli` and the `{ provider: 'claude-cli', via: 'browser' }` link selector are unchanged. `anthropic` remains the API-billed provider only: a Claude Code login never makes `signedIn(member, 'anthropic')` true.
+FIX: Engine start on macOS no longer sticks on a dead-but-unreaped guard process. `pidAlive` detects zombies portably — `ps` state where there is no `/proc` — instead of Linux-only `/proc`, so a stale guard reads as stopped and start can recover. A live pid still reads as owned, an invalid guard still reads as ambiguous, and anything unexpected from the probe keeps the guard. Linux answers are unchanged.
+- FIX: Code sign-ins whose pinned engine prints the code only into a note now hand the caller the code, link, expiry (`expiresAt`) and instructions (`message`) in the same `SignInView` shape as structured codes, and wait out device approval instead of failing with `gateway request timeout for wizard.next` after two minutes.
+- The O16 day-usage engine tests no longer fail when a run straddles UTC midnight: a case that could still be running at midnight starts just after it, so the day (and month) it reads is the day its engine stamps charges in.
+- The `relay` option takes anything with `RelayClient`'s `notify`, so a host can hand the kit a relay it opens after `Host.open` (the client needs the open host). A `RelayClient` still fits; behaviour is unchanged.
+- FIX: The sealed credential store is written as `v: 1` again. 0.6.2's `v: 2` tag made every earlier kit (through 0.6.1) refuse an intact store with `invalid sealed credential store`, so a host rolled back to an earlier kit could not start and lost its saved sign-in. `v: 2` stores still restore and re-seal as `v: 1`.
+- A saved store the key cannot open (a different key, damaged or tampered bytes) or whose payload is not a credential snapshot no longer blocks engine start: it is kept as `auth-store.sealed.unreadable-<ms>` (never overwritten or deleted), the engine starts signed out, and the kit reports `{ phase: 'ready', why: 'sign-in-reset' }` with the words "Your saved sign-in couldn't be opened, so it was kept aside. Sign in again." until a sign-in through the kit completes.
+- FIX: Every wizard `text` step now reaches the caller as `SignInView.prompt`, not only sensitive ones. A non-sensitive step shows the engine's question as written (`github-copilot-enterprise` asks for the Enterprise domain first), so the sign-in no longer waits 15 minutes on a screen with nothing to answer. Once a step is sensitive (or the choice is `setup-token`), the prompt stays the fixed `Sign-in token` label and no gateway prose is shown, as before.
+- FIX: `setup-token` is no longer offered. The pinned Gateway has no app-guided sign-in for it and refuses every attempt with "That provider setup is not available on this Gateway.", so it is listed with `readiness: 'no_upstream_flow'`, the link no longer maps `{ provider: 'anthropic', via: 'browser' }` to it. `plugins.allow` now holds the plugin of every default-eligible bundled route rather than only the ready ones, so `anthropic-cli` and `apiKey` keep the `anthropic` plugin allowed without app config.
+- The R1 restart-recovery probe accepts both restart-time gate denials for the unowned recovering session (HEAD's `unknown run` and the published kit's `can't check this action right now`); any other transcript text still fails the denial assertion.
+
+## 0.6.2 (2026-10-05)
+
+FIX: The browser broker now holds its CDP endpoint back until Chromium's initial tab exists, so `/json/list` can never serve an empty browser to an attaching engine on a cold or slow start; a browser that never lists a tab fails the launch honestly instead.
+- Remove the fake Gateway's own happy-path self-tests for default member/auth and the device-code wizard script from `test/fake.test.ts`. They asserted the synthetic fixture's own response shapes and exact number of progress pulls, not product behaviour. Member creation, caching and validation, device-code sign-in through `kit.signIn`/`kit.signedIn`, `health` pass-through and sign-out remain covered by the shared public consumer contract (`src/testing/contract.ts`) and the packed Chromium journey in `examples/openclaw-kit/e2e.test.ts`. Every negative, cancellation, denial, gate, drop and refusal assertion is kept unchanged, and no test was added.
+- The quickstart's example output is what the example actually prints today: the offered-route list was stale
+  (it still showed `anthropic-cli` and a browser `setup-token` and missed `opencode-go`). The block is now the
+  real output of the runnable fake-Gateway example, followed by a "read next" pointer to the run contract, the
+  kit example and SECURITY.md.
+FIX: The sealed credential store now seals credential state only — the complete `state` tree plus config/credential paths under `home` — instead of the whole engine home, so a real signed-in home with tool caches no longer produces a sealed payload past the runtime string limit and aborts boot. Regenerable caches, transcripts and logs (`home/.cache`, `home/.npm`, and the `sessions`/`log`/`cache`/`.tmp`/`history.jsonl` subtrees of `.codex`, the `projects`/`todos`/`shell-snapshots`/`statsig`/`file-history`/`history.jsonl` subtrees of `.claude`) stay on disk unsealed; unknown `home` paths stay sealed. The sealed payload is built exactly once and verified by decrypting the sealed bytes. Existing `v: 1` snapshots still restore completely and re-seal once as `v: 2` with a log line; no credential is ever dropped.
+- Every type an entry hands a caller is now nameable from that entry, and none of them carries `any`.
+  `.` exports `GatewayMethods`, `RouteView`, `RouteFacts`, `JsonValue`, `UsageClient` and `DayUsageClient`;
+  `./device` exports `OpenClawDevice` and `DeviceEndFrame`; `./link` exports `OpenClawLinkOptions`,
+  `OpenClawLinkHost`, `OpenClawServeOptions` and `OpenClawServeHandle`; `./testing` exports `FakeGateway`,
+  `FakeHandler`, `FakeParams` and `StubRequest`, types `fakeGateway`'s script per method, and records each
+  stubbed request as a typed `StubRequest` instead of `any`. An app can write its own generic wrapper over
+  `call` and annotate what `routes()`, `openclawDevice()` and `openclawLink()` return without a cast. The
+  Gateway slots the pinned engine does not declare stay `unknown` and are listed per release in
+  `src/generated/report.json`; the README now says so beside the API table.
+
 ## 0.6.1 (2026-10-04)
 
 FIX: Let apps declare `appOwnedSessions.keyPrefixes` before Gateway startup so caller-requeued task sessions do not also receive an engine-started recovery turn. Preserve session history, policy gates, API-key session mapping and stock recovery for other namespaces.

package/README.md

@@ -102,6 +102,9 @@ just to read a final result: on cache eviction that would start another run. App
 recovery. Typed `kit.call('agent', ...)` remains exact upstream pass-through. Details and real-engine proof are
 in [the run contract](../../docs/runtime-kits.md#58-runs-members-and-streams).
 
+Every code route shows its code the same way: a waiting view carries `code`, `url`, `expiresAt` (epoch ms, when
+the engine gives a lifetime) and the engine's own instructions in `message`, including routes whose pinned engine
+prints the code only into a note's text.
 Device approval can take longer than two minutes. The kit waits through the engine's advertised code lifetime
 (`expiresInMinutes` on the pin, or `expires_in` seconds when supplied), including progress pulls. If the engine
 supplies no lifetime, it owns the deadline. Ordinary wizard requests keep their 120-second timeout.
@@ -109,7 +112,7 @@ supplies no lifetime, it owns the deadline. Ordinary wizard requests keep their
 `done` returns a typed `SignInView`: `why: 'expired'` for an expired code, `why: 'declined'` for cancellation,
 with a plain sentence in `error`. `SignInOptions` is exported from the host entry.
 
-For a subscription setup-token or any sensitive wizard text step, pass the token once through the same
+For any sensitive wizard text step, pass the secret once through the same
 `signIn.paste(token)` channel and clear the input afterwards. The kit displays only a fixed entry label;
 subsequent wizard errors, links and codes are withheld, and failures use a fixed message rather than
 engine text that could echo the token. It is sent only as this member's wizard answer, never in views,
@@ -288,17 +291,22 @@ state: ready | protocol: 4
 event: {"type":"text","text":"fake: Say hello."}
 event: {"type":"text","text":"fake: Say hello."}
 end: {"ok":true,"text":"fake: Say hello.","usage":{"input":10,"output":16,"total":26}}
-route: openai                     subscription browser
-route: openai-device-code         subscription code
-route: xai-oauth                  subscription code
 route: github-copilot             subscription code
 route: github-copilot-enterprise  subscription code
 route: minimax-global-oauth       subscription code
 route: minimax-cn-oauth           subscription code
-route: anthropic-cli              subscription browser
-route: setup-token                subscription browser
+route: openai                     subscription browser
+route: openai-device-code         subscription code
+route: opencode-go                subscription plan_key
+route: xai-oauth                  subscription code
 ```
 
+The block above is the whole quickstart: copy it into a `.mts` file next to your app's
+`node_modules` and `node` it. No engine, no account, no network. Then read
+[the run contract](../../docs/runtime-kits.md#58-runs-members-and-streams) for retries and
+streams, [`examples/openclaw-kit`](../../examples/openclaw-kit) for a whole app, and
+[SECURITY.md](SECURITY.md) before you store anything the engine returns.
+
 Subscription sign-ins are offered by default. API-billed routes remain in `kit.routes()` with `offer: false`;
 apps can offer them when the app or person opts in, labelled API key (billed per use). Each `Route` carries `billing` (`subscription`, `api` or
 `local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. The pinned Gateway guides only some routes; other choices need manual paste or key entry. For an opted-in route, allow its `plugin` id
@@ -319,12 +327,23 @@ Entries:
 | `OpenClawKit` (`.`) | Prepares, starts, supervises and stops the engine. `call` / `callDynamic` pass through to the Gateway, `onEvent` listens. Helpers: `ensureMember`, `routes`, `providers`, `signedIn`, `signIn`, `signOut`, `migrateRetainedLogin`, `confirmRetainedLogin`, `toolNames`, `run`, `steer`, `abort`, `approvals`, `onApproval`, `decide`, `allowOnce`, `disallowOnce`, `patchConfig`, `getConfigKey`, `setConfigKey`, `memoryLimited`, `doctorContext` |
 | `ENGINE_VERSION`, `PROTOCOL_VERSION`, `OPERATOR_SCOPES` (`.`) | The pinned engine version, its protocol and the operator scopes the kit connects with |
 | `KitOptions`, `RunSpec`, `RunEvent`, `RunEnd`, `RunUsage`, `PlanWindow`, `Route`, `Approval`, `Decision`, `ToolSpec`, `ToolHost`, `KitState`, ... (`.`) | Public types (docs/runtime-kits.md §5.2) |
-| `openclawDevice(link)` (`./device`) | Portable client: state, routes, sign-in, runs, steer, abort, approvals, events, sealed notices, pass-through `call` |
+| `GatewayMethods`, `GatewayMethod`, `GatewayParams`, `GatewayResult`, `GatewayEventName`, `GatewayEventPayload` (`.`) | The generated pass-through tables, so an app can write its own generic wrapper over `call` / `onEvent` once |
+| `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` |
-| `openclawLink(kit, o)` (`./link`) | `handle` / `stream` / `allow` for a `@byokit/link` `Host`, checked per member, plus `onAction` for relay push actions |
-| `serve(o)` (`./link`) | Binds the link host per reach and returns its URLs |
-| `fakeGateway`, `openclawContract`, `startModelStub`, `useModelStub` (`./testing`) | In-memory Gateway, the contract suite and the scripted model for tests |
+| `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` |
+
+### What the pass-through cannot type
+
+Every method and event the pin publishes has a real type: `kit.call('sessions.list', params)` is checked in and
+returns the engine's declared result, with no cast. For the slots the pin itself leaves undeclared the table stays
+`unknown`, and `src/generated/report.json` names every one of them per release. On `openclaw@2026.8.1` that is 301
+of 393 methods' params and 192 of their results, plus 21 of 55 event payloads; the other slots are not missing from
+the kit, they are not published by the engine, and typing them here would be a guess that does not match the
+gateway. `callDynamic` stays the same shape for a method the pin never declared.
 
 ## Owned browser (unqualified handoff)
 
@@ -419,8 +438,9 @@ Route data follows the shared account-route vocabulary (D18 in [`docs/runtime-ki
 
 The pinned engine has no supported hook for sealing OAuth profile writes. Its `auth-profiles` loader stores
 credential JSON in agent SQLite databases and a shared state database, and doctor imports leave migration
-archives. `authSeal` therefore protects the complete isolated `state` and `home` directories, including SQLite
-journals. It uses the injected `SealingAdapter` from `@byokit/secrets`. `osKeyringSeal()` automatically
+archives. `authSeal` therefore protects credential state — the complete isolated `state` tree plus
+config/credential paths under `home`, including SQLite journals — while regenerable tool caches,
+transcripts and logs stay on disk unsealed. It uses the injected `SealingAdapter` from `@byokit/secrets`. `osKeyringSeal()` automatically
 uses a persistent private file key for new stores when no non-interactive keyring is available.
 Opening follows the saved envelope's mode. A locked or unresponsive keyring-only store leaves
 `kit.state.phase === 'locked'`: `prepare()` and `start()` resolve, show `stateWords(kit.state)` for
@@ -461,8 +481,11 @@ every retained sealed migration archive before retiring an automatic key. Rotate
 separately; dual-wrap rotation retains old wrapping keys for backups.
 
 Without `authSeal`, engine credentials remain plaintext. With it, successful `prepare()` and `stop()` leave
-only a sealed snapshot, `auth-store.sealed`, for those directories. The adapter authenticates the snapshot
-before any restoration; a wrong key, tampering, or a missing adapter rejects. Files restored for the engine
+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
 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.
@@ -474,7 +497,8 @@ inspection or a rewritten command line), another host is alive, or shutdown time
 `{ phase: 'failed', why: 'engine-already-running' }`; show `stateWords(kit.state)` and retry after the other
 session stops. Failed-start cleanup and `stop()` on an instance with no ownership preserve the other
 writer's pid, lock, sealed snapshot and live state.
-Sealing copies the whole store through memory, so startup and stop cost grows with session history.
+The sealed payload is built once and verified by decrypting the sealed bytes, so startup and stop cost
+grows with credential state, not session history.
 
 The migration doctor temporarily opens the same store and reseals it even when import fails. Once the gateway
 verifies every provider, `confirmRetainedLogin()` removes the explicitly passed legacy source and writes only
@@ -516,4 +540,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), 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 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.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.

package/SECURITY.md

@@ -28,7 +28,10 @@ resolve with `phase: 'locked'`, do not restore plaintext or launch the engine, a
 retries after unlock. Opt-in dual wrapping opens through an owner-only host key without prompting;
 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. Other sealing failures still reject.
+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.
 
 ## Secrets at rest and in memory
 
@@ -37,7 +40,7 @@ the replacement decrypts to identical contents. Other sealing failures still rej
 | Gateway token | `openclaw/token` | Random 32-byte bearer secret; newly created file is 0600. Treat it as operator access. |
 | Device identity | `openclaw/device.json` | Ed25519 private key stored as **unencrypted PKCS#8 PEM** in JSON, newly created 0600. The transport accepts both kit and legacy paired shapes without rewriting. Theft can impersonate the operator identity. |
 | Provider profiles | `openclaw/state/` and `openclaw/home/`, including agent/shared SQLite databases, journals and migration JSON | Access/refresh tokens or API keys are **plaintext while running**; without `authSeal` they also remain plaintext while stopped. Migration stages `auth-profiles.json` at 0600 in a newly created 0700 directory. Theft may authorize provider calls and refresh. |
-| Sealed credential snapshot | `openclaw/auth-store.sealed` and retired `*.sealed` archives | With host-injected `authSeal`, authenticates and encrypts the complete state/home trees while stopped. Key security belongs to the adapter/host; an older authentic snapshot can be replayed. |
+| Sealed credential snapshot | `openclaw/auth-store.sealed` and retired `*.sealed` archives | With host-injected `authSeal`, authenticates and encrypts credential state (the complete `state` tree plus config/credential paths under `home`) while stopped; regenerable caches stay on disk unsealed. Key security belongs to the adapter/host; an older authentic snapshot can be replayed. |
 | Saved configuration, logs and sessions | `openclaw/openclaw.json`, `logs/`, engine state | May contain app-supplied keys, prompts, tool inputs, sign-in URLs/codes or provider diagnostics. Treat the whole tree as secret. Engine stdout/stderr is appended to a newly created 0600 log; it is not a guaranteed credential-redaction layer. |
 | Notice seed and decrypted approvals | Device app storage and memory | The app stores the 32-byte seed; the kit receives it only for key derivation/decryption. Seed theft exposes notices for its box key. |
 
@@ -48,8 +51,8 @@ collects regular files and file symlinks whose fully resolved targets are regula
 files within the isolated engine root; links restore as regular files at the link
 paths. Outside-root, dangling and directory links, sockets, FIFOs and devices are
 skipped without reading their contents. Collected POSIX modes are normalized;
-other paths still need host protection. Skipped entries are not preserved in the
-snapshot and are removed with the live trees after successful sealing. Never use a shared/writable tree or point
+other paths still need host protection. Excluded caches are not preserved in the
+snapshot and stay on disk unsealed after successful sealing; other skipped entries are not preserved in the snapshot. Never use a shared/writable tree or point
 the kit at another product's state. Review existing permissions before adopting a
 tree; use an OS-protected app directory, encrypted disk and restricted backups.
 Do not log `doctorContext().env`, transport arguments, auth records or sign-in
@@ -57,8 +60,8 @@ callbacks. JavaScript strings and engine memory are not reliably zeroized.
 
 The engine needs plaintext credentials and PEM during operation. With `authSeal`
 (a host-injected `SealingAdapter` from `@byokit/secrets`), `src/auth-store.ts` seals
-all of state/home, including SQLite journals, on successful `prepare()` and after
-the engine exits on `stop()`. It verifies the adapter round-trip, writes via an
+credential state — the complete `state` tree plus config/credential paths under `home`, including SQLite journals — on successful `prepare()` and after
+the engine exits on `stop()`, while regenerable caches stay on disk unsealed. It verifies the adapter round-trip, writes via an
 exclusive temporary file, fsyncs/renames the snapshot and verifies it again before
 removing live plaintext. `start()` authenticates and validates snapshot paths before
 restoring files. Missing/wrong keys or tampering reject without plaintext fallback.
@@ -69,7 +72,7 @@ orderly shutdown. An abrupt host exit can leave live plaintext; the next prepare
 seals leftovers only after the orphan writer has exited. Interrupted restore or
 removal recovers from the authenticated snapshot. A sealing failure retains
 recoverable files and rejects; the host must resolve it and retry. Snapshot size
-and memory cost grow with the complete state/home trees. Keys, gateway token,
+and memory cost grow with sealed credential state; the payload is built once and excluded caches never enter it. Keys, gateway token,
 device PEM, inline config secrets, logs, install/cache files and app workspaces
 are outside this seal. OS-keyring or host-key adapters must keep the key separate
 from state/backups. There is no rollback protection. File removal cannot erase old

package/dist/auth-store.d.ts

@@ -1,5 +1,9 @@
 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;
 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;
@@ -19,7 +23,13 @@ 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
+     *  and the directories still holding them are left in place. */
+    private remove;
     private persist;
     private restore;
     archives(): Promise<void>;

package/dist/auth-store.js

@@ -1,7 +1,9 @@
 // The pin persists OAuth JSON in both shared and agent SQLite. There is no public persistence hook.
-// Seal the complete isolated stores, including journals, only after their writer has exited.
-import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, closeSync, fsyncSync, openSync } from 'node:fs';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+// Seal only credential state — the engine's complete `state` tree plus every config/credential path in
+// `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 { 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)
@@ -45,13 +47,27 @@ function put(path, bytes) {
         rmSync(tmp, { force: true });
     }
 }
+// Credential state is what restores a working signed-in session. Regenerable tool caches, transcripts
+// and logs never do: the XDG cache and npm cache homes the kit's engine environment pins, plus the
+// transcript/log/cache subtrees of the Codex and Claude Code CLIs it runs in `home`. Unknown paths stay
+// sealed — a credential location we do not know about must fail loudly, never drop silently.
+const HOME_CACHES = {
+    home: ['.cache', '.npm'],
+    'home/.codex': ['sessions', 'log', 'cache', '.tmp', 'history.jsonl'],
+    'home/.claude': ['projects', 'todos', 'shell-snapshots', 'statsig', 'file-history', 'history.jsonl'],
+};
+/** True for the regenerable cache paths the collector never seals; tests assert these are all that stay at rest. */
+export function cached(name) {
+    const parent = name.includes('/') ? name.slice(0, name.lastIndexOf('/')) : '';
+    return (HOME_CACHES[parent] ?? []).includes(name.slice(name.lastIndexOf('/') + 1));
+}
 function safePath(path) {
     return typeof path === 'string' && /^(state|home)(\/[^/]+)*$/.test(path)
         && !path.split('/').some((part) => part === '.' || part === '..' || part.includes('\\') || part.includes('\0'));
 }
 function snapshot(text) {
     const s = JSON.parse(text);
-    if (s?.v !== 1 || !Array.isArray(s.dirs) || !Array.isArray(s.files))
+    if ((s?.v !== 1 && s?.v !== 2) || !Array.isArray(s.dirs) || !Array.isArray(s.files))
         throw new Error('invalid sealed credential store');
     const paths = new Set();
     for (const path of s.dirs) {
@@ -73,6 +89,8 @@ function snapshot(text) {
     return s;
 }
 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();
@@ -158,8 +176,22 @@ export class AuthStore {
         regular(this.file);
         const seal = this.o.seal;
         const bytes = readFileSync(this.file);
-        const text = seal.decryptString(bytes);
-        const saved = snapshot(text);
+        let text;
+        try {
+            text = seal.decryptString(bytes);
+        }
+        catch (error) {
+            if (error?.code !== 'auth-failed')
+                throw error;
+            return this.setAside('could not be authenticated');
+        }
+        let saved;
+        try {
+            saved = snapshot(text);
+        }
+        catch {
+            return this.setAside('is not a credential snapshot');
+        }
         const upgraded = seal.upgrade?.(bytes);
         if (upgraded) {
             if (seal.decryptString(Buffer.from(upgraded)) !== text)
@@ -168,11 +200,22 @@ 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);
         const walk = (path) => {
             const name = relative(this.o.root, path).split('\\').join('/');
+            if (cached(name))
+                return; // tool caches are never credential state; skipping a directory skips its subtree
             const stat = lstatSync(path);
             if (stat.isDirectory()) {
                 chmodSync(path, 0o700);
@@ -208,31 +251,56 @@ export class AuthStore {
                 walk(join(this.o.root, dir));
         return s;
     }
+    /** 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
+     *  and the directories still holding them are left in place. */
+    remove(s) {
+        rmSync(join(this.o.root, 'state'), { recursive: true, force: true });
+        for (const [path] of s.files)
+            if (path.startsWith('home/'))
+                rmSync(join(this.o.root, path), { force: true });
+        for (const path of [...s.dirs].sort((a, b) => b.split('/').length - a.split('/').length)) {
+            if (!path.startsWith('home/'))
+                continue;
+            try {
+                rmdirSync(join(this.o.root, path));
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== 'ENOTEMPTY' && code !== 'ENOENT')
+                    throw error; // a directory still holding caches stays
+            }
+        }
+    }
     async persist() {
         if (!this.o.seal)
             return;
         // Always authenticate an earlier snapshot before considering a leftover live store after a crash.
         const previous = await this.read();
         if (previous && (existsSync(this.cleanup) || existsSync(this.restoring))) {
-            for (const dir of ['state', 'home'])
-                rmSync(join(this.o.root, dir), { recursive: true, force: true });
+            this.remove(previous);
             removeMarker(this.cleanup);
             removeMarker(this.restoring);
             this.o.log?.('interrupted credential transition recovered');
         }
-        const hasLive = ['state', 'home'].some((dir) => existsSync(join(this.o.root, dir)));
-        if (!hasLive && previous)
+        const saved = this.collect();
+        // Live trees with nothing sealable are debris (crash leftovers, or only the caches a previous stop
+        // left in place) — keep the sealed credentials instead of replacing them with an empty snapshot.
+        // A running engine always leaves files behind (its SQLite stores), so a genuine sign-out still re-seals.
+        if (!saved.files.length && previous)
             return;
-        const text = JSON.stringify(this.collect());
-        const sealed = this.o.seal.encryptString(text);
-        if (this.o.seal.decryptString(Buffer.from(sealed)) !== text)
+        // The payload is built exactly once; verification decrypts the sealed bytes and compares to it.
+        const payload = JSON.stringify(saved);
+        const sealed = this.o.seal.encryptString(payload);
+        if (this.o.seal.decryptString(Buffer.from(sealed)) !== payload)
             throw new Error('credential seal verification failed');
         put(this.file, sealed);
-        if (this.o.seal.decryptString(readFileSync(this.file)) !== text)
+        if (this.o.seal.decryptString(readFileSync(this.file)) !== payload)
             throw new Error('credential seal verification failed');
+        if (previous?.dirs.some(cached))
+            this.o.log?.('sealed credential store re-sealed: tool caches no longer sealed');
         put(this.cleanup, encoder.encode('1'));
-        for (const dir of ['state', 'home'])
-            rmSync(join(this.o.root, dir), { recursive: true, force: true });
+        this.remove(saved);
         removeMarker(this.cleanup);
     }
     async restore() {

package/dist/browser/broker.js

@@ -668,10 +668,23 @@ export async function launchBroker(o) {
         await send('Browser.getVersion');
         await send('Browser.setDownloadBehavior', { behavior: 'deny', eventsEnabled: false });
         await send('Target.setDiscoverTargets', { discover: true });
-        const result = await send('Target.getTargets');
-        for (const t of result.targetInfos)
-            targets.set(t.targetId, t);
-        lastAgent = result.targetInfos.find(t => t.type === 'page')?.targetId;
+        // Chromium creates the initial tab after the pipe already answers, so a cold start can list zero
+        // page targets here. Never expose the endpoint before the agent tab exists: a discovery /json/list
+        // would honestly report an empty browser and break every engine that lists targets at attach.
+        const tabUntil = Date.now() + 30_000;
+        let pages = [];
+        for (;;) {
+            const result = await send('Target.getTargets');
+            for (const t of result.targetInfos)
+                targets.set(t.targetId, t);
+            pages = result.targetInfos.filter(t => t.type === 'page');
+            if (pages.length > 0 || Date.now() >= tabUntil)
+                break;
+            await new Promise(resolve => setTimeout(resolve, 25));
+        }
+        lastAgent = pages[0]?.targetId;
+        if (!lastAgent)
+            throw failure();
         await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', () => resolve()); });
         port = server.address().port;
     }

package/dist/config.js

@@ -56,7 +56,10 @@ export function reconcileConfig(saved, o) {
     c.plugins.load ??= {};
     c.plugins.load.paths = [...new Set([...(c.plugins.load.paths ?? []).filter((p) => !p.includes('byokit-openclaw-bridge')), o.pluginDir])];
     c.plugins.allow = [...new Set([...(c.plugins.allow ?? []), o.pluginId,
-            ...routes().filter(route => route.offer && route.plugin).map(route => route.plugin)])];
+            // Every default-eligible bundled route, not only the ready ones: anthropic-cli waits on its binary and
+            // shares its plugin with the explicit apiKey route, so neither may depend on another route being offered.
+            ...routes().filter(route => route.offerPolicy === 'default' && !route.needs?.plugin && route.plugin)
+                .map(route => route.plugin)])];
     c.plugins.entries ??= {};
     c.plugins.entries[o.pluginId] = merge(c.plugins.entries[o.pluginId] ?? {}, { hooks: { timeouts: { before_tool_call: 200_000 } } });
     if (o.browser) {

package/dist/day-usage.d.ts

@@ -69,8 +69,10 @@ export type AgentDayUsage = {
 export declare function engineStartedOf(raw: unknown, member: Member, window: AgentDayUsage['window']): AgentDayUsage['engineStarted'] & {
     complete: boolean;
 };
-/** Read the transcript and Workshop terms independently. A failed term never becomes zero. */
-export declare function readAgentDayUsage(client: {
+/** What `readAgentDayUsage` needs from a reader: the kit's `call` plus its own string-typed RPC. */
+export type DayUsageClient = {
     callDynamic(method: string, params?: unknown): Promise<unknown>;
     call(method: 'sessions.usage', params: SessionsUsageParams): Promise<unknown>;
-}, member: Member, window: AgentDayUsage['window']): Promise<AgentDayUsage>;
+};
+/** Read the transcript and Workshop terms independently. A failed term never becomes zero. */
+export declare function readAgentDayUsage(client: DayUsageClient, member: Member, window: AgentDayUsage['window']): Promise<AgentDayUsage>;

package/dist/device.d.ts

@@ -27,7 +27,8 @@ export type SessionRow = {
     sessionKey: string;
     [k: string]: unknown;
 };
-type EndFrame<T = unknown> = {
+/** The frame `oc.run`'s stream ends with: the run's `RunEnd`, beside its events. */
+export type DeviceEndFrame<T = unknown> = {
     type: 'end';
     end: RunEnd<T>;
 };
@@ -78,7 +79,8 @@ export type SignInNotice = {
 export declare function openSignInNotice(data: Record<string, unknown>, seed: Uint8Array): SignInNotice | null;
 /** Transient streams bypass link's durable request/answer cache: no lease nonce or frame is persisted. */
 export declare function browserDevice(link: DeviceLink): BrowserDevice;
-export declare function openclawDevice(link: DeviceLink): {
+/** `openclawDevice`'s device surface: every `oc.*` op the computer answers, typed. */
+export type OpenClawDevice = {
     browser: BrowserDevice;
     state(): Promise<DeviceState>;
     routes(): Promise<RouteView[]>;
@@ -90,7 +92,7 @@ export declare function openclawDevice(link: DeviceLink): {
     };
     signOut(p: string): Promise<void>;
     sessions(): Promise<SessionRow[]>;
-    run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<RunEvent | EndFrame<SchemaOutput<S>>>;
+    run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<RunEvent | DeviceEndFrame<SchemaOutput<S>>>;
     steer(k: string, t: string, o?: {
         auth?: 'apiKey';
     }): Promise<void>;
@@ -105,6 +107,7 @@ export declare function openclawDevice(link: DeviceLink): {
     call<M extends GatewayMethod>(method: M, params: GatewayParams<M>): Promise<GatewayResult<M>>;
     callDynamic(method: string, params?: unknown): Promise<unknown>;
 };
+export declare function openclawDevice(link: DeviceLink): OpenClawDevice;
 export { openNotice } from './notices.ts';
 export { readAgentUsage, agentUsageOf } from './usage.ts';
 export { readAgentDayUsage } from './day-usage.ts';

package/dist/engine-status.d.ts

@@ -1,4 +1,4 @@
-import type { ChildProcess } from 'node:child_process';
+import { type ChildProcess } from 'node:child_process';
 /** Every process the kit itself spawned, held for shutdown by pid. */
 export declare class StartedProcesses {
     private readonly started;
@@ -16,4 +16,4 @@ export declare class EngineAlreadyRunningError extends Error {
     readonly code = "engine-already-running";
     constructor();
 }
-export declare function pidAlive(pid: number): boolean;
+export declare function pidAlive(pid: number, platform?: NodeJS.Platform): boolean;

package/dist/engine-status.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 /** Every process the kit itself spawned, held for shutdown by pid. */
 export class StartedProcesses {
     started = new Set();
@@ -38,20 +39,40 @@ export class EngineAlreadyRunningError extends Error {
         this.name = 'EngineAlreadyRunningError';
     }
 }
-export function pidAlive(pid) {
+export function pidAlive(pid, platform = process.platform) {
     if (!Number.isSafeInteger(pid) || pid < 1)
         return true; // An invalid guard is ambiguous, never stale.
     try {
         process.kill(pid, 0);
         // An orphan can remain a zombie until its new parent reaps it; it has no writer left.
-        if (process.platform === 'linux') {
+        if (platform === 'linux') {
             const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
             if (stat.slice(stat.lastIndexOf(')') + 2).startsWith('Z '))
                 return false;
         }
+        else if (platform !== 'win32' && psReportsZombie(pid)) {
+            // No /proc here (notably macOS): only a definite zombie reads as stale.
+            return false;
+        }
         return true;
     }
     catch (error) {
         return error.code !== 'ESRCH';
     }
 }
+/**
+ * Why ps: `ps -o stat=` exists on macOS and Linux with the same leading-letter state
+ * convention, so a `Z` first letter names the same kernel fact the /proc read names on
+ * Linux. Linux keeps its /proc read (no subprocess, unchanged answers); every other Unix
+ * asks ps. Only positive `Z` evidence flips the answer — a missing ps, an empty reply,
+ * or gibberish keeps the guard, so a reused live pid is never stolen.
+ */
+function psReportsZombie(pid) {
+    try {
+        const probed = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8', timeout: 5000 });
+        return (probed.stdout ?? '').trimStart().startsWith('Z');
+    }
+    catch {
+        return false;
+    }
+}

package/dist/engine.d.ts

@@ -1,3 +1,4 @@
+import { AuthStore } from './auth-store.ts';
 import type { KitOptions } from './kit.ts';
 import type { KitState, ToolSpec } from './types.ts';
 export type EngineOptions = Pick<KitOptions, 'stateDir' | 'engineDir' | 'npmPath' | 'enginePath' | 'config' | 'appOwnedSessions' | 'installPolicy' | 'log' | 'bridge' | 'authSeal'> & {
@@ -24,7 +25,7 @@ export declare class Engine {
     private child?;
     private readonly started;
     private starting?;
-    private readonly authStore;
+    readonly authStore: AuthStore;
     private stopping;
     private credentialsLocked;
     private repaired;

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 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 { 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 { EngineAlreadyRunningError } from './engine-status.ts';
 export { readAgentDayUsage } from './day-usage.ts';
-export type { AgentDayUsage, EngineStartedCharge, EngineStartedKind } from './day-usage.ts';
+export type { AgentDayUsage, DayUsageClient, EngineStartedCharge, EngineStartedKind } from './day-usage.ts';
 export { readAgentUsage, agentUsageOf } from './usage.ts';
-export type { AgentUsageReading, LedgerUsageTotals, UsageCache, UsageWindow } from './usage.ts';
+export type { AgentUsageReading, LedgerUsageTotals, UsageCache, UsageClient, UsageWindow } from './usage.ts';
 export type { LiveSource, BrowserState, SignInMethodHint, SignInReason, SignInChoice, SettledState, SettledReason, ResumeState, NeedSignIn, TakeoverLease, LiveViewState, LiveFrame, LiveInput, ThumbnailResult, SignInRefusedWhy, BrowserOptions, SiteVerifier, BrowserHost, BrowserDevice } from './browser.ts';

package/dist/kit.js

@@ -736,7 +736,7 @@ export class OpenClawKit {
             await this.bridge.start();
             this.off.push(transport.onEvent((e) => this.approvalsCtl.handleEvent(e)));
             this.failures = 0;
-            this.setState({ phase: 'ready' });
+            this.setState(this.engine.authStore.reset ? { phase: 'ready', why: 'sign-in-reset' } : { phase: 'ready' });
             if (this.o.browser)
                 await this.checkBrowserTools();
             // Replays the engine's native approval lists over the now-live transport (N9).
@@ -882,7 +882,14 @@ export class OpenClawKit {
         return engineProviders(this.signInCtx(), member).then((names) => names.includes(provider)).catch(() => false);
     }
     signIn(member, o, on) {
-        return startSignIn(this.signInCtx(), 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);
+        });
     }
     signOut(member, provider) {
         return engineSignOut(this.signInCtx(), member, provider);

package/dist/link.d.ts

@@ -1,27 +1,35 @@
 import type { BrowserHost } from './browser.ts';
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type Grant, type Host, type HostOptions } from '@byokit/link';
-import { type ServeIngress, type Via } from '@byokit/reach';
+import { type ServeIngress, type Via } from '@byokit/discover';
 import type { PushAction, RelayClient } from '@byokit/relay';
 import type { OpenClawKit } from './kit.ts';
 import type { Member } from './types.ts';
-export declare function openclawLink(kit: OpenClawKit & {
-    browser?: BrowserHost;
-}, o: {
+/** `openclawLink`'s options: which member a grant acts for, the D8 pass-through predicate, sealed relay push. */
+export type OpenClawLinkOptions = {
     memberOf: (grant: Grant) => Member | undefined;
     passThrough?: (method: string, grant: Grant) => boolean;
-    relay?: RelayClient;
-}): Pick<HostOptions, 'handle' | 'stream' | 'allow' | 'onGrantRemoved'> & {
+    relay?: Pick<RelayClient, 'notify'>;
+};
+/** What `openclawLink` hands the link host: its request/stream handlers plus the kit's push entry point. */
+export type OpenClawLinkHost = Pick<HostOptions, 'handle' | 'stream' | 'allow' | 'onGrantRemoved'> & {
     onAction(a: PushAction): Promise<unknown>;
 };
-export declare function serve(o: {
+export declare function openclawLink(kit: OpenClawKit & {
+    browser?: BrowserHost;
+}, o: OpenClawLinkOptions): OpenClawLinkHost;
+/** `serve`'s options: the link host to accept on, and the ingress to publish or replace. */
+export type OpenClawServeOptions = {
     host: Host;
     port: number;
     via?: Via;
     previous?: ServeIngress;
     http?: (req: IncomingMessage, res: ServerResponse) => void;
-}): Promise<{
+};
+/** The running ingress: its urls, the entry that reaches the engine, and an orderly close. */
+export type OpenClawServeHandle = {
     urls: string[];
     ingress?: ServeIngress;
     close(): Promise<void>;
-}>;
+};
+export declare function serve(o: OpenClawServeOptions): Promise<OpenClawServeHandle>;

package/dist/link.js

@@ -6,7 +6,7 @@ import { readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { WebSocketServer } from 'ws';
 import { PublicLinkError, } from '@byokit/link';
-import { reach } from '@byokit/reach';
+import { reach } from '@byokit/discover';
 import { ENGINE_VERSION } from "./constants.js";
 import { b64urlDecode, b64urlEncode, sealNotice } from "./notices.js";
 import { routeFor } from "./routes.js";
@@ -618,8 +618,6 @@ export function openclawLink(kit, o) {
     };
     return { handle, stream, allow: () => true, onAction, onGrantRemoved: grant => revoke(grant.id) };
 }
-// ponytail: this ~40-line serve() wiring is deliberately duplicated per runtime kit (D3);
-// extract it into a shared package when a third runtime kit appears.
 export async function serve(o) {
     const r = await reach({ port: o.port, via: o.via, previous: o.previous });
     const server = createServer(o.http ??

package/dist/routes.json

@@ -122,7 +122,7 @@
     },
     {
         "choice": "anthropic-cli",
-        "provider": "anthropic",
+        "provider": "claude-cli",
         "plugin": "anthropic",
         "billing": "subscription",
         "via": "cli",
@@ -134,6 +134,7 @@
             "provider": "claude-cli",
             "via": "browser"
         },
+        "deprecatedProvider": "anthropic",
         "reason": "Anthropic Claude CLI: subscription sign-in.",
         "source": "extensions/anthropic/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
@@ -173,13 +174,9 @@
         "via": "setup_token",
         "auth": "token",
         "prerequisite": null,
-        "offer": true,
-        "offerPolicy": "default",
-        "legacy": {
-            "provider": "anthropic",
-            "via": "browser"
-        },
-        "reason": "Anthropic setup-token: subscription sign-in.",
+        "offer": false,
+        "offerPolicy": "explicit",
+        "reason": "The pinned Gateway has no app-guided sign-in for this choice.",
         "source": "extensions/anthropic/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -201,7 +198,7 @@
             "id": "anthropic",
             "method": "setup-token",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {

package/dist/signin.js

@@ -15,6 +15,19 @@ const CANCEL_MS = 10_000;
 const RECONFIRM_MS = 60_000;
 const TURNS = 200;
 const PASTE_MS = 15 * 60_000;
+// Two of the pin's code routes print their code only into a note's text ("Code: X" with
+// "Code expires in N minutes", or "enter the code X." with "Expires at: <ISO>"), never as `deviceCode`.
+// Read it back so every code route reaches the caller in the one structured shape.
+const noteCode = (step) => {
+    const text = step.type === 'note' ? step.message ?? '' : '';
+    const code = /^Code: (\S+)$/m.exec(text)?.[1] ?? /enter the code (\S+?)\.?$/m.exec(text)?.[1];
+    if (!code)
+        return undefined;
+    const minutes = /Code expires in (\d+) minutes/.exec(text)?.[1];
+    const at = Date.parse(/Expires at: (\S+)/.exec(text)?.[1] ?? '');
+    return { code, message: text, ...(minutes ? { expiresInMinutes: Number(minutes) }
+            : Number.isFinite(at) ? { expires_in: Math.max(0, Math.floor((at - Date.now()) / 1_000)) } : {}) };
+};
 const cut = (value) => (value instanceof Error ? value.message : String(value)).slice(0, 200);
 const pullOptions = (signal) => ({ timeoutMs: PULL_MS, signal });
 /**
@@ -268,19 +281,22 @@ export function signIn(ctx, member, o, on) {
             step = undefined;
             if (current.type === 'text' && current.sensitive)
                 sensitive = true;
-            if (current.deviceCode && current.type !== 'text') {
+            const deviceCode = current.type === 'text' ? undefined : current.deviceCode ?? noteCode(current);
+            if (deviceCode) {
                 stopApproval();
                 approval = true;
                 sawDeviceCode = true;
                 // The pin converts its provider duration to minutes. Prefer exact seconds if the engine supplies them.
-                const duration = current.deviceCode.expires_in !== undefined
-                    ? Number(current.deviceCode.expires_in) * 1_000
-                    : Number(current.deviceCode.expiresInMinutes) * 60_000;
-                if (Number.isFinite(duration) && duration >= 0) {
+                const duration = deviceCode.expires_in !== undefined
+                    ? Number(deviceCode.expires_in) * 1_000
+                    : Number(deviceCode.expiresInMinutes) * 60_000;
+                const timed = Number.isFinite(duration) && duration >= 0;
+                if (timed)
                     codeTimer = setTimeout(() => { codeExpired = true; owner.abort(); }, duration);
-                }
+                const message = deviceCode.message ?? current.message;
                 // The code is on the card; acknowledging it lets the engine poll the provider itself.
-                say({ ...(current.deviceCode.code ? { code: current.deviceCode.code } : {}), ...(current.externalUrl ? { url: current.externalUrl } : {}) });
+                say({ ...(deviceCode.code ? { code: deviceCode.code } : {}), ...(current.externalUrl ? { url: current.externalUrl } : {}),
+                    ...(timed ? { expiresAt: Date.now() + duration } : {}), ...(message ? { message } : {}) });
                 const next = await answer(current);
                 if (next.done) {
                     terminal = next;
@@ -292,8 +308,9 @@ export function signIn(ctx, member, o, on) {
             if (current.type !== 'progress')
                 stopApproval();
             if (current.type === 'text') {
-                if (current.sensitive)
-                    say({ prompt: 'Sign-in token' });
+                // Every text step is a question the person must answer, so it is always asked. A non-sensitive one is not a
+                // secret by the engine's own flag: its question is shown as written. Once anything is sensitive, only the fixed label is.
+                say({ prompt: sensitive ? 'Sign-in token' : current.message || 'Paste what the sign-in page gave you' });
                 const value = await waitForPaste();
                 if (value === undefined)
                     return signal.aborted ? cancelled() : expired();

package/dist/testing/contract.js

@@ -10,8 +10,7 @@ import assert from 'node:assert/strict';
 import { PROTOCOL_VERSION } from "../constants.js";
 import { GATEWAY_CAPS } from "../transport.js";
 import { releaseStub, stubHolding } from "./model-stub.js";
-// The generated method table arrives with O2; until then kit.call's typed surface accepts no method names, so the
-// suite drives pass-through through this string-typed view of the same runtime path.
+/** The contract drives pass-through by method name, so results arrive untyped and are narrowed per case. */
 const call = (kit, method, params) => kit.call(method, params);
 const REQUIRED_METHODS = [
     'agent', 'agent.wait', 'agents.create', 'agents.list', 'chat.abort', 'config.get', 'config.patch',

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

@@ -1,9 +1,16 @@
-import type { GatewayTransport } from '../types.ts';
+import type { GatewayMethod, GatewayParams, GatewayTransport } from '../types.ts';
 import type { KitOptions } from '../kit.ts';
-type Handler = (params: any, bridgeSock: string) => unknown;
-/** Pre-registered handlers for `fakeGateway(script)`, on top of the defaults (a same-name entry replaces one). */
-export type FakeScript = Record<string, Handler>;
-export declare function fakeGateway(script?: FakeScript): {
+/** A scripted handler's params: the generated type when the pin publishes one, else the raw params object. */
+export type FakeParams<M extends GatewayMethod> = unknown extends GatewayParams<M> ? Record<string, unknown> : GatewayParams<M>;
+/** A scripted handler for one method, with that method's params typed. */
+export type FakeHandler<M extends GatewayMethod = GatewayMethod> = (params: FakeParams<M>, bridgeSock: string) => unknown;
+/** Pre-registered handlers for `fakeGateway(script)`, on top of the defaults (a same-name entry replaces one).
+ * Only methods the pinned engine publishes are scriptable, exactly as `kit.call` and `kit.callDynamic` divide them. */
+export type FakeScript = {
+    [M in GatewayMethod]?: FakeHandler<M>;
+};
+/** The fake's control surface: the transport to hand a kit, the calls it saw, and its triggers. */
+export type FakeGateway = {
     factory: NonNullable<KitOptions['transport']>;
     calls: {
         method: string;
@@ -12,8 +19,8 @@ export declare function fakeGateway(script?: FakeScript): {
     emit(event: string, payload?: unknown): void;
     failNext(method: string, message: string): void;
     drop(why: string): void;
-    handle(method: string, fn: Handler): void;
+    handle(method: string, fn: FakeHandler): void;
 } & {
     transport: GatewayTransport;
 };
-export {};
+export declare function fakeGateway(script?: FakeScript): FakeGateway;

package/dist/testing/fake-gateway.js

@@ -245,12 +245,12 @@ export function fakeGateway(script) {
         'openclaw.setup.activate': (p) => {
             if (p.kind !== 'api-key')
                 throw new Error('only the API-key setup path is simulated');
-            const route = routes().find((r) => r.choice === p.authChoice && r.keyEntry);
+            const route = routes().find((r) => r.choice === String(p.authChoice) && r.keyEntry);
             if (!route)
                 return { ok: false, status: 'unavailable' };
             const model = `${route.provider}/fake-key-model`;
-            keys.set(p.agentId, { provider: route.provider, key: p.apiKey, model, sealed: false });
-            signInAgent(p.agentId, route.provider);
+            keys.set(String(p.agentId), { provider: route.provider, key: String(p.apiKey), model, sealed: false });
+            signInAgent(String(p.agentId), route.provider);
             return { ok: true, status: 'ok', modelRef: model };
         },
         'openclaw.setup.auth.start': (p) => {
@@ -325,14 +325,15 @@ export function fakeGateway(script) {
         'exec.approval.request': (p) => {
             const id = String(p.id ?? `exec-${randomUUID()}`);
             const now = Date.now();
+            const plan = isPlainObject(p.systemRunPlan) ? p.systemRunPlan : {};
             emit('exec.approval.requested', {
                 approvalKind: 'exec', id, createdAtMs: now, expiresAtMs: now + 180_000,
                 request: {
                     command: p.command,
                     // Like the real engine, which normalizes the exec policy mode into request.ask (B8).
                     ask: p.ask ?? 'on-miss',
-                    agentId: p.agentId ?? p.systemRunPlan?.agentId,
-                    sessionKey: p.sessionKey ?? p.systemRunPlan?.sessionKey,
+                    agentId: p.agentId ?? plan.agentId,
+                    sessionKey: p.sessionKey ?? plan.sessionKey,
                 },
             });
             return { id };
@@ -366,6 +367,7 @@ export function fakeGateway(script) {
     };
     for (const [method, handler] of Object.entries(defaults))
         handlers.set(method, handler);
+    // A script handler is already per-method typed; the loose internal map only dispatches it.
     for (const [method, handler] of Object.entries(script ?? {}))
         handlers.set(method, handler);
     const dispatch = async (method, params, bridgeSock) => {
@@ -377,7 +379,7 @@ export function fakeGateway(script) {
         const handler = handlers.get(method);
         if (!handler)
             throw new Error(`unknown method: ${method}`);
-        return await handler(params ?? {}, bridgeSock);
+        return await handler(isPlainObject(params) ? params : {}, bridgeSock);
     };
     const hello = () => ({
         protocol: PROTOCOL_VERSION,

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-export { fakeGateway, type FakeScript } from './fake-gateway.ts';
+export { fakeGateway, type FakeGateway, type FakeHandler, type FakeParams, type FakeScript } from './fake-gateway.ts';
 export { fakeBrowserHost, createBrowserHostFake, browserHostContract, memorySignInStore, type FakeBrowserHost, type FakeBrowserHostOptions, type BrowserFixture } from './browser.ts';
 export { openclawContract, type ContractFixture } from './contract.ts';
-export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls, type ModelStub, type ModelStubOptions, type StubCall } from './model-stub.ts';
+export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls, type ModelStub, type ModelStubOptions, type StubCall, type StubRequest } from './model-stub.ts';

package/dist/testing/model-stub.d.ts

@@ -1,8 +1,21 @@
 import type { OpenClawKit } from '../kit.ts';
+export type StubRequest = {
+    model?: unknown;
+    input?: unknown;
+    messages?: {
+        role?: string;
+        content?: unknown;
+        name?: unknown;
+        tool_call_id?: unknown;
+    }[];
+    stream_options?: {
+        include_usage?: boolean;
+    };
+};
 export type StubCall = {
     authorization: string;
     path: string;
-    body: any;
+    body: StubRequest;
 };
 /** The token usage every stub reply reports when asked (`stream_options.include_usage`), per model call. */
 export declare const STUB_USAGE: {

package/dist/testing/model-stub.js

@@ -58,7 +58,8 @@ export const releaseStub = (key, reply = '') => {
         }
 };
 export const stubHolding = (key) => (key ? holds.has(key) : holds.size > 0);
-const words = (m) => typeof m?.content === 'string' ? m.content : Array.isArray(m?.content) ? m.content.map((c) => c.text ?? '').join('') : '';
+const words = (m) => typeof m?.content === 'string' ? m.content : Array.isArray(m?.content)
+    ? m.content.map((c) => (typeof c?.text === 'string' ? c.text : '')).join('') : '';
 export function startModelStub(script = [], o = {}) {
     const calls = [];
     const queue = [...script];
@@ -97,7 +98,7 @@ export function startModelStub(script = [], o = {}) {
         const phrased = (text) => /hit the limit|no helpers in plan|sign me out|ask permission/i.test(text);
         const lastUser = [...users].reverse().find((m) => structural(words(m)))
             ?? [...users].reverse().find((m) => phrased(words(m)))
-            ?? users.at(-1);
+            ?? users.at(-1) ?? {};
         const said = words(lastUser);
         const anchor = messages.lastIndexOf(lastUser);
         const results = anchor < 0 ? [] : messages.slice(anchor + 1).filter((m) => m.role === 'tool');
@@ -113,7 +114,7 @@ export function startModelStub(script = [], o = {}) {
         if (said.startsWith(routingMarker)) {
             const options = [...said.matchAll(/^- ([a-z0-9-]+):/gm)].map((m) => m[1]);
             const pick = /\[route ([a-z0-9-]+|\?)\]/.exec(said)?.[1] ?? 'chief';
-            return plain(res, body, JSON.stringify(Object.fromEntries(options.map((o) => [o, pick === '?' ? 1 / options.length : o === pick ? 0.9 : 0.1 / (options.length - 1)]))));
+            return plain(res, body.model, JSON.stringify(Object.fromEntries(options.map((o) => [o, pick === '?' ? 1 / options.length : o === pick ? 0.9 : 0.1 / (options.length - 1)]))));
         }
         if (/sign me out/i.test(said)) {
             res.writeHead(401, { 'content-type': 'application/json' });
@@ -167,21 +168,18 @@ export function startModelStub(script = [], o = {}) {
         });
     });
 }
-const plain = (res, body, text) => {
+const plain = (res, model, text) => {
     const id = randomUUID();
     res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
-    const chunk = (delta, finish = null) => res.write(`data: ${JSON.stringify({ id, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), model: body.model, choices: [{ index: 0, delta, finish_reason: finish }] })}\n\n`);
+    const chunk = (delta, finish = null) => res.write(`data: ${JSON.stringify({ id, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), model, choices: [{ index: 0, delta, finish_reason: finish }] })}\n\n`);
     chunk({ role: 'assistant', content: text });
     chunk({}, 'stop');
     res.end('data: [DONE]\n\n');
 };
 // provider id 'byokit-stub', model 'test': the stub becomes every agent's primary model.
 export async function useModelStub(kit, stub) {
-    // The generated method table arrives with O2; until then kit.call's typed surface accepts no method names, so
-    // configure through this string-typed view of the same runtime path.
-    const call = kit.call.bind(kit);
-    const current = await call('config.get');
-    await call('config.patch', { baseHash: current.hash, raw: JSON.stringify({
+    const current = await kit.call('config.get', {});
+    await kit.call('config.patch', { baseHash: current.hash, raw: JSON.stringify({
             models: { providers: { 'byokit-stub': {
                         baseUrl: stub.url, apiKey: 'byokit-stub', api: 'openai-completions',
                         models: [{ id: 'test', name: 'Test', reasoning: true, input: ['text'],

package/dist/types.d.ts

@@ -103,6 +103,8 @@ export type SignInView = {
     via: 'browser' | 'code';
     url?: string;
     code?: string;
+    expiresAt?: number;
+    message?: string;
     prompt?: string;
     error?: string;
     why?: 'busy' | 'declined' | 'expired' | 'failed';
@@ -125,7 +127,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';
+    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version' | 'engine-already-running' | 'engine-patch' | 'sign-in-reset';
     retryAt?: number;
     patchSet?: string | null;
 };
@@ -157,6 +159,10 @@ export type Route = {
         provider: string;
         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
+     * `claude-cli:cli:anthropic-cli`. */
+    deprecatedProvider?: string;
     billingFrom?: 'source' | 'host';
     group?: 'models' | 'services';
     platforms?: {

package/dist/usage.d.ts

@@ -46,6 +46,8 @@ export type AgentUsageReading = {
 /** Normalize an explicitly agent-scoped UTC response. No missing datum is replaced with zero. */
 export declare function agentUsageOf(raw: unknown, member: Member, window: UsageWindow, receivedAt?: number): AgentUsageReading;
 /** Works with kit.call or the portable device.call; retains the complete existing pass-through. RPC errors reject. */
-export declare function readAgentUsage(client: {
+/** What `readAgentUsage` needs from a reader: the kit (`call`) or a device (`callDynamic` + `call`) both fit. */
+export type UsageClient = {
     call(method: 'sessions.usage', params: SessionsUsageParams, options?: CallOptions): Promise<unknown>;
-}, member: Member, window: UsageWindow, options?: CallOptions): Promise<AgentUsageReading>;
+};
+export declare function readAgentUsage(client: UsageClient, member: Member, window: UsageWindow, options?: CallOptions): Promise<AgentUsageReading>;

package/dist/usage.js

@@ -53,7 +53,6 @@ export function agentUsageOf(raw, member, window, receivedAt = Date.now()) {
     result.totals = totals;
     return result;
 }
-/** Works with kit.call or the portable device.call; retains the complete existing pass-through. RPC errors reject. */
 export async function readAgentUsage(client, member, window, options) {
     validate(member, window);
     const raw = await client.call('sessions.usage', { agentId: member, startDate: window.startDate, endDate: window.endDate, mode: 'utc', groupBy: 'instance', limit: 1 }, options);

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 === 'sign-in-reset')
+        return words('engine.signInAgain');
     return s.phase === 'stopped' ? '' : words(PHASE_WORDS[s.phase]);
 }
 export function toAccountView(view, ready) {

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.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.",
     "engine.alreadyRunning": "Your saved sign-in is in use. Try again after the other session stops.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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,9 +60,9 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.7.0",
-    "@byokit/relay": "0.5.2",
-    "@byokit/reach": "0.6.0",
+    "@byokit/link": "0.7.1",
+    "@byokit/relay": "0.5.3",
+    "@byokit/discover": "0.6.0",
     "@byokit/seal": "0.3.0",
     "@byokit/secrets": "0.5.0",
     "@openclaw/gateway-client": "2026.9.6",