@byokit/openclaw 0.5.1 → 0.6.1

package/engine/OPENCLAW-LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Third-party notices for incorporated or adapted code are recorded in
+THIRD_PARTY_NOTICES.md.

package/engine/patches.json

@@ -0,0 +1,59 @@
+{
+  "v": 1,
+  "id": "171ce088cd516dcf",
+  "upstream": {
+    "name": "openclaw",
+    "version": "2026.8.1",
+    "integrity": "sha512-bSaFeaDFnQH/bU1vgKMac6eHkHHPHG0C/uwduXGI3eIS3lyiYSwmDU5ehhBUUhlPeV85tL5/KVwmoH48nX1tWw==",
+    "commit": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
+    "license": "MIT"
+  },
+  "files": [
+    {
+      "path": "dist/experience-review-default-6DPIIJds.js",
+      "before": "30f43da07b2520dd785df42ba417737a0f2cc0286922fe2189f06ecbafc1ab9c",
+      "after": "e9448c45a2d7f5e8ab7f1996269a4291d2453aac7641ea82cb82cc238e93cb43",
+      "edits": [
+        {
+          "find": "import { n as getRuntimeConfig } from \"./io.runtime-CNGn9TXj.js\";\n",
+          "replace": "import { n as getRuntimeConfig } from \"./io.runtime-CNGn9TXj.js\";\nimport { openSync as byokitOpen, writeSync as byokitWrite, fsyncSync as byokitFsync, closeSync as byokitClose } from \"node:fs\";\nimport { join as byokitJoin } from \"node:path\";\n"
+        },
+        {
+          "find": "async function runSkillExperienceReviewInner(candidate, deps) {\n",
+          "replace": "/** BYOKit R4-1: content-free durable Gateway Workshop facts, inert without kit env. */\nfunction byokitUsageFact(fact) {\n\tconst dir = process.env.BYOKIT_ENGINE_USAGE_LEDGER;\n\tconst bootId = process.env.BYOKIT_ENGINE_BOOT;\n\tif (!dir || !bootId) return;\n\tconst key = Symbol.for(\"byokit.engine-usage.v1\");\n\tconst live = globalThis[key] ??= { bootId, months: {}, inFlight: {} };\n\tconst month = new Date(fact.at).toISOString().slice(0, 7);\n\tconst counter = live.months[month] ??= { lastSeq: 0, failed: 0 };\n\tconst seq = ++counter.lastSeq;\n\tif (fact.phase === \"started\") live.inFlight[fact.chargeId] = { startedAt: fact.startedAt };\n\telse delete live.inFlight[fact.chargeId];\n\ttry {\n\t\tconst fd = byokitOpen(byokitJoin(dir, \"engine-started-\" + month + \".jsonl\"), \"a\", 0o600);\n\t\ttry {\n\t\t\tconst line = Buffer.from(JSON.stringify({ v: 1, ...fact, bootId, seq }) + \"\\n\");\n\t\t\tif (byokitWrite(fd, line) !== line.length) throw new Error(\"short accounting write\");\n\t\t\tbyokitFsync(fd);\n\t\t} finally { byokitClose(fd); }\n\t} catch { counter.failed++; }\n}\nasync function runSkillExperienceReviewInner(candidate, deps) {\n"
+        },
+        {
+          "find": "\tlet outcome;\n\tlet proposalId;\n\tlet usage;\n",
+          "replace": "\tlet outcome;\n\tlet proposalId;\n\tlet usage;\n\tlet byokitRunUsage;\n\tconst byokitFact = { chargeId: runId, agentId: foregroundPromptContext.agentId, kind: \"workshop-review\", provider: modelProviderId, model: modelId, ...candidate.ctx.authProfileId ? { authProfileId: candidate.ctx.authProfileId } : {}, startedAt: attemptedAtMs, origin: { sessionKey: foregroundSessionKey, ...candidate.ctx.runId ? { runId: candidate.ctx.runId } : {} } };\n"
+        },
+        {
+          "find": "\ttry {\n\t\tlet embeddedResult;\n",
+          "replace": "\tbyokitUsageFact({ ...byokitFact, phase: \"started\", at: attemptedAtMs });\n\ttry {\n\t\tlet embeddedResult;\n"
+        },
+        {
+          "find": "\t\t} finally {\n\t\t\tpreparedRunAdmission.close();\n\t\t}\n\t\tassertSkillReviewRunSucceeded(embeddedResult);\n",
+          "replace": "\t\t} finally {\n\t\t\tpreparedRunAdmission.close();\n\t\t}\n\t\tbyokitRunUsage = embeddedResult?.meta?.agentMeta?.usage;\n\t\tassertSkillReviewRunSucceeded(embeddedResult);\n"
+        },
+        {
+          "find": "\t} catch (error) {\n\t\trecordSkillExperienceReviewOutcome(workspaceDir, {\n",
+          "replace": "\t} catch (error) {\n\t\tbyokitUsageFact({ ...byokitFact, phase: \"ended\", at: Date.now(), outcome: \"failed\", ...byokitRunUsage ? { usage: byokitRunUsage } : {} });\n\t\trecordSkillExperienceReviewOutcome(workspaceDir, {\n"
+        },
+        {
+          "find": "\t} finally {\n\t\tclearAgentRunContext(runId);\n\t}\n\trecordSkillExperienceReviewOutcome(workspaceDir, {\n",
+          "replace": "\t} finally {\n\t\tclearAgentRunContext(runId);\n\t}\n\tbyokitUsageFact({ ...byokitFact, phase: \"ended\", at: Date.now(), outcome, ...byokitRunUsage ? { usage: byokitRunUsage } : {} });\n\trecordSkillExperienceReviewOutcome(workspaceDir, {\n"
+        }
+      ]
+    },
+    {
+      "path": "dist/main-session-recovery-state-BWIrIyi_.js",
+      "before": "418a957496786dd7ed28df4a7a02e31e9567020e1be5804545e785baf965f225",
+      "after": "f1afea642c78d7979ed40ce43c102c41f790c5dbedaec0e6e7eb8d6f47bc0032",
+      "edits": [
+        {
+          "find": "function isMainRestartRecoveryCandidate(entry, sessionKey) {",
+          "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;"
+        }
+      ]
+    }
+  ]
+}

