kibi-agent-core 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # kibi-agent-core
 
+## 0.11.1
+
+### Patch Changes
+
+- The telemetry status carries the channel in effect and where it comes from (`channel`, `channelSource`), and `telemetryChannel` returns both.
+
+- Edit snippets say what the lead requirement must keep true as the claims its facts model, in words with their operator and members (for example "REQ-GREET must keep true: The greet function must not call console.log."), or as the requirement's own statement, instead of listing internal fact IDs and subject keys. A requirement title that an older Kibi cut at a dot inside a name is shown whole.
+
+- f9ec786: Usage telemetry events now carry a `channel`: `release` for an installed Kibi package, `source` when Kibi runs from a checkout of its own repository, or the value of `KIBI_TELEMETRY_CHANNEL` when a harness sets one (for example `agent-test`). Development and test runs can then be filtered out of real usage. Nothing else about what is sent changes.
+
+## 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/knowledge-index.d.ts

@@ -82,6 +82,21 @@ export type EntitySummary = {
      * with canonical relationship-shard records whose `from` is this entity.
      */
     links?: EntityLink[];
+    /** Requirement prose: `semantic_text`, else the body's first paragraph. */
+    statement?: string;
+    /** The claim a fact models, from its typed front matter fields. */
+    claim?: FactClaim;
+};
+/** A fact's typed fields, as authored; absent fields are left out. */
+export type FactClaim = {
+    factKind?: string;
+    subjectKey?: string;
+    propertyKey?: string;
+    operator?: string;
+    /** `value_set` members, or the one scalar value. */
+    values?: string[];
+    unit?: string;
+    claimText?: string;
 };
 /**
  * Read an entity's title, status and outgoing links. Title and status come

package/dist/knowledge-index.js

@@ -636,6 +636,62 @@ const ENTITY_LANES = [
     ["EVT-", "events"],
 ];
 const SAFE_ENTITY_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Front matter scalars a summary keeps, by field name. */
