kibi-agent-core 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # kibi-agent-core
 
+## 0.11.0
+
+### Minor Changes
+
+- 43d4366: Usage telemetry data is cleaner and more complete. Telemetry is now off when the home directory lies inside the temp directory, as eval, packaging and end-to-end harnesses set it, so each harness run no longer counts as a new install; Kibi's own eval and packed-test sandboxes also set `KIBI_TELEMETRY=0`. Events now name the host agent from `CLAUDECODE`, `CURSOR_AGENT`, `CODEX_SANDBOX`, `GEMINI_CLI`, `OPENCODE`, `AI_AGENT` or the MCP client name, carry a hashed host session id in every host, and say whether they come from a hosted cloud workspace. Failed CLI commands and MCP tool results now carry a fixed error category: the result's error code (for example `upsert_dry_run_invalid`), the failing `kibi doctor` checks, or the `kibi migrate` approval problem. `kibi migrate --apply-safe` now prints the current plan hash when the approved hash is missing or out of date.
+
+  Hooks in Claude Code, Codex, Cursor, ZCode and OpenCode now all send the anonymous `kibi_hook` event (before, only Claude Code did, and only in diagnostic mode for the others), and each hook remembers, as hashes in `telemetry-sessions.json`, which host session last ran in the workspace. CLI and MCP events take the session id from `KIBI_SESSION_ID`, `CLAUDE_CODE_SESSION_ID` or `CODEX_THREAD_ID` when the host exposes one, and otherwise from that workspace marker (at most 30 minutes old), so events from Cursor and OpenCode sessions, which expose no session variable, can be grouped too. Every host's hook also sends the queue when it is due, and right away at the end of a turn.
+
+### Patch Changes
+
+- ce41f02: Agents now keep a signoff in the pull request it approves. The guidance used to time the signoff as an end-of-work step and said only that an agent must never set `approved_by` itself, so agents often opened the pull request first and then carried the person's answer in a separate follow-up pull request.
+  - kibi-usage 2.37.0, kibi-decisions 1.5.0 and kibi-commit-review 1.4.0 (and the signoff-views resource) say to ask for the signoff before opening or merging the pull request, and to record the person's answer (their name in `approved_by` or a `*_waiver_approved_by` field, their words in `origin.ref` or `approval_ref`) on the same branch and pull request. Writing down an answer the person gave is not self-approval. A pull request that only carries a signoff, firmness or waiver approval is ruled out.
+  - The stop-hook signoff reminder (Claude Code, Codex, Cursor, ZCode) adds the same rule. So do the `agent-requirement-unapproved` check action, the `dimension_unrepresented` repair hint and the waiver lines of `kibi proof explain`.
+
 ## 0.10.0
 
 ### Minor Changes

package/dist/decision-guard.js

