@byokit/openclaw 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## 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.

package/README.md

@@ -391,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**:

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/index.d.ts

@@ -1,5 +1,5 @@
 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';

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;
@@ -142,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

@@ -21,6 +21,8 @@ import { reconcileConfig, browserToolPolicySafe, browserProfileAcknowledged, bro
 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',
@@ -1042,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/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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.8.0",
+  "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"