+const SUMMARY_SCALARS = {
+    semantic_text: "statement",
+    fact_kind: "factKind",
+    subject_key: "subjectKey",
+    property_key: "propertyKey",
+    operator: "operator",
+    unit: "unit",
+    claim_text: "claimText",
+};
+const SCALAR_VALUE_FIELDS = new Set([
+    "value_string",
+    "value_int",
+    "value_number",
+    "value_bool",
+]);
+/**
+ * A front matter scalar starting at `lines[index]` with `raw` after its key:
+ * a plain or quoted value with its indented continuation lines, or a block
+ * scalar (`>-`, `|`). Returns the value and the last line it used.
+ */
+function readScalar(lines, index, raw) {
+    const block = /^[>|][+-]?$/.test(raw.trim());
+    const parts = block ? [] : [raw.trim()];
+    let last = index;
+    while (last + 1 < lines.length) {
+        const next = lines[last + 1] ?? "";
+        if (next.trim() === "---" || !/^\s+\S/.test(next))
+            break;
+        if (!block && /^\s+-\s/.test(next))
+            break;
+        parts.push(next.trim());
+        last += 1;
+    }
+    const joined = parts.join(" ").trim();
+    return { value: block ? joined : unquote(joined), last };
+}
+/** The first prose paragraph of a Markdown body, headings skipped. */
+function firstParagraph(lines) {
+    const paragraph = [];
+    for (const line of lines) {
+        const text = line.trim();
+        if (text === "") {
+            if (paragraph.length > 0)
+                break;
+            continue;
+        }
+        if (/^#{1,6}\s/.test(text)) {
+            if (paragraph.length > 0)
+                break;
+            continue;
+        }
+        paragraph.push(text);
+    }
+    return paragraph.length > 0 ? paragraph.join(" ") : undefined;
+}
 const MAX_SUMMARY_LINKS = 24;
 const RELATIONSHIPS_DIR = ".kb/relationships";
 /**
@@ -713,16 +769,53 @@ export function readEntitySummary(workspaceRoot, entityId) {
         return { id: entityId };
     const summary = { id: entityId };
     const authored = [];
+    const claim = {};
+    const values = [];
     let inLinks = false;
+    let inValueSet = false;
     let inOrigin = false;
     let originKind;
     let closed = false;
+    let bodyStart = lines.length;
     let pending;
-    for (const line of lines.slice(1)) {
+    for (let index = 1; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
         if (line.trim() === "---") {
             closed = true;
+            bodyStart = index + 1;
             break;
         }
+        const scalar = /^([a-z_]+):\s*(.*)$/.exec(line);
+        const scalarField = scalar ? SUMMARY_SCALARS[scalar[1] ?? ""] : undefined;
+        if (scalar && scalarField && scalar[2]) {
+            const { value, last } = readScalar(lines, index, scalar[2]);
+            if (value !== "") {
+                if (scalarField === "statement")
+                    summary.statement = value;
+                else if (scalarField !== "values")
+                    claim[scalarField] = value;
+            }
+            index = last;
+            flushLink(authored, pending);
+            pending = undefined;
+            inLinks = false;
+            inValueSet = false;
+            continue;
+        }
+        if (scalar && SCALAR_VALUE_FIELDS.has(scalar[1] ?? "") && scalar[2]) {
+            values.push(unquote(scalar[2]));
+        }
+        const flowSet = /^value_set:\s*\[(.*)\]\s*$/.exec(line);
+        if (flowSet?.[1]?.trim()) {
+            values.push(...flowSet[1].split(",").map((member) => unquote(member)));
+        }
+        if (/^\S/.test(line))
+            inValueSet = /^value_set:\s*$/.test(line);
+        else if (inValueSet) {
+            const member = /^\s*-\s*(.+)$/.exec(line);
+            if (member)
+                values.push(unquote(member[1] ?? ""));
+        }
         // implements REQ-kb-decision-firmness-from-origin
         const flowOrigin = /^origin:\s*\{.*\bkind:\s*["']?([a-z]+)/.exec(line);
         if (flowOrigin)
@@ -791,5 +884,14 @@ export function readEntitySummary(workspaceRoot, entityId) {
     }
     if (links.length > 0)
         summary.links = links;
+    if (values.length > 0)
+        claim.values = values;
+    if (Object.keys(claim).length > 0)
+        summary.claim = claim;
+    if (summary.statement === undefined && lane[1] === "requirements" && closed) {
+        const paragraph = firstParagraph(lines.slice(bodyStart));
+        if (paragraph)
+            summary.statement = paragraph;
+    }
     return summary;
 }

package/dist/snippets.d.ts

@@ -44,10 +44,20 @@ export declare function unreadableManifestNote(relativePath: string): string;
 /** Link types through which a requirement is grounded in semantic facts. */
 export declare const GROUNDING_LINK_TYPES: readonly string[];
 /**
- * What a requirement says must stay true (its linked facts) and the decision
- * behind it (a linked ADR), read from its frontmatter links and
- * relationship-shard records. A retired requirement is not current policy, so
- * its grounding is not presented as something to keep true.
+ * A property fact as a sentence naming its operator and members ("The greet
+ * function must not call console.log"); a predicate or rule fact as the
+ * claim text it models. Undefined for a subject fact and for a fact without
+ * readable fields.
+ */
+export declare function factClaimSentence(summary: EntitySummary): string | undefined;
+/**
+ * What a requirement says must stay true and the decision behind it (a
+ * linked ADR), read from its frontmatter links and relationship-shard
+ * records. Each linked fact is shown as the claim it models, with its
+ * operator and members (a fact without typed fields by its title); without
+ * one the requirement's own statement is shown. Fact IDs are internal and
+ * never shown. A retired requirement is not current policy, so its grounding
+ * is not presented as something to keep true.
  */
 export declare function requirementGroundingLines(requirementId: string, summarize: Summarize, options?: {
     maxFacts?: number;

package/dist/snippets.js

@@ -18,6 +18,7 @@ const MAX_SYMBOLS_PER_REQUIREMENT = 3;
 const MAX_TESTS = 3;
 const MAX_TITLE = 80;
 const MAX_GROUNDING = 2;
+const MAX_CLAIM = 160;
 /** Files larger than this are not scanned to locate an edit. */
 const MAX_FOCUS_SCAN_BYTES = 2 * 1024 * 1024;
 // implements REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1
@@ -118,10 +119,25 @@ export function describeEntity(summary) {
             : " [exploratory]"
         : "";
     const notable = `${retired}${firmness}`;
-    return summary.title
-        ? `${summary.id}${notable}: ${truncate(summary.title, MAX_TITLE)}`
+    const title = displayTitle(summary);
+    return title
+        ? `${summary.id}${notable}: ${truncate(title, MAX_TITLE)}`
         : `${summary.id}${notable}`;
 }
+/**
+ * The title, completed from the statement when an older title was cut at a
+ * dot inside a name ("...call console" for "...call console.log").
+ */
+function displayTitle(summary) {
+    const { title, statement } = summary;
+    if (!title || !statement?.startsWith(title))
+        return title;
+    const rest = statement.slice(title.length);
+    if (!/^\.\S/.test(rest))
+        return title;
+    const end = rest.search(/[.!?](?:\s|$)/);
+    return end < 0 ? statement : statement.slice(0, title.length + end);
+}
 function jsonString(value) {
     return JSON.stringify(value);
 }
@@ -178,12 +194,94 @@ export const GROUNDING_LINK_TYPES = [
     "requires_predicate",
     "requires_rule",
 ];
+/** Set-valued properties whose claim reads as a verb on the members. */
+const PROPERTY_VERBS = {
+    calls: "call",
+    imports: "import",
+    reads: "read",
+    uses: "use",
+    throws: "throw",
+};
+/** How a scalar or set property is constrained, by fact operator. */
+const OPERATOR_PHRASES = {
+    eq: "must be",
+    neq: "must not be",
+    lt: "must be less than",
+    lte: "must be at most",
+    gt: "must be greater than",
+    gte: "must be at least",
+    matches: "must match",
+    includes: "must include",
+    subset_of: "must be within",
+    excludes: "must not include",
+};
+function joinMembers(values, conjunction) {
+    if (values.length <= 1)
+        return values[0] ?? "";
+    return `${values.slice(0, -1).join(", ")} ${conjunction} ${values.at(-1)}`;
+}
+const MODAL = /^(.{1,100}?)\s+(?:must|may|can|cannot|should|shall|will|never)\b/i;
+/** The claim's own subject words, before its modal verb, else the key's. */
+function subjectPhrase(claim) {
+    const spoken = MODAL.exec(claim.claimText ?? "")?.[1];
+    if (spoken)
+        return spoken;
+    return claim.subjectKey?.replace(/[._]+/g, " ").trim() || undefined;
+}
+// implements REQ-agent-core-edit-snippets
+/**
+ * A property fact as a sentence naming its operator and members ("The greet
+ * function must not call console.log"); a predicate or rule fact as the
+ * claim text it models. Undefined for a subject fact and for a fact without
+ * readable fields.
+ */
+export function factClaimSentence(summary) {
+    const claim = summary.claim;
+    if (!claim || claim.factKind === "subject")
+        return undefined;
+    const values = claim.values ?? [];
+    if (claim.propertyKey && claim.operator && values.length > 0) {
+        const subject = subjectPhrase(claim);
+        if (!subject)
+            return claim.claimText;
+        const verb = PROPERTY_VERBS[claim.propertyKey];
+        const verbal = verb
+            ? {
+                excludes: `must not ${verb} ${joinMembers(values, "or")}`,
+                includes: `must ${verb} ${joinMembers(values, "and")}`,
+                subset_of: `may ${verb} only ${joinMembers(values, "or")}`,
+                eq: `must ${verb} exactly ${joinMembers(values, "and")}`,
+            }[claim.operator]
+            : undefined;
+        if (verbal)
+            return `${subject} ${verbal}`;
+        const phrase = OPERATOR_PHRASES[claim.operator];
+        if (phrase) {
+            const property = claim.propertyKey.replace(/_+/g, " ");
+            const unit = claim.unit ? ` ${claim.unit}` : "";
+            return `${subject}: ${property} ${phrase} ${values.join(", ")}${unit}`;
+        }
+    }
+    return claim.claimText;
+}
+/** A fact's claim sentence, else its authored title; a subject fact adds nothing. */
+function groundingText(summary) {
+    if (summary.claim?.factKind === "subject")
+        return undefined;
+    return factClaimSentence(summary) ?? summary.title;
+}
+function withoutClosingStop(text) {
+    return text.replace(/[.\s]+$/, "");
+}
 // implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
 /**
- * What a requirement says must stay true (its linked facts) and the decision
- * behind it (a linked ADR), read from its frontmatter links and
- * relationship-shard records. A retired requirement is not current policy, so
- * its grounding is not presented as something to keep true.
+ * What a requirement says must stay true and the decision behind it (a
+ * linked ADR), read from its frontmatter links and relationship-shard
+ * records. Each linked fact is shown as the claim it models, with its
+ * operator and members (a fact without typed fields by its title); without
+ * one the requirement's own statement is shown. Fact IDs are internal and
+ * never shown. A retired requirement is not current policy, so its grounding
+ * is not presented as something to keep true.
  */
 export function requirementGroundingLines(requirementId, summarize, options = {}) {
     const maxFacts = options.maxFacts ?? MAX_GROUNDING;
@@ -203,11 +301,24 @@ export function requirementGroundingLines(requirementId, summarize, options = {}
     ];
     const lines = [];
     if (facts.length > 0) {
-        const shown = facts
-            .slice(0, maxFacts)
-            .map((id) => describeEntity(summarize(id)));
-        const more = facts.length > maxFacts ? ` +${facts.length - maxFacts}` : "";
-        lines.push(`${requirementId} must keep true: ${shown.join("; ")}${more}.`);
+        const claims = [
+            ...new Set(facts
+                .map((id) => groundingText(summarize(id)))
+                .filter((sentence) => Boolean(sentence))
+                .map(withoutClosingStop)),
+        ];
+        const statement = requirement.statement
+            ? withoutClosingStop(requirement.statement)
+            : undefined;
+        const shown = claims.length > 0
+            ? claims.slice(0, maxFacts)
+            : statement
+                ? [statement]
+                : [];
+        const more = claims.length > maxFacts ? ` +${claims.length - maxFacts} more` : "";
+        if (shown.length > 0) {
+            lines.push(`${requirementId} must keep true: ${shown.map((claim) => truncate(claim, MAX_CLAIM)).join("; ")}${more}.`);
+        }
     }
     const adr = adrs[0];
     if (adr)

package/dist/usage-telemetry.d.ts

@@ -14,7 +14,11 @@
  * 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. Runs of Kibi from a checkout of its own
+ * repository, and runs a harness marks with `KIBI_TELEMETRY_CHANNEL`, are
+ * still sent but carry a `channel` other than `release`, so they can be
+ * filtered out of real usage.
  */
 /** Public, write-only PostHog project key: it can send events, not read them. */
 export declare const DEFAULT_TELEMETRY_KEY = "phc_A5z8jRhD528abGJiTtPfgu4d4hpbEbfiJr9iUGn9TMsY";
@@ -32,7 +36,16 @@ export type TelemetryStatus = {
     /** Why telemetry is on or off, e.g. `KIBI_TELEMETRY=0` or `default`. */
     reason: string;
     directory: string;
+    /** The channel events carry, e.g. `release`, `source` or `agent-test`. */
+    channel: string;
+    /** Where the channel comes from. */
+    channelSource: TelemetryChannelSource;
 };
+/**
+ * `KIBI_TELEMETRY_CHANNEL` (a harness set it), `checkout` (Kibi runs from a
+ * checkout of its own repository) or `installed` (an installed package).
+ */
+export type TelemetryChannelSource = "KIBI_TELEMETRY_CHANNEL" | "checkout" | "installed";
 /** Summary of one Kibi operation run through MCP or the CLI. */
 export type OperationTelemetry = {
     interface: "mcp" | "cli";
@@ -62,11 +75,40 @@ 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;
+/**
+ * Where a run comes from: the `KIBI_TELEMETRY_CHANNEL` a harness sets (for
+ * example `agent-test`), `source` when Kibi runs from a checkout of its own
+ * repository (local development, the repository's own hooks, e2e and agent
+ * test rounds built from source), and `release` for an installed package.
+ */
+export declare function detectTelemetryChannel(env?: Env, moduleFile?: string | null): string;
+/** The channel in effect and where it comes from. */
+export declare function telemetryChannel(env?: Env, moduleFile?: string | null): {
+    channel: string;
+    source: TelemetryChannelSource;
+};
 /** 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 +131,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

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 /**
  * Anonymous usage telemetry shared by the CLI, the MCP server and the host
  * hooks.
@@ -19,7 +20,11 @@ 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. Runs of Kibi from a checkout of its own
+ * repository, and runs a harness marks with `KIBI_TELEMETRY_CHANNEL`, are
+ * still sent but carry a `channel` other than `release`, so they can be
+ * filtered out of real usage.
  */
 // implements REQ-kibi-anonymous-usage-telemetry
 /** Public, write-only PostHog project key: it can send events, not read them. */
@@ -29,6 +34,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 +109,158 @@ 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}`);
+}
+/** The Kibi monorepo root's package name. */
+const KIBI_REPOSITORY_PACKAGE = "kibi";
+/** This module's file, or undefined when a bundle format drops `import.meta.url`. */
+function thisModuleFile() {
+    try {
+        const url = import.meta.url;
+        return typeof url === "string" && url !== ""
+            ? fileURLToPath(url)
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a file belongs to a checkout of the Kibi repository rather than to
+ * an installed package. Installed copies live under `node_modules` or in a
+ * host's plugin cache; a checkout has the monorepo root `package.json` (named
+ * `kibi`, with a `packages/agent-core` workspace) above the file.
+ */
+function insideKibiCheckout(file) {
+    const resolved = realDirectory(file);
+    if (resolved.split(/[\\/]/).includes("node_modules"))
+        return false;
+    let current = path.dirname(resolved);
+    for (;;) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(current, "package.json"), "utf8"));
+            if (manifest.name === KIBI_REPOSITORY_PACKAGE &&
+                fs.existsSync(path.join(current, "packages", "agent-core"))) {
+                return true;
+            }
+        }
+        catch {
+            // No readable manifest here; keep walking up.
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+const checkoutCache = new Map();
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * Where a run comes from: the `KIBI_TELEMETRY_CHANNEL` a harness sets (for
+ * example `agent-test`), `source` when Kibi runs from a checkout of its own
+ * repository (local development, the repository's own hooks, e2e and agent
+ * test rounds built from source), and `release` for an installed package.
+ */
+export function detectTelemetryChannel(env = process.env, moduleFile = thisModuleFile() ?? null) {
+    return telemetryChannel(env, moduleFile).channel;
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/** The channel in effect and where it comes from. */
+export function telemetryChannel(env = process.env, moduleFile = thisModuleFile() ?? null) {
+    const explicit = env.KIBI_TELEMETRY_CHANNEL?.trim();
+    if (explicit)
+        return {
+            channel: telemetryCategory(explicit) ?? "release",
+            source: "KIBI_TELEMETRY_CHANNEL",
+        };
+    if (!moduleFile)
+        return { channel: "release", source: "installed" };
+    let fromCheckout = checkoutCache.get(moduleFile);
+    if (fromCheckout === undefined) {
+        fromCheckout = insideKibiCheckout(moduleFile);
+        checkoutCache.set(moduleFile, fromCheckout);
+    }
+    return fromCheckout
+        ? { channel: "source", source: "checkout" }
+        : { channel: "release", source: "installed" };
+}
+// 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();
@@ -146,10 +307,13 @@ export function setTelemetryPreference(preference, env = process.env) {
  */
 export function telemetryStatus(env = process.env) {
     const directory = telemetryDirectory(env);
+    const { channel, source } = telemetryChannel(env);
     const status = (enabled, reason) => ({
         enabled,
         reason,
         directory,
+        channel,
+        channelSource: source,
     });
     const explicit = flagValue(env.KIBI_TELEMETRY);
     if (explicit === false)
@@ -176,6 +340,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 +411,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 +501,12 @@ 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),
+        channel: detectTelemetryChannel(env),
+        session: sessionProperty(source, env),
         os: process.platform,
         arch: process.arch,
         runtime: runtimeName(),
@@ -282,6 +534,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 +560,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 +594,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.1",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",