package/engine/patches.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "BYOKit pinned OpenClaw patch set v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["v", "id", "upstream", "files"],
+  "properties": {
+    "v": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[a-f0-9]{16}$" },
+    "upstream": {
+      "type": "object", "additionalProperties": false,
+      "required": ["name", "version", "integrity", "commit", "license"],
+      "properties": {
+        "name": { "const": "openclaw" },
+        "version": { "type": "string" },
+        "integrity": { "type": "string", "pattern": "^sha512-" },
+        "commit": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "license": { "const": "MIT" }
+      }
+    },
+    "files": { "type": "array", "items": { "$ref": "#/$defs/file" } }
+  },
+  "$defs": {
+    "file": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "before", "after", "edits"],
+      "properties": {
+        "path": { "type": "string", "pattern": "^dist/(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_.-]+\\.m?js$" },
+        "before": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "after": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "edits": {
+          "type": "array", "minItems": 1,
+          "items": {
+            "type": "object", "additionalProperties": false, "required": ["find", "replace"],
+            "properties": { "find": { "type": "string", "minLength": 1 }, "replace": { "type": "string", "minLength": 1 } }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "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",
@@ -29,6 +29,14 @@
       "types": "./dist/device.d.ts",
       "default": "./dist/device.js"
     },
+    "./usage": {
+      "types": "./dist/usage.d.ts",
+      "default": "./dist/usage.js"
+    },
+    "./day-usage": {
+      "types": "./dist/day-usage.d.ts",
+      "default": "./dist/day-usage.js"
+    },
     "./link": {
       "types": "./dist/link.d.ts",
       "default": "./dist/link.js"
@@ -53,11 +61,11 @@
   },
   "dependencies": {
     "@byokit/link": "0.7.0",
-    "@byokit/relay": "0.5.1",
+    "@byokit/relay": "0.5.2",
     "@byokit/reach": "0.6.0",
-    "@byokit/seal": "0.2.0",
+    "@byokit/seal": "0.3.0",
     "@byokit/secrets": "0.5.0",
-    "@openclaw/gateway-client": "2026.8.1",
+    "@openclaw/gateway-client": "2026.9.6",
     "@openclaw/gateway-protocol": "2026.8.1",
     "ws": "8.21.3"
   },

package/plugin/index.js

@@ -4,6 +4,7 @@
 import { connect } from 'node:net';
 import { readFileSync } from 'node:fs';
 import { registerKeys } from './keys.js';
+import { registerUsage } from './usage.js';
 
 /** TypeBox's Kind is a global symbol, so these schemas are valid TypeBox without importing typebox. */
 const Kind = Symbol.for('TypeBox.Kind');
@@ -14,6 +15,36 @@ const PERMIT_PARAM = table.permitParam;
 const TOOLS = new Map(table.tools.map((t) => [t.name, t]));
 // Absent (a table from before the flag) reads as true: fail closed.
 const GATE_BUILTINS = table.gateBuiltins !== false;
+const BROWSER = table.browser === true;
+let browserCapabilities = [];
+function scrubBrowserCapabilities(value) {
+  let serialized = JSON.stringify(value).replace(/\b(?:wss?|https?):\/\/[^\s"'<>\\]+/g, url => {
+    try { return new URL(url).pathname.startsWith('/devtools/') ? '[browser transport omitted]' : url; }
+    catch { return url; }
+  });
+  for (const capability of browserCapabilities) serialized = serialized.replaceAll(capability, '[browser capability omitted]');
+  return JSON.parse(serialized);
+}
+const unsafe = new Set(['exec', 'process', 'code_execution', 'bash', 'terminal', 'read', 'write', 'edit', 'apply_patch', 'gateway']);
+const browserActions = new Set(['profiles', 'importprofile', 'start', 'stop', 'doctor', 'evaluate']);
+
+// Run before the app gate; never trust a caller's profile, target or nested routing.
+function browserParams(params, member) {
+  if (!params || typeof params !== 'object' || Array.isArray(params)) throw new Error('browser action refused');
+  if (browserActions.has(String(params.action).toLowerCase()) || browserActions.has(String(params.kind).toLowerCase()))
+    throw new Error('browser action refused');
+  const out = { ...params };
+  // Stock merges hook params over the original: omission would retain a hostile node selection.
+  out.node = undefined;
+  out.profile = `byokit-${member}`;
+  out.target = 'host';
+  if (out.request !== undefined) out.request = browserParams(out.request, member);
+  if (out.actions !== undefined) {
+    if (!Array.isArray(out.actions)) throw new Error('browser action refused');
+    out.actions = out.actions.map(action => browserParams(action, member));
+  }
+  return out;
+}
 
 /** Minimal JSON Schema -> TypeBox-marked schema converter; output is both valid TypeBox and valid JSON Schema. */
 function toTypeBox(schema) {
@@ -115,7 +146,25 @@ export default {
     jsonSchema: { type: 'object', additionalProperties: false, properties: {} },
   },
   register(api) {
-    if (api.registerGatewayMethod) registerKeys(api);
+    if (api.registerGatewayMethod) { registerKeys(api); registerUsage(api); }
+    if (BROWSER) {
+      if (typeof api.registerAgentToolResultMiddleware !== 'function') throw new Error('browser result protection unavailable');
+      api.registerAgentToolResultMiddleware(async (event, ctx) => {
+        const stopped = { result: { content: [{ type: 'text', text: 'Browser session unavailable.' }],
+          details: { status: 'error' }, terminate: true } };
+        try {
+          const admission = await bridgeRequest({ kind: 'before-agent-run', key: ctx.sessionKey, runId: ctx.runId });
+          if (admission.allow !== true) return stopped;
+          const reply = await bridgeRequest({ kind: 'browser-capabilities' });
+          if (!Array.isArray(reply.capabilities) || reply.capabilities.some(value => typeof value !== 'string' || !value)) return stopped;
+          browserCapabilities = [...reply.capabilities].sort((a, b) => b.length - a.length);
+          return { result: scrubBrowserCapabilities(event.result) };
+        } catch { return stopped; }
+      }, { runtimes: ['openclaw', 'codex'] });
+      // Transcript-only safety net; live provider protection comes from the awaited middleware above.
+      api.on('tool_result_persist', event => ({ message: scrubBrowserCapabilities(event.message) }));
+      api.on('before_message_write', event => ({ message: scrubBrowserCapabilities(event.message) }));
+    }
     for (const spec of table.tools) {
       api.registerTool({
         name: spec.name,
@@ -151,16 +200,40 @@ export default {
         },
       });
     }
+    if (BROWSER) api.on('before_agent_run', async (_event, ctx) => {
+      // A kit-owned refusal seam, NOT an enable flag or an automatic-redispatch qualification.
+      const key = ctx?.sessionKey;
+      if (typeof key !== 'string' || !key) return { outcome: 'block', reason: 'run unavailable', message: 'run unavailable' };
+      try {
+        const reply = await bridgeRequest({ kind: 'before-agent-run', key, runId: ctx?.runId },
+          { timeoutMs: 10_000, signal: ctx?.abortSignal });
+        if (reply?.allow === true) return undefined;
+      } catch { /* missing host or timeout refuses before submission */ }
+      return { outcome: 'block', reason: 'run unavailable', message: 'run unavailable' };
+    });
     api.on('before_tool_call', async (event, ctx) => {
       // Engine builtins (web_fetch, memory, ...) are gated too unless the app opted out; they run in-engine and
       // never call back, so an allow passes them through unchanged.
       const builtin = !TOOLS.has(event.toolName);
-      if (builtin && !GATE_BUILTINS) return undefined;
+      if (builtin && !GATE_BUILTINS && !BROWSER) return undefined;
       const key = ctx?.sessionKey;
       if (typeof key !== 'string' || !key) return { block: true, blockReason: "can't check this action right now" };
+      let params = event.params ?? {};
+      if (BROWSER) {
+        if (unsafe.has(event.toolName) || (builtin && event.toolName !== 'browser'))
+          return { block: true, blockReason: 'browser tool policy refused' };
+        if (event.toolName === 'browser') {
+          // Account agents retain their member identity. A delegate has its own agent id, never the parent's browser.
+          const agent = ctx?.agentId ?? /^agent:([^:]+):/.exec(key)?.[1];
+          const member = typeof agent === 'string' ? agent.replace(/^byokit-key-/, '') : '';
+          if (!/^[a-z][a-z0-9-]{0,31}$/.test(member)) return { block: true, blockReason: 'browser member unavailable' };
+          try { params = browserParams(params, member); }
+          catch { return { block: true, blockReason: 'browser action refused' }; }
+        }
+      }
       let decision;
       try {
-        decision = await gate(key, event.toolName, event.params ?? {}, ctx?.abortSignal);
+        decision = await gate(key, event.toolName, params, ctx?.abortSignal);
       } catch (error) {
         return { block: true, blockReason: error instanceof Error ? error.message : "can't check this action right now" };
       }
@@ -170,12 +243,12 @@ export default {
           blockReason: typeof decision.reason === 'string' ? decision.reason : "can't check this action right now",
         };
       }
-      if (builtin) return undefined;
+      if (builtin) return BROWSER && event.toolName === 'browser' ? { params } : undefined;
       // The bridge mints a permit for permitted tools and admits the rest ticket-side; either way the run key
       // rides along and execute sends back only what the gate gave it (N1).
       return {
         params: {
-          ...(event.params ?? {}),
+          ...params,
           [RUN_PARAM]: key,
           ...(typeof decision.permit === 'string' ? { [PERMIT_PARAM]: decision.permit } : {}),
         },

package/plugin/usage.js

@@ -0,0 +1,125 @@
+// Gateway-only accounting. Reads requested UTC months, never transcript content or credentials.
+import { readFileSync, openSync, writeSync, fsyncSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+const object = v => !!v && typeof v === 'object' && !Array.isArray(v);
+const count = v => Number.isSafeInteger(v) && v >= 0;
+export const USAGE_SYMBOL = Symbol.for('byokit.engine-usage.v1');
+export function readEngineStarted(dir, live, params, read = readFileSync) {
+  const { agentId, startMs, endMs } = params ?? {};
+  if (typeof agentId !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(agentId) || !count(startMs) || !count(endMs) || startMs > endMs ||
+    endMs > 8.64e15) throw new Error('Invalid usage window');
+  const result = { state: 'unavailable', agentId, startMs, endMs, facts: [], unreadableLines: 0, complete: false };
+  if (!dir || !live || typeof live.bootId !== 'string' || !object(live.months) || !object(live.inFlight)) return result;
+  const lines = (path, absentOK) => {
+    try {
+      const text = read(path, 'utf8');
+      const rows = [];
+      for (const line of text.split('\n')) {
+        if (!line) continue;
+        try { const row = JSON.parse(line); if (!object(row)) throw new Error(); rows.push(row); }
+        catch { result.unreadableLines++; }
+      }
+      // A torn final write is not a valid durable line, even when its JSON happens to parse.
+      if (text && !text.endsWith('\n')) result.unreadableLines++;
+      return rows;
+    } catch (error) { if (!absentOK || error.code !== 'ENOENT') result.unreadableLines++; return []; }
+  };
+  const boots = new Map();
+  for (const row of lines(join(dir, 'boots.jsonl'), false)) {
+    if (typeof row.bootId !== 'string' || (row.startedAt === undefined && row.stoppedAt === undefined && row.spawned !== false) ||
+      (row.startedAt !== undefined && !count(row.startedAt)) || (row.stoppedAt !== undefined && (!count(row.stoppedAt) || !object(row.months))) ||
+      (row.spawned === false && !count(row.failedAt))) {
+      result.unreadableLines++; continue;
+    }
+    const boot = boots.get(row.bootId) ?? {};
+    if (row.startedAt !== undefined) { if (boot.startedAt !== undefined && boot.startedAt !== row.startedAt) result.unreadableLines++; boot.startedAt = row.startedAt; }
+    if (row.stoppedAt !== undefined) { if (boot.stoppedAt !== undefined) result.unreadableLines++; boot.stoppedAt = row.stoppedAt; boot.months = row.months; }
+    if (row.spawned === false) { boot.stoppedAt = row.failedAt; boot.months = {}; }
+    boots.set(row.bootId, boot);
+  }
+  const starts = [...boots.values()].map(b => b.startedAt).filter(count).sort((a, b) => a - b);
+  if (!starts.length) return result;
+  result.coverageSince = starts[0]; result.liveBootId = live.bootId; result.state = 'available';
+  let complete = startMs >= starts[0] && count(boots.get(live.bootId)?.startedAt);
+  const sequences = new Map(), seen = new Map(), sequenceFacts = new Map();
+  const months = [];
+  const cursor = new Date(startMs); cursor.setUTCDate(1); cursor.setUTCHours(0, 0, 0, 0);
+  while (cursor.getTime() <= endMs) {
+    const month = cursor.toISOString().slice(0, 7); months.push(month);
+    for (const row of lines(join(dir, `engine-started-${month}.jsonl`), true)) {
+      if (row.v !== 1 || !['started', 'ended'].includes(row.phase) || typeof row.bootId !== 'string' || !count(row.seq) || row.seq < 1 ||
+        !count(row.at) || row.at > 8.64e15 || !count(row.startedAt) || row.startedAt > row.at || new Date(row.at).toISOString().slice(0, 7) !== month ||
+        typeof row.chargeId !== 'string' || typeof row.agentId !== 'string' || row.kind !== 'workshop-review' ||
+        typeof row.provider !== 'string' || typeof row.model !== 'string' || !boots.has(row.bootId)) { result.unreadableLines++; continue; }
+      const key = `${row.bootId}\0${month}`, seq = sequences.get(key) ?? new Set(); seq.add(row.seq); sequences.set(key, seq);
+      const phase = `${row.chargeId}\0${row.phase}`;
+      const sequenceKey = `${key}\0${row.seq}`;
+      if (sequenceFacts.has(sequenceKey) && sequenceFacts.get(sequenceKey) !== phase) result.unreadableLines++;
+      sequenceFacts.set(sequenceKey, phase);
+      const safe = { v: 1, phase: row.phase, bootId: row.bootId, seq: row.seq, at: row.at, startedAt: row.startedAt,
+        chargeId: row.chargeId, agentId: row.agentId, kind: row.kind, provider: row.provider, model: row.model };
+      if (typeof row.authProfileId === 'string') safe.authProfileId = row.authProfileId;
+      if (['nothing', 'proposed', 'applied', 'failed'].includes(row.outcome)) safe.outcome = row.outcome;
+      else if (row.phase === 'ended') { result.unreadableLines++; continue; }
+      if (object(row.usage)) {
+        safe.usage = {};
+        for (const field of ['input', 'output', 'cacheRead', 'cacheWrite', 'reasoningTokens', 'total'])
+          if (typeof row.usage[field] === 'number' && Number.isFinite(row.usage[field]) && row.usage[field] >= 0) safe.usage[field] = row.usage[field];
+      }
+      if (object(row.origin) && typeof row.origin.sessionKey === 'string') safe.origin = { sessionKey: row.origin.sessionKey,
+        ...(typeof row.origin.runId === 'string' ? { runId: row.origin.runId } : {}) };
+      if (seen.has(phase) && JSON.stringify(seen.get(phase)) !== JSON.stringify(safe)) result.unreadableLines++;
+      seen.set(phase, safe);
+    }
+    cursor.setUTCMonth(cursor.getUTCMonth() + 1);
+  }
+  for (const fact of seen.values()) {
+    const start = fact.phase === 'ended' ? seen.get(`${fact.chargeId}\0started`) : undefined;
+    if (start && ['agentId', 'bootId', 'kind', 'provider', 'model', 'authProfileId', 'startedAt'].some(k => start[k] !== fact[k]))
+      result.unreadableLines++;
+  }
+  for (const [id, boot] of boots) {
+    if (!count(boot.startedAt) || (boot.stoppedAt !== undefined && boot.stoppedAt < boot.startedAt)) { complete = false; continue; }
+    if (boot.startedAt > endMs || (boot.stoppedAt !== undefined && boot.stoppedAt < startMs)) continue;
+    const counters = id === live.bootId ? live.months : boot.months;
+    if (!object(counters) || (id !== live.bootId && boot.stoppedAt === undefined)) { complete = false; continue; }
+    for (const month of months) {
+      const counter = counters[month];
+      const seq = sequences.get(`${id}\0${month}`) ?? new Set();
+      if (counter === undefined) { if (seq.size) complete = false; continue; }
+      if (!object(counter) || !count(counter.lastSeq) || !count(counter.failed) || counter.failed !== 0 || seq.size !== counter.lastSeq ||
+        [...seq].some(n => n < 1 || n > counter.lastSeq)) complete = false;
+    }
+  }
+  for (const fact of Object.values(live.inFlight)) if (!object(fact) || !count(fact.startedAt) || fact.startedAt <= endMs) complete = false;
+  result.facts = [...seen.values()].filter(f => f.agentId === agentId);
+  result.live = { bootId: live.bootId, months: Object.fromEntries(months.filter(m => object(live.months[m])).map(m =>
+    [m, { lastSeq: live.months[m].lastSeq, failed: live.months[m].failed }])),
+    inFlight: Object.fromEntries(Object.entries(live.inFlight).filter(([, f]) => object(f) && count(f.startedAt)).map(([id, f]) => [id, { startedAt: f.startedAt }])) };
+  result.complete = complete && result.unreadableLines === 0;
+  return result;
+}
+export function registerUsage(api) {
+  const dir = process.env.BYOKIT_ENGINE_USAGE_LEDGER, bootId = process.env.BYOKIT_ENGINE_BOOT;
+  if (dir && bootId) {
+    const live = globalThis[USAGE_SYMBOL] ??= { bootId, months: {}, inFlight: {} };
+    let clean = false;
+    api.on('gateway_stop', () => { clean = true; });
+    // Snapshot at process exit: no async review can append after these counters. SIGKILL cannot forge a clean stop.
+    process.once('exit', code => {
+      if (!clean || code !== 0 || Object.keys(live.inFlight).length) return;
+      let fd;
+      try {
+        fd = openSync(join(dir, 'boots.jsonl'), 'a', 0o600);
+        const line = Buffer.from(JSON.stringify({ bootId, stoppedAt: Date.now(), months: live.months }) + '\n');
+        if (writeSync(fd, line) !== line.length) return;
+        fsyncSync(fd);
+      } catch { /* No stop proof: permanently incomplete, never fail a review or shutdown. */ }
+      finally { if (fd !== undefined) { try { closeSync(fd); } catch { /* no further writes at exit */ } } }
+    });
+  }
+  api.registerGatewayMethod('byokit.usage.engineStarted', ({ params, respond }) => {
+    try { respond(true, readEngineStarted(process.env.BYOKIT_ENGINE_USAGE_LEDGER, globalThis[USAGE_SYMBOL], params)); }
+    catch { respond(false, undefined, { code: 'INVALID_REQUEST', message: 'Invalid usage window' }); }
+  }, { scope: 'operator.read' });
+}