@bli-cockpit/telemetry-core 0.1.29 → 0.1.31

package/dist/collector-heartbeat.d.ts

@@ -99,6 +99,11 @@ export declare const CollectorHeartbeatSchema: z.ZodObject<{
         }, z.core.$strict>;
         reasons: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         bin_found: z.ZodOptional<z.ZodBoolean>;
+        hook_runs_24h: z.ZodOptional<z.ZodNumber>;
+        hook_timeouts_24h: z.ZodOptional<z.ZodNumber>;
+        hook_printed_24h: z.ZodOptional<z.ZodNumber>;
+        hook_failed_24h: z.ZodOptional<z.ZodNumber>;
+        hook_stats_reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     setup_receipt: z.ZodOptional<z.ZodObject<{
         schema_version: z.ZodLiteral<"setup-receipt.v1">;

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./evidence-reconcile.js";
 export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";
 export * from "./local-config.js";
+export * from "./memory-hook-stats.js";
 export * from "./memory-install-receipt.js";
 export * from "./paths.js";
 export * from "./privacy.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./evidence-reconcile.js";
 export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";
 export * from "./local-config.js";
+export * from "./memory-hook-stats.js";
 export * from "./memory-install-receipt.js";
 export * from "./paths.js";
 export * from "./privacy.js";

package/dist/ingest-dto.d.ts

@@ -401,6 +401,8 @@ export declare const TelemetryIngestEnvelopeSchema: z.ZodObject<{
         started_at: z.ZodString;
         updated_at: z.ZodOptional<z.ZodString>;
         active_ticket_id: z.ZodOptional<z.ZodString>;
+        tower_issue_id: z.ZodOptional<z.ZodString>;
+        linear_ticket_id: z.ZodOptional<z.ZodString>;
         ticket_binding_candidates: z.ZodDefault<z.ZodArray<z.ZodObject<{
             ticket_id: z.ZodString;
             binding_source: z.ZodEnum<{

package/dist/memory-hook-stats.d.ts

@@ -0,0 +1,105 @@
+/**
+ * THE HOOK COUNTER, SHARED (BLI-3788).
+ *
+ * `@bli-cockpit/memory-mcp` WRITES this file — one hook run at a time, on the
+ * machine, counts only — and `@bli-cockpit/local-collector` READS it once a
+ * tick to put `hook_timeouts_24h` on the heartbeat's memory receipt. The two
+ * packages are published separately and never import each other, so the
+ * contract between them lives here, in the one package they both depend on:
+ * the file's address, its shape, and the rule for turning hourly buckets into
+ * a 24-hour number.
+ *
+ * The alternative was two copies of a JSON shape kept in step by comment, and
+ * BLI-2541 is what that costs — a fixture built from our own formatting rather
+ * than from the real thing, green while the fleet was broken.
+ *
+ * WHY IT EXISTS AT ALL: a prompt hook that misses its deadline prints NOTHING,
+ * deliberately. That is right for the person and blind for the operator, and
+ * QA tick 18 found the recall silently missing on 4 of 6 runs with no surface
+ * anywhere reporting it. These counts are that silence made countable.
+ *
+ * WHAT MAY NEVER BE IN IT: a prompt, a memory, a container tag, a path, a
+ * token, or any string that did not come from the hook's own closed reason
+ * vocabulary. Counts and hour labels, nothing else.
+ */
+import { z } from "zod";
+export declare const MEMORY_HOOK_STATS_SCHEMA_VERSION = "memory-hook-stats.v1";
+/** The file name, in the collector's state directory. One spelling, here. */
+export declare const MEMORY_HOOK_STATS_FILE_NAME = "memory-hook-stats.json";
+/** The three hook events, spelled as the bin's subcommands are. */
+export declare const MEMORY_HOOK_STAT_EVENTS: readonly ["session-start", "prompt", "stop"];
+export type MemoryHookStatEvent = (typeof MEMORY_HOOK_STAT_EVENTS)[number];
+/**
+ * One hour of one event.
+ *
+ * `timeouts` is counted apart from `failed` (a refusal, an outage, an
+ * unpaired machine — different fixes) and apart from `empty` (the record was
+ * genuinely silent, which is an answer and not a fault). Collapsing them is
+ * exactly how "the door is slow" and "the shelf is empty" became one
+ * unreadable number in the first place.
+ */
+export declare const MemoryHookCountsSchema: z.ZodObject<{
+    runs: z.ZodNumber;
+    printed: z.ZodNumber;
+    empty: z.ZodNumber;
+    timeouts: z.ZodNumber;
+    failed: z.ZodNumber;
+    skipped: z.ZodNumber;
+}, z.core.$strict>;
+export type MemoryHookCounts = z.infer<typeof MemoryHookCountsSchema>;
+/** `YYYY-MM-DDTHH` in UTC — the bucket key, and the reason the window is exact. */
+export declare const MEMORY_HOOK_BUCKET_PATTERN: RegExp;
+export declare const MemoryHookStatsFileSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"memory-hook-stats.v1">;
+    buckets: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodEnum<{
+        "session-start": "session-start";
+        prompt: "prompt";
+        stop: "stop";
+    }> & z.core.$partial, z.ZodObject<{
+        runs: z.ZodNumber;
+        printed: z.ZodNumber;
+        empty: z.ZodNumber;
+        timeouts: z.ZodNumber;
+        failed: z.ZodNumber;
+        skipped: z.ZodNumber;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type MemoryHookStatsFile = z.infer<typeof MemoryHookStatsFileSchema>;
+export declare function memoryHookStatsFilePath(homeDir: string): string;
+/** The hour a moment belongs to. UTC, so two machines agree on a boundary. */
+export declare function memoryHookHourBucket(at: Date): string;
+export declare function emptyMemoryHookCounts(): MemoryHookCounts;
+export interface MemoryHookWindow {
+    runs: number;
+    printed: number;
+    timeouts: number;
+    failed: number;
+    /** Buckets that were inside the window and had something in them. */
+    hours: number;
+}
+/**
+ * Sum one event's buckets over the last `hours` hours, ending at `now`.
+ *
+ * The window is inclusive of the hour `now` falls in, so a run three minutes
+ * ago counts; that makes the last bucket partial, which is the honest
+ * direction for a gauge whose whole job is to notice that something is going
+ * wrong RIGHT NOW.
+ */
+export declare function summariseMemoryHookWindow(file: MemoryHookStatsFile, event: MemoryHookStatEvent, options: {
+    now: Date;
+    hours?: number;
+}): MemoryHookWindow;
+/**
+ * Parse what is on disk, or say why not.
+ *
+ * A file this version does not recognise is REPLACED by the writer and
+ * reported as unreadable by the reader — never merged into a shape it was not
+ * written in, which would publish a number nobody can explain.
+ */
+export declare function parseMemoryHookStats(raw: string): {
+    ok: true;
+    file: MemoryHookStatsFile;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/memory-hook-stats.js

@@ -0,0 +1,122 @@
+/**
+ * THE HOOK COUNTER, SHARED (BLI-3788).
+ *
+ * `@bli-cockpit/memory-mcp` WRITES this file — one hook run at a time, on the
+ * machine, counts only — and `@bli-cockpit/local-collector` READS it once a
+ * tick to put `hook_timeouts_24h` on the heartbeat's memory receipt. The two
+ * packages are published separately and never import each other, so the
+ * contract between them lives here, in the one package they both depend on:
+ * the file's address, its shape, and the rule for turning hourly buckets into
+ * a 24-hour number.
+ *
+ * The alternative was two copies of a JSON shape kept in step by comment, and
+ * BLI-2541 is what that costs — a fixture built from our own formatting rather
+ * than from the real thing, green while the fleet was broken.
+ *
+ * WHY IT EXISTS AT ALL: a prompt hook that misses its deadline prints NOTHING,
+ * deliberately. That is right for the person and blind for the operator, and
+ * QA tick 18 found the recall silently missing on 4 of 6 runs with no surface
+ * anywhere reporting it. These counts are that silence made countable.
+ *
+ * WHAT MAY NEVER BE IN IT: a prompt, a memory, a container tag, a path, a
+ * token, or any string that did not come from the hook's own closed reason
+ * vocabulary. Counts and hour labels, nothing else.
+ */
+import { z } from "zod";
+import { getUserLocalCockpitPaths } from "./paths.js";
+export const MEMORY_HOOK_STATS_SCHEMA_VERSION = "memory-hook-stats.v1";
+/** The file name, in the collector's state directory. One spelling, here. */
+export const MEMORY_HOOK_STATS_FILE_NAME = "memory-hook-stats.json";
+/** The three hook events, spelled as the bin's subcommands are. */
+export const MEMORY_HOOK_STAT_EVENTS = ["session-start", "prompt", "stop"];
+/**
+ * One hour of one event.
+ *
+ * `timeouts` is counted apart from `failed` (a refusal, an outage, an
+ * unpaired machine — different fixes) and apart from `empty` (the record was
+ * genuinely silent, which is an answer and not a fault). Collapsing them is
+ * exactly how "the door is slow" and "the shelf is empty" became one
+ * unreadable number in the first place.
+ */
+export const MemoryHookCountsSchema = z
+    .object({
+    runs: z.number().int().min(0),
+    printed: z.number().int().min(0),
+    empty: z.number().int().min(0),
+    timeouts: z.number().int().min(0),
+    failed: z.number().int().min(0),
+    skipped: z.number().int().min(0),
+})
+    .strict();
+/** `YYYY-MM-DDTHH` in UTC — the bucket key, and the reason the window is exact. */
+export const MEMORY_HOOK_BUCKET_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}$/u;
+export const MemoryHookStatsFileSchema = z
+    .object({
+    schema_version: z.literal(MEMORY_HOOK_STATS_SCHEMA_VERSION),
+    // `partialRecord`, not `record`: a record keyed by an enum is EXHAUSTIVE
+    // in zod 4 — every event would be required — and an hour in which only
+    // the prompt hook ran is the ordinary case, not a malformed file.
+    buckets: z.record(z.string().regex(MEMORY_HOOK_BUCKET_PATTERN), z.partialRecord(z.enum(MEMORY_HOOK_STAT_EVENTS), MemoryHookCountsSchema)),
+})
+    .strict();
+export function memoryHookStatsFilePath(homeDir) {
+    const paths = getUserLocalCockpitPaths(homeDir);
+    const separator = paths.state_dir.includes("\\") ? "\\" : "/";
+    return `${paths.state_dir}${separator}${MEMORY_HOOK_STATS_FILE_NAME}`;
+}
+/** The hour a moment belongs to. UTC, so two machines agree on a boundary. */
+export function memoryHookHourBucket(at) {
+    return at.toISOString().slice(0, 13);
+}
+export function emptyMemoryHookCounts() {
+    return { runs: 0, printed: 0, empty: 0, timeouts: 0, failed: 0, skipped: 0 };
+}
+/**
+ * Sum one event's buckets over the last `hours` hours, ending at `now`.
+ *
+ * The window is inclusive of the hour `now` falls in, so a run three minutes
+ * ago counts; that makes the last bucket partial, which is the honest
+ * direction for a gauge whose whole job is to notice that something is going
+ * wrong RIGHT NOW.
+ */
+export function summariseMemoryHookWindow(file, event, options) {
+    const hours = options.hours ?? 24;
+    const earliest = memoryHookHourBucket(new Date(options.now.getTime() - (hours - 1) * 3_600_000));
+    const latest = memoryHookHourBucket(options.now);
+    const total = { runs: 0, printed: 0, timeouts: 0, failed: 0, hours: 0 };
+    for (const [bucket, events] of Object.entries(file.buckets)) {
+        // Lexical order is chronological for this key, which is the only reason a
+        // string comparison is allowed to stand in for a date one here.
+        if (bucket < earliest || bucket > latest)
+            continue;
+        const counts = events[event];
+        if (!counts)
+            continue;
+        total.runs += counts.runs;
+        total.printed += counts.printed;
+        total.timeouts += counts.timeouts;
+        total.failed += counts.failed;
+        total.hours += 1;
+    }
+    return total;
+}
+/**
+ * Parse what is on disk, or say why not.
+ *
+ * A file this version does not recognise is REPLACED by the writer and
+ * reported as unreadable by the reader — never merged into a shape it was not
+ * written in, which would publish a number nobody can explain.
+ */
+export function parseMemoryHookStats(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: "hook_stats_unparseable" };
+    }
+    const result = MemoryHookStatsFileSchema.safeParse(parsed);
+    if (!result.success)
+        return { ok: false, reason: "hook_stats_unrecognised_shape" };
+    return { ok: true, file: result.data };
+}

package/dist/memory-install-receipt.d.ts

@@ -109,6 +109,11 @@ export declare const MemoryInstallReceiptSchema: z.ZodObject<{
     }, z.core.$strict>;
     reasons: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     bin_found: z.ZodOptional<z.ZodBoolean>;
+    hook_runs_24h: z.ZodOptional<z.ZodNumber>;
+    hook_timeouts_24h: z.ZodOptional<z.ZodNumber>;
+    hook_printed_24h: z.ZodOptional<z.ZodNumber>;
+    hook_failed_24h: z.ZodOptional<z.ZodNumber>;
+    hook_stats_reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type MemoryInstallReceipt = z.infer<typeof MemoryInstallReceiptSchema>;
 /** Every piece is `ok`. The one question the board asks first. */

package/dist/memory-install-receipt.js

@@ -103,6 +103,36 @@ export const MemoryInstallReceiptSchema = z
      * (`no_bin_no_write`).
      */
     bin_found: z.boolean().optional(),
+    /**
+     * DID THE HOOKS ACTUALLY WORK? (BLI-3788)
+     *
+     * The five words above say a hook is REGISTERED. They cannot say whether
+     * it did anything, and a prompt hook that loses its deadline prints
+     * nothing by design — so a machine could read `memory: claude mcp ✓ hooks
+     * ✓` while two thirds of that person's turns silently got no recall (QA
+     * tick 18). These four counts, summed over the last 24 hours from the
+     * hook's own on-disk counter, are that gap closed:
+     *
+     *   `hook_runs_24h`      hooks that ran at all — the denominator, without
+     *                        which a timeout count says nothing
+     *   `hook_timeouts_24h`  runs that lost the clock and printed nothing
+     *   `hook_printed_24h`   runs that injected a block
+     *   `hook_failed_24h`    runs that could not run (a refusal, an outage)
+     *
+     * An honestly EMPTY shelf is in none of them but `runs`, because zero hits
+     * is a real answer and not a fault. All four are optional: a collector or
+     * a memory-mcp older than this ticket reports none, and absent must read
+     * as "not reported", never as zero.
+     *
+     * They are a FLOOR. Two hooks finishing in the same millisecond can lose
+     * one increment to the file rename, which understates and cannot invent.
+     */
+    hook_runs_24h: z.number().int().min(0).optional(),
+    hook_timeouts_24h: z.number().int().min(0).optional(),
+    hook_printed_24h: z.number().int().min(0).optional(),
+    hook_failed_24h: z.number().int().min(0).optional(),
+    /** Named when the counts are absent because the file could not be read. */
+    hook_stats_reason: ReasonLabelSchema.optional(),
 })
     .strict();
 /** Every piece is `ok`. The one question the board asks first. */

package/dist/ticket-id.d.ts

@@ -1 +1,44 @@
+/**
+ * WHICH TRACKER MINTED THIS ID (BLI-3779).
+ *
+ * Tower runs its own issue tracker beside Linear during the dual-run, and both
+ * spell an identifier the same way: a team key, a hyphen, a number. Two facts
+ * tell them apart, and neither is a guess:
+ *
+ *  - **The number.** Tower's tracker mints from `BLI-10001` up;
+ *    Linear's BLI team is in the 3,000s. An id at or above
+ *    `TOWER_NATIVE_ISSUE_NUMBER_FLOOR` is one only Tower could have issued.
+ *    The dashboard's `lib/jarvis/chat-v2/issue-word-boundary.ts` (BLI-3783)
+ *    re-exports this constant rather than keeping a second copy of it.
+ *  - **The title.** A Tower-native row that mirrors a Linear ticket ends its
+ *    title with `[BLI-3779]` — Edward's dogfooding convention, 2026-09-05 —
+ *    so the Linear id a Tower row stands for is READ, never inferred.
+ *
+ * Exact after upper-casing, never fuzzy: the `person-identity.ts` discipline,
+ * for the same reason. A wrong match binds a session's work to somebody
+ * else's ticket.
+ */
+/**
+ * The first identifier Tower's own tracker mints. Linear's BLI team is in the
+ * 3,000s as of 2026-09-05 and would need six thousand more tickets to reach
+ * it; if it ever does, this constant moves and `work_issues.source` becomes
+ * the only honest discriminator.
+ */
+export declare const TOWER_NATIVE_ISSUE_NUMBER_FLOOR = 10000;
 export declare function parseTicketIdFromText(value: string): string | null;
+/** Is this the shape either tracker uses for an identifier? */
+export declare function looksLikeIssueIdentifier(value: string): boolean;
+/** The one spelling of an identifier: trimmed and upper-cased, or null. */
+export declare function normalizeIssueIdentifier(value: string): string | null;
+/**
+ * Is this an id only TOWER's tracker could have minted? A fact about the
+ * number, not a claim about any row: `BLI-10042` cannot be in Linear whether
+ * or not it is in Tower.
+ */
+export declare function isTowerNativeIssueId(value: string): boolean;
+/**
+ * The Linear id a Tower-native title mirrors: the LAST `[BLI-3779]` in the
+ * title, because a title may quote another ticket in its prose and the
+ * convention puts the mirrored id at the end.
+ */
+export declare function mirroredTicketIdInTitle(title: string): string | null;

package/dist/ticket-id.js

@@ -1,4 +1,61 @@
+/**
+ * WHICH TRACKER MINTED THIS ID (BLI-3779).
+ *
+ * Tower runs its own issue tracker beside Linear during the dual-run, and both
+ * spell an identifier the same way: a team key, a hyphen, a number. Two facts
+ * tell them apart, and neither is a guess:
+ *
+ *  - **The number.** Tower's tracker mints from `BLI-10001` up;
+ *    Linear's BLI team is in the 3,000s. An id at or above
+ *    `TOWER_NATIVE_ISSUE_NUMBER_FLOOR` is one only Tower could have issued.
+ *    The dashboard's `lib/jarvis/chat-v2/issue-word-boundary.ts` (BLI-3783)
+ *    re-exports this constant rather than keeping a second copy of it.
+ *  - **The title.** A Tower-native row that mirrors a Linear ticket ends its
+ *    title with `[BLI-3779]` — Edward's dogfooding convention, 2026-09-05 —
+ *    so the Linear id a Tower row stands for is READ, never inferred.
+ *
+ * Exact after upper-casing, never fuzzy: the `person-identity.ts` discipline,
+ * for the same reason. A wrong match binds a session's work to somebody
+ * else's ticket.
+ */
+/** `BLI-3654`, `TRI-12` — a team key, a hyphen, a number, and nothing else. */
+const ISSUE_IDENTIFIER = /^[A-Z][A-Z0-9]{1,12}-\d+$/;
+/**
+ * The first identifier Tower's own tracker mints. Linear's BLI team is in the
+ * 3,000s as of 2026-09-05 and would need six thousand more tickets to reach
+ * it; if it ever does, this constant moves and `work_issues.source` becomes
+ * the only honest discriminator.
+ */
+export const TOWER_NATIVE_ISSUE_NUMBER_FLOOR = 10_000;
 export function parseTicketIdFromText(value) {
     const match = value.match(/\b[A-Z][A-Z0-9]{1,12}-\d+\b/);
     return match?.[0] ?? null;
 }
+/** Is this the shape either tracker uses for an identifier? */
+export function looksLikeIssueIdentifier(value) {
+    return ISSUE_IDENTIFIER.test(value.trim().toUpperCase());
+}
+/** The one spelling of an identifier: trimmed and upper-cased, or null. */
+export function normalizeIssueIdentifier(value) {
+    const normalized = value.trim().toUpperCase();
+    return ISSUE_IDENTIFIER.test(normalized) ? normalized : null;
+}
+/**
+ * Is this an id only TOWER's tracker could have minted? A fact about the
+ * number, not a claim about any row: `BLI-10042` cannot be in Linear whether
+ * or not it is in Tower.
+ */
+export function isTowerNativeIssueId(value) {
+    const match = /^[A-Z][A-Z0-9]{1,12}-(\d+)$/.exec(value.trim().toUpperCase());
+    return match ? Number(match[1]) >= TOWER_NATIVE_ISSUE_NUMBER_FLOOR : false;
+}
+/**
+ * The Linear id a Tower-native title mirrors: the LAST `[BLI-3779]` in the
+ * title, because a title may quote another ticket in its prose and the
+ * convention puts the mirrored id at the end.
+ */
+export function mirroredTicketIdInTitle(title) {
+    const matches = [...title.matchAll(/\[([A-Z][A-Z0-9]{1,12}-\d+)\]/gi)];
+    const last = matches.at(-1);
+    return last ? last[1].toUpperCase() : null;
+}

package/dist/work-context.d.ts

@@ -85,6 +85,8 @@ export declare const LocalWorkContextSchema: z.ZodObject<{
     started_at: z.ZodString;
     updated_at: z.ZodOptional<z.ZodString>;
     active_ticket_id: z.ZodOptional<z.ZodString>;
+    tower_issue_id: z.ZodOptional<z.ZodString>;
+    linear_ticket_id: z.ZodOptional<z.ZodString>;
     ticket_binding_candidates: z.ZodDefault<z.ZodArray<z.ZodObject<{
         ticket_id: z.ZodString;
         binding_source: z.ZodEnum<{

package/dist/work-context.js

@@ -76,6 +76,20 @@ export const LocalWorkContextSchema = z
     started_at: IsoDateTimeSchema,
     updated_at: IsoDateTimeSchema.optional(),
     active_ticket_id: NonEmptyStringSchema.optional(),
+    /**
+     * BLI-3779, the dual-run: one piece of work has an id in TWO trackers, so
+     * the context carries both beside `active_ticket_id` (which stays exactly
+     * what the person typed — rewriting it would move every downstream
+     * attribution to an id nobody bound).
+     *
+     * `tower_issue_id` is a `work_issues.identifier` (`BLI-10019`);
+     * `linear_ticket_id` is the Linear one (`BLI-3779`). Both OPTIONAL and
+     * both absent when nothing was resolved: `cockpit start` never blocks a
+     * session on a tracker lookup (session-first commandment), so an
+     * unresolved ticket is a named gap, never a missing context.
+     */
+    tower_issue_id: NonEmptyStringSchema.optional(),
+    linear_ticket_id: NonEmptyStringSchema.optional(),
     ticket_binding_candidates: z
         .array(TicketBindingCandidateSchema)
         .default([]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/telemetry-core",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",