@@ -260,7 +260,7 @@ export function claimSignoffReminder(session, workspaceRoot) {
 export function signoffReminder() {
     return [
         "Kibi: this session recorded or changed requirements, and the person has not seen them as a signoff view.",
-        "Before reporting the work done or asking to commit, run `kibi signoff` and put its output in the reply unchanged; a requirement the agent wrote waits for the person's approval, so ask for it with this view, never in your own words. When replies go through a messaging tool, pass the output there as the message text, and share `.kb/briefs/signoff/latest.html` only as a rendered page (the Artifact tool in Claude apps), never as an attached file, which chat apps show as raw source (kibi-decisions, resources/signoff-views.md).",
+        "Before reporting the work done, asking to commit, or opening or merging the pull request, run `kibi signoff` and put its output in the reply unchanged; a requirement the agent wrote waits for the person's approval, so ask for it with this view, never in your own words. When they answer, record their answer on the same branch and push it to the same pull request, never to a separate one. When replies go through a messaging tool, pass the output there as the message text, and share `.kb/briefs/signoff/latest.html` only as a rendered page (the Artifact tool in Claude apps), never as an attached file, which chat apps show as raw source (kibi-decisions, resources/signoff-views.md).",
     ].join("\n");
 }
 function readSettled(file) {

package/dist/hook-usage-log.d.ts

@@ -35,6 +35,8 @@ export declare function hookTelemetryEnabled(env?: NodeJS.ProcessEnv): boolean;
 export type HookUsageRow = {
     /** Host agent, e.g. `claude-code`, `cursor`, `codex`, `zcode`, `opencode`. */
     host: string;
+    /** Adapter npm package; defaults to `kibi-<host>` (`kibi-claude` for Claude Code). */
+    packageName?: string | undefined;
     /** Version of the adapter package that wrote the row, when known. */
     packageVersion?: string | null | undefined;
     workspaceRoot: string;
@@ -44,7 +46,15 @@ export type HookUsageRow = {
     trace: HookTrace;
     startedAt: Date;
 };
-/** Append one hook row to `.kb/usage.log` when the operator opted in. */
+/**
+ * Whether a host should build hook traces at all: for the opt-in
+ * `.kb/usage.log` rows or for anonymous usage telemetry.
+ */
+export declare function hookTracesWanted(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Record one hook decision: an anonymous summary event (unless telemetry is
+ * off) and, when the operator opted in, the detailed `.kb/usage.log` row.
+ */
 export declare function appendHookUsage(row: HookUsageRow, env?: NodeJS.ProcessEnv): void;
 /**
  * Trace for a tool call that ran a Kibi operation through MCP or the
@@ -59,6 +69,17 @@ export declare function kbUsageTrace(toolName: string | undefined, toolInput: un
 export declare function editTraces(relativePaths: readonly string[], requirementIdsFor: (relativePath: string) => string[]): HookTrace[];
 /** Append one row per trace, sharing the call's host, session and tool. */
 export declare function appendHookUsageRows(row: Omit<HookUsageRow, "trace">, traces: readonly HookTrace[], env?: NodeJS.ProcessEnv): void;
+/**
+ * End-of-hook bookkeeping every host runs: remember the host session for the
+ * workspace, so CLI and MCP events from that workspace can carry it, and send
+ * the anonymous telemetry queue when it is due, or always at the end of a
+ * turn. Never throws.
+ */
+export declare function finishHookTelemetry(input: {
+    readonly event: string;
+    readonly workspaceRoot: string | undefined;
+    readonly sessionId: string | undefined;
+}, env?: NodeJS.ProcessEnv): Promise<void>;
 /**
  * Version of the adapter package whose `package.json` sits at
  * `packageJsonPath`, or null when it cannot be read.

package/dist/hook-usage-log.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { hostKbOperation } from "./kb-mcp-tools.js";
 import { classifyPath } from "./path-policy.js";
+import { flushTelemetry, recordHookTelemetry, rememberHookSession, telemetryEnabled, } from "./usage-telemetry.js";
 // implements REQ-claude-hook-usage-telemetry-v2, REQ-kibi-telemetry-acceptance-gate-v2
 /** Hook actions the acceptance report reads; hosts emit these names. */
 export const HOOK_ACTION_EDITED = "edited";
@@ -15,9 +16,38 @@ export function hookTelemetryEnabled(env = process.env) {
     return value === "1" || value === "true";
 }
 // implements REQ-claude-hook-usage-telemetry-v2
-/** Append one hook row to `.kb/usage.log` when the operator opted in. */
+/**
+ * Whether a host should build hook traces at all: for the opt-in
+ * `.kb/usage.log` rows or for anonymous usage telemetry.
+ */
+export function hookTracesWanted(env = process.env) {
+    return hookTelemetryEnabled(env) || telemetryEnabled(env);
+}
+function adapterPackage(host) {
+    return host === "claude-code" ? "kibi-claude" : `kibi-${host}`;
+}
+// implements REQ-claude-hook-usage-telemetry-v2, REQ-kibi-anonymous-usage-telemetry
+/**
+ * Record one hook decision: an anonymous summary event (unless telemetry is
+ * off) and, when the operator opted in, the detailed `.kb/usage.log` row.
+ */
 export function appendHookUsage(row, env = process.env) {
-    if (!hookTelemetryEnabled(env) || row.trace.action === undefined)
+    if (row.trace.action === undefined)
+        return;
+    recordHookTelemetry({
+        packageName: row.packageName ?? adapterPackage(row.host),
+        packageVersion: row.packageVersion,
+        host: row.host,
+        sessionId: row.sessionId,
+    }, {
+        hookEvent: row.event,
+        hookAction: row.trace.action,
+        pathKind: row.trace.pathKind,
+        kbOperation: row.trace.kbOperation,
+        kbUsedBefore: row.trace.kbUsedBefore,
+        requirementCount: row.trace.requirementIds?.length,
+    }, env);
+    if (!hookTelemetryEnabled(env))
         return;
     const finishedAt = new Date();
     const { trace } = row;
@@ -85,11 +115,32 @@ export function editTraces(relativePaths, requirementIdsFor) {
 // implements REQ-claude-hook-usage-telemetry-v2
 /** Append one row per trace, sharing the call's host, session and tool. */
 export function appendHookUsageRows(row, traces, env = process.env) {
-    if (!hookTelemetryEnabled(env))
+    if (!hookTracesWanted(env))
         return;
     for (const trace of traces)
         appendHookUsage({ ...row, trace }, env);
 }
+/** Host events that end a turn or a session: the queue is sent right away. */
+const TURN_END_EVENTS = new Set(["stop", "sessionend"]);
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * End-of-hook bookkeeping every host runs: remember the host session for the
+ * workspace, so CLI and MCP events from that workspace can carry it, and send
+ * the anonymous telemetry queue when it is due, or always at the end of a
+ * turn. Never throws.
+ */
+export async function finishHookTelemetry(input, env = process.env) {
+    try {
+        if (input.workspaceRoot && input.sessionId) {
+            rememberHookSession(input.workspaceRoot, input.sessionId, env);
+        }
+        const turnEnd = TURN_END_EVENTS.has(input.event.toLowerCase().replace(/[^a-z]/g, ""));
+        await flushTelemetry({ force: turnEnd }, env);
+    }
+    catch {
+        // Telemetry is best effort and must never disturb the hook.
+    }
+}
 // implements REQ-claude-hook-usage-telemetry-v2
 /**
  * Version of the adapter package whose `package.json` sits at

package/dist/usage-telemetry.d.ts

@@ -14,7 +14,8 @@
  * Events are appended to a per-user queue file and sent in batches, so
  * short-lived processes (hooks, the CLI) do not wait on the network.
  * `KIBI_TELEMETRY=0`, `DO_NOT_TRACK=1`, `kibi telemetry disable`, CI and test
- * runs turn it off.
+ * runs, and sandboxes whose home directory is a temp directory (eval and
+ * packaging harnesses) turn it off.
  */
 /** Public, write-only PostHog project key: it can send events, not read them. */
 export declare const DEFAULT_TELEMETRY_KEY = "phc_A5z8jRhD528abGJiTtPfgu4d4hpbEbfiJr9iUGn9TMsY";
@@ -62,11 +63,28 @@ export type TelemetrySource = {
     host?: string | undefined;
     /** Host session id; only its hash is sent. */
     sessionId?: string | null | undefined;
+    /**
+     * Workspace the CLI or MCP server works in. Without a session id of its
+     * own, the event takes the session a host hook last reported there.
+     */
+    workspaceRoot?: string | undefined;
 };
 /** Variables CI providers set; any non-false value marks a CI run. */
 export declare const CI_ENV_KEYS: readonly ["CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "BUILDKITE", "CIRCLECI", "TRAVIS", "TF_BUILD", "JENKINS_URL", "TEAMCITY_VERSION", "BITBUCKET_BUILD_NUMBER", "CODEBUILD_BUILD_ID", "DRONE", "APPVEYOR", "SEMAPHORE", "BUILDKITE_BUILD_ID", "CF_BUILD_ID", "HEROKU_TEST_RUN_ID"];
 /** Variables test runners set for the code under test (`NAME=value` must match). */
 export declare const TEST_ENV_KEYS: readonly ["NODE_ENV=test", "JEST_WORKER_ID", "VITEST", "VITEST_WORKER_ID", "NODE_TEST_CONTEXT"];
+/** Variables an agent host sets for the processes it starts, in priority order. */
+export declare const HOST_ENV_KEYS: readonly [readonly ["CLAUDECODE=1", "claude-code"], readonly ["CURSOR_AGENT=1", "cursor"], readonly ["CODEX_SANDBOX", "codex"], readonly ["CODEX_THREAD_ID", "codex"], readonly ["GEMINI_CLI=1", "gemini-cli"], readonly ["OPENCODE=1", "opencode"]];
+/** Variables that carry the host agent's session id; only its hash is sent. */
+export declare const SESSION_ENV_KEYS: readonly ["KIBI_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID"];
+/**
+ * The agent host running Kibi, from an explicit `KIBI_HOST`/`KIBI_MCP_HOST`,
+ * the variables hosts set for their children, or the `AI_AGENT` convention
+ * (`claude-code_2-1-3_agent`). Undefined when nothing names one.
+ */
+export declare function detectTelemetryHost(env?: Env): string | undefined;
+/** The host agent's session id from the environment, when it exposes one. */
+export declare function detectTelemetrySession(env?: Env): string | undefined;
 /** Per-user directory holding the telemetry config and queue. */
 export declare function telemetryDirectory(env?: Env): string;
 export declare function readTelemetryConfig(env?: Env): TelemetryConfig;
@@ -89,6 +107,24 @@ export declare function hashTelemetryId(value: string): string;
  * shown. Callers that can reach the user (CLI and MCP stderr) print it.
  */
 export declare function takeTelemetryNotice(env?: Env): string | null;
+/**
+ * Remember which host session last ran a hook in a workspace. Every host
+ * hands its hooks the session id, but only some expose it to the CLI and MCP
+ * server through the environment. Only hashes are stored: of the workspace
+ * path and of the session id.
+ */
+export declare function rememberHookSession(workspaceRoot: string, sessionId: string, env?: Env): void;
+/**
+ * Hashed session a host hook recently reported for this directory or the
+ * nearest ancestor that has one, or undefined.
+ */
+export declare function workspaceSessionHash(startDirectory: string, env?: Env): string | undefined;
+/**
+ * An error category as sent: fixed identifiers such as `tool_timeout` or
+ * `UPSERT_DRY_RUN_INVALID` pass, lower-cased; anything that looks like free
+ * text is replaced, so a message can never leak through this field.
+ */
+export declare function telemetryCategory(value: string | undefined): string | null;
 export declare function recordOperationTelemetry(source: TelemetrySource, operation: OperationTelemetry, env?: Env): void;
 export declare function recordHookTelemetry(source: TelemetrySource, hook: HookTelemetry, env?: Env): void;
 export declare function clearTelemetryQueue(env?: Env): void;

package/dist/usage-telemetry.js

@@ -19,7 +19,8 @@ import path from "node:path";
  * Events are appended to a per-user queue file and sent in batches, so
  * short-lived processes (hooks, the CLI) do not wait on the network.
  * `KIBI_TELEMETRY=0`, `DO_NOT_TRACK=1`, `kibi telemetry disable`, CI and test
- * runs turn it off.
+ * runs, and sandboxes whose home directory is a temp directory (eval and
+ * packaging harnesses) turn it off.
  */
 // implements REQ-kibi-anonymous-usage-telemetry
 /** Public, write-only PostHog project key: it can send events, not read them. */
@@ -29,6 +30,10 @@ export const DEFAULT_TELEMETRY_HOST = "https://eu.i.posthog.com";
 // implements REQ-kibi-anonymous-usage-telemetry
 export const TELEMETRY_DOCS_URL = "https://looted.github.io/kibi/guide/telemetry.html";
 const QUEUE_FILE = "telemetry-queue.jsonl";
+const SESSIONS_FILE = "telemetry-sessions.json";
+/** A hook-recorded session older than this no longer names the workspace's session. */
+const SESSION_MARKER_MAX_AGE_MS = 30 * 60 * 1000;
+const MAX_SESSION_MARKERS = 200;
 const CONFIG_FILE = "telemetry.json";
 const SENDING_SUFFIX = ".sending";
 /** Queue size that makes a flush due regardless of age. */
@@ -100,6 +105,85 @@ function automationName(env, keys) {
     return undefined;
 }
 // implements REQ-kibi-anonymous-usage-telemetry
+/** Variables an agent host sets for the processes it starts, in priority order. */
+export const HOST_ENV_KEYS = [
+    ["CLAUDECODE=1", "claude-code"],
+    ["CURSOR_AGENT=1", "cursor"],
+    ["CODEX_SANDBOX", "codex"],
+    ["CODEX_THREAD_ID", "codex"],
+    ["GEMINI_CLI=1", "gemini-cli"],
+    ["OPENCODE=1", "opencode"],
+];
+// implements REQ-kibi-anonymous-usage-telemetry
+/** Variables that carry the host agent's session id; only its hash is sent. */
+export const SESSION_ENV_KEYS = [
+    "KIBI_SESSION_ID",
+    "CLAUDE_CODE_SESSION_ID",
+    "CODEX_THREAD_ID",
+];
+/** `Claude Code`, `claude_code` and `claude-code` name the same host. */
+function hostKey(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * The agent host running Kibi, from an explicit `KIBI_HOST`/`KIBI_MCP_HOST`,
+ * the variables hosts set for their children, or the `AI_AGENT` convention
+ * (`claude-code_2-1-3_agent`). Undefined when nothing names one.
+ */
+export function detectTelemetryHost(env = process.env) {
+    const explicit = env.KIBI_HOST?.trim() || env.KIBI_MCP_HOST?.trim();
+    if (explicit)
+        return hostKey(explicit) || undefined;
+    for (const [key, host] of HOST_ENV_KEYS) {
+        if (automationName(env, [key]))
+            return host;
+    }
+    const agent = env.AI_AGENT?.trim().split("_")[0];
+    return agent ? hostKey(agent) || undefined : undefined;
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/** The host agent's session id from the environment, when it exposes one. */
+export function detectTelemetrySession(env = process.env) {
+    for (const key of SESSION_ENV_KEYS) {
+        const value = env[key]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/** Whether the process runs in a hosted cloud workspace rather than on a laptop. */
+function remoteEnvironment(env) {
+    return (flagValue(env.CLAUDE_CODE_REMOTE) === true ||
+        flagValue(env.CODESPACES) === true ||
+        Boolean(env.GITPOD_WORKSPACE_ID?.trim()));
+}
+function realDirectory(directory) {
+    try {
+        return fs.realpathSync(directory);
+    }
+    catch {
+        return path.resolve(directory);
+    }
+}
+/**
+ * Eval, packaging and e2e harnesses give each run a fresh home under the temp
+ * directory, so every run would count as a new install. A real user's home
+ * never lives there.
+ */
+function sandboxedHome(env) {
+    const home = (env.HOME ?? env.USERPROFILE)?.trim();
+    if (!home)
+        return false;
+    const temp = realDirectory(os.tmpdir());
+    const resolved = realDirectory(home);
+    return resolved !== temp && resolved.startsWith(`${temp}${path.sep}`);
+}
+// implements REQ-kibi-anonymous-usage-telemetry
 /** Per-user directory holding the telemetry config and queue. */
 export function telemetryDirectory(env = process.env) {
     const explicit = env.KIBI_TELEMETRY_DIR?.trim();
@@ -176,6 +260,9 @@ export function telemetryStatus(env = process.env) {
         automationName(processEnv, TEST_ENV_KEYS);
     if (testName)
         return status(false, `test environment (${testName})`);
+    if (sandboxedHome(env)) {
+        return status(false, "sandboxed home in the temp directory (harness run)");
+    }
     if (preference === "enabled") {
         return status(true, "enabled with `kibi telemetry enable`");
     }
@@ -244,8 +331,89 @@ function runtimeName() {
         ? "node"
         : "bun";
 }
+function sessionMarkersPath(env) {
+    return path.join(telemetryDirectory(env), SESSIONS_FILE);
+}
+function readSessionMarkers(env) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(sessionMarkersPath(env), "utf8"));
+        return parsed !== null &&
+            typeof parsed === "object" &&
+            !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function workspaceKey(workspaceRoot) {
+    return hashTelemetryId(`workspace\0${path.resolve(workspaceRoot)}`);
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * Remember which host session last ran a hook in a workspace. Every host
+ * hands its hooks the session id, but only some expose it to the CLI and MCP
+ * server through the environment. Only hashes are stored: of the workspace
+ * path and of the session id.
+ */
+export function rememberHookSession(workspaceRoot, sessionId, env = process.env) {
+    if (!sessionId.trim() || !telemetryEnabled(env))
+        return;
+    const now = Date.now();
+    const markers = readSessionMarkers(env);
+    markers[workspaceKey(workspaceRoot)] = {
+        session: hashTelemetryId(sessionId.trim()),
+        at: now,
+    };
+    const kept = Object.entries(markers)
+        .filter(([, marker]) => typeof marker?.at === "number" &&
+        now - marker.at <= SESSION_MARKER_MAX_AGE_MS)
+        .sort(([, left], [, right]) => right.at - left.at)
+        .slice(0, MAX_SESSION_MARKERS);
+    try {
+        const file = sessionMarkersPath(env);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+        fs.writeFileSync(temporary, JSON.stringify(Object.fromEntries(kept)));
+        fs.renameSync(temporary, file);
+    }
+    catch {
+        // Telemetry is best effort and must never disturb the hook.
+    }
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * Hashed session a host hook recently reported for this directory or the
+ * nearest ancestor that has one, or undefined.
+ */
+export function workspaceSessionHash(startDirectory, env = process.env) {
+    const markers = readSessionMarkers(env);
+    const now = Date.now();
+    let current = path.resolve(startDirectory);
+    for (;;) {
+        const marker = markers[workspaceKey(current)];
+        if (marker &&
+            typeof marker.session === "string" &&
+            typeof marker.at === "number" &&
+            now - marker.at <= SESSION_MARKER_MAX_AGE_MS) {
+            return marker.session;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function sessionProperty(source, env) {
+    const sessionId = source.sessionId?.trim() || detectTelemetrySession(env);
+    if (sessionId)
+        return hashTelemetryId(sessionId);
+    return source.workspaceRoot
+        ? (workspaceSessionHash(source.workspaceRoot, env) ?? null)
+        : null;
+}
 function baseProperties(source, env) {
-    const sessionId = source.sessionId?.trim();
     return {
         distinct_id: installId(env),
         $process_person_profile: false,
@@ -253,8 +421,11 @@ function baseProperties(source, env) {
         $lib: "kibi",
         package: source.packageName,
         package_version: source.packageVersion ?? null,
-        host: source.host?.trim() || "unknown",
-        session: sessionId ? hashTelemetryId(sessionId) : null,
+        host: (source.host?.trim() && hostKey(source.host)) ||
+            detectTelemetryHost(env) ||
+            "unknown",
+        remote: remoteEnvironment(env),
+        session: sessionProperty(source, env),
         os: process.platform,
         arch: process.arch,
         runtime: runtimeName(),
@@ -282,6 +453,20 @@ function appendEvent(event, env) {
     }
 }
 // implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * An error category as sent: fixed identifiers such as `tool_timeout` or
+ * `UPSERT_DRY_RUN_INVALID` pass, lower-cased; anything that looks like free
+ * text is replaced, so a message can never leak through this field.
+ */
+export function telemetryCategory(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    return /^[A-Za-z0-9_.:+-]{1,160}$/.test(trimmed)
+        ? trimmed.toLowerCase()
+        : "unclassified";
+}
+// implements REQ-kibi-anonymous-usage-telemetry
 export function recordOperationTelemetry(source, operation, env = process.env) {
     if (!telemetryEnabled(env))
         return;
@@ -294,7 +479,7 @@ export function recordOperationTelemetry(source, operation, env = process.env) {
             operation: operation.operation,
             status: operation.status,
             duration_ms: Math.max(0, Math.round(operation.durationMs)),
-            error_category: operation.errorCategory ?? null,
+            error_category: telemetryCategory(operation.errorCategory),
             exit_code: operation.exitCode ?? null,
         },
     }, env);
@@ -328,7 +513,9 @@ export function clearTelemetryQueue(env = process.env) {
         return;
     }
     for (const name of names) {
-        if (name === QUEUE_FILE || name.endsWith(SENDING_SUFFIX)) {
+        if (name === QUEUE_FILE ||
+            name === SESSIONS_FILE ||
+            name.endsWith(SENDING_SUFFIX)) {
             fs.rmSync(path.join(directory, name), { force: true });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",