trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/telemetry/contract.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The telemetry contract: the complete, machine-enforced list of what graft may
+ * send. `TELEMETRY.md` is the same list in prose, and the two are kept in
+ * lockstep — an event or property that is not in this file cannot be sent, and
+ * one that is not in `TELEMETRY.md` must not be added here.
+ *
+ * Why an allowlist rather than a review rule: every telemetry incident in the
+ * tools we studied came from a call site quietly adding a property nobody
+ * audited. `track()` (track.ts) drops unknown events and unknown keys instead of
+ * trusting its callers, so a future `track('query', { path })` sends `query`
+ * with no `path` rather than leaking one. The blast radius of a careless call
+ * site is "we lose a metric", never "we received someone's source tree".
+ *
+ * The other half of that guarantee is the value side: every number crosses as a
+ * BUCKET and every string as a member of a fixed union. A raw file count plus a
+ * language set starts to fingerprint a specific repo; `"100-500"` does not. A
+ * raw error message is a path, a symbol, and sometimes a snippet of code; an
+ * enum member is not.
+ *
+ * This module is pure — no I/O, no config, no clock. It is the file a reviewer
+ * (or a suspicious user, since the repo is public) reads to verify the claim.
+ */
+/**
+ * The contract itself. Common properties (see {@link COMMON_KEYS}) are stamped
+ * centrally by `track()` and are deliberately not repeated per event.
+ */
+export declare const EVENTS: Record<string, ReadonlySet<string>>;
+/** The labels {@link hookMsBucket} returns. */
+export declare const HOOK_MS_BUCKETS: readonly ["<50ms", "50-100ms", "100-300ms", "300ms-1s", "1-3s", "3s+"];
+/**
+ * The values an event's key may take, where the contract fixes them. `track()`
+ * drops a value outside the set, key and all, so a call site that passes a
+ * skill's name, a prompt or an error line under an allowed key sends nothing
+ * for it. Every key of the skills events is listed here.
+ */
+export declare const VALUES: Record<string, Record<string, ReadonlySet<string>>>;
+/** Whether `value` may go under `key` of `event`: always, unless {@link VALUES} fixes the key's values. */
+export declare function allowedValue(event: string, key: string, value: string): boolean;
+/** Stamped on every event by `track()`; not listed per event above. */
+export declare const COMMON_KEYS: readonly ["app_version", "os", "arch", "node_major", "ci", "agent_host", "cli_name", "repo_id"];
+/** Which surface issued a query. `hook` is Claude Code's prompt hook, which
+ *  queries on the user's behalf without them typing a command. */
+export type Surface = 'cli' | 'mcp' | 'hook';
+/** Which editor/agent graft is running under. Derived from the surface and the
+ *  wiring on disk — never from a hostname, a username, or an env var's value. */
+export type AgentHost = 'claude-code' | 'cursor' | 'copilot' | 'mcp' | 'cli';
+/**
+ * The commands worth counting. A command absent here is simply not reported —
+ * `track()` drops the event rather than sending a free-form string, which is
+ * what keeps a future `graft <something-user-named>` from becoming a data leak.
+ */
+export declare const TRACKED_COMMANDS: readonly ["ask", "grep", "callers", "skeleton", "map", "check", "blast", "viz"];
+export type TrackedCommand = (typeof TRACKED_COMMANDS)[number];
+export declare function isTrackedCommand(name: string): name is TrackedCommand;
+/**
+ * How a sign-in handoff ended.
+ *
+ * Five categories and nothing else, because the alternative — the error string
+ * the CLI already prints — carries a repo slug and a URL. `timed_out` and
+ * `no_tty` are deliberately apart: one is a person who opened the browser and
+ * did not finish, the other is a machine that was never able to open one, and
+ * treating them alike would read as a product problem where there is only a
+ * remote shell. `stopped` is Ctrl-C while waiting: a person changing their
+ * mind, not a browser that never came back.
+ */
+export declare const BRAIN_SIGNUP_OUTCOMES: readonly ["linked", "timed_out", "no_tty", "bad_callback", "stopped"];
+export type BrainSignupOutcome = (typeof BRAIN_SIGNUP_OUTCOMES)[number];
+/** Where a failing build died. Coarse on purpose: enough to route a bug, not
+ *  enough to describe anyone's repo. */
+export declare const BUILD_STAGES: readonly ["walk", "extract", "graph", "summarize", "synthesize", "write"];
+export type BuildStage = (typeof BUILD_STAGES)[number];
+/**
+ * The failure taxonomy. Anything unrecognised becomes `E_UNKNOWN` — the point of
+ * a closed set is that an unclassified error contributes a count and nothing
+ * else, so no message text can ride along inside a "code".
+ */
+export declare const ERROR_CODES: readonly ["E_UNKNOWN", "E_PARSE", "E_TIMEOUT", "E_LLM", "E_AUTH", "E_RATE_LIMIT", "E_NETWORK", "E_DISK", "E_PERMISSION", "E_OOM", "E_LOCK"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+/**
+ * Map a thrown value to a code without letting its text through. Only fixed
+ * substrings are matched, and only a member of {@link ERROR_CODES} is returned —
+ * the error's own message is never the return value, not even in part.
+ */
+export declare function errorCode(err: unknown): ErrorCode;
+/** Repo scale. Exact counts fingerprint a repo; these five labels answer the
+ *  only question we have ("toy, service, or monorepo?"). */
+export declare function filesBucket(n: number): string;
+/** Wall-clock for a build. Coarse enough that it says "fast/slow", not "this
+ *  exact machine on this exact tree". */
+export declare function durationBucket(ms: number): string;
+/** Generic small-count bucket, for the per-session read counters. */
+export declare function countBucket(n: number): string;
+/** One hook's wall-clock. The budgets are 50 ms (PreToolUse) and 300 ms (the
+ *  rest), so the labels split there. */
+export declare function hookMsBucket(ms: number): (typeof HOOK_MS_BUCKETS)[number];
+/** Estimated tokens saved in one session — the README's central claim, in the
+ *  only resolution we need to defend it. */
+export declare function savedTokensBucket(n: number): string;
+/**
+ * Languages, normalised, filtered to a safe shape, and capped.
+ *
+ * Sorted so `["go","ts"]` and `["ts","go"]` aggregate as one value, deduped, and
+ * cut to eight — a repo with a very long tail of languages is itself a
+ * distinguishing fact, and the tail answers no question we have.
+ *
+ * The character filter is the part that matters. This is the only property in
+ * the contract that is not drawn from a closed set defined in this file: the
+ * values come from the parser registry, several modules away, via
+ * `languageLabelOf() ?? container.name ?? generic.name ?? "unknown"`. That is
+ * safe today, but it means the no-free-text guarantee would rest on a promise
+ * made elsewhere — and a future generic extractor naming itself after the
+ * extension it matched would quietly turn this into a channel for file
+ * metadata. Anything outside `[a-z0-9+#._-]`, or longer than 24 characters, is
+ * therefore dropped here rather than trusted.
+ */
+export declare function langsValue(langs: readonly string[]): string;
+//# sourceMappingURL=contract.d.ts.map

package/dist/telemetry/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/telemetry/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CA0FtD,CAAC;AAEF,+CAA+C;AAC/C,eAAO,MAAM,eAAe,wEAAyE,CAAC;AAEtG;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAsBtE,CAAC;AAEF,2GAA2G;AAC3G,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAI/E;AAED,uEAAuE;AACvE,eAAO,MAAM,WAAW,iGASd,CAAC;AAMX;kEACkE;AAClE,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAE7C;iFACiF;AACjF,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,iFAEnB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,cAAc,CAErE;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,uEAAwE,CAAC;AAC3G,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;wCACwC;AACxC,eAAO,MAAM,YAAY,2EAA4E,CAAC;AACtG,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,WAAW,6IAGd,CAAC;AACX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAoBjD;AAMD;4DAC4D;AAC5D,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAO7C;AAED;yCACyC;AACzC,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAO7C;AAED;wCACwC;AACxC,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAOzE;AAED;4CAC4C;AAC5C,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAK3D"}

package/dist/telemetry/contract.js

@@ -0,0 +1,341 @@
+/**
+ * The telemetry contract: the complete, machine-enforced list of what graft may
+ * send. `TELEMETRY.md` is the same list in prose, and the two are kept in
+ * lockstep — an event or property that is not in this file cannot be sent, and
+ * one that is not in `TELEMETRY.md` must not be added here.
+ *
+ * Why an allowlist rather than a review rule: every telemetry incident in the
+ * tools we studied came from a call site quietly adding a property nobody
+ * audited. `track()` (track.ts) drops unknown events and unknown keys instead of
+ * trusting its callers, so a future `track('query', { path })` sends `query`
+ * with no `path` rather than leaking one. The blast radius of a careless call
+ * site is "we lose a metric", never "we received someone's source tree".
+ *
+ * The other half of that guarantee is the value side: every number crosses as a
+ * BUCKET and every string as a member of a fixed union. A raw file count plus a
+ * language set starts to fingerprint a specific repo; `"100-500"` does not. A
+ * raw error message is a path, a symbol, and sometimes a snippet of code; an
+ * enum member is not.
+ *
+ * This module is pure — no I/O, no config, no clock. It is the file a reviewer
+ * (or a suspicious user, since the repo is public) reads to verify the claim.
+ */
+/* -------------------------------------------------------------------------- */
+/* the event → allowed-property-keys map                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * The contract itself. Common properties (see {@link COMMON_KEYS}) are stamped
+ * centrally by `track()` and are deliberately not repeated per event.
+ */
+export const EVENTS = {
+    /** Once per machine per version, from the npm postinstall hook. The real
+     *  denominator: a machine that installs graft and never runs a command emits
+     *  this event and no other, so it is the only place the "installed, never
+     *  used" leak is visible at all. Version-scoped rather than once-ever so an
+     *  upgrade counts; distinct install ids still give unique machines.
+     *  `global` separates `npm i -g graft` from a project dependency, which is
+     *  roughly the difference between a person and a lockfile. */
+    install: new Set(['global']),
+    /** Once per machine, the first time a command actually runs. Paired with
+     *  `install`, the gap between the two is the top of the funnel. */
+    first_run: new Set(),
+    /** `graft init` completed. Tells us which agents people actually wire, and
+     *  how many decline telemetry at the picker. */
+    init_completed: new Set(['agents', 'consent']),
+    /** A build finished. The activation event — an install that never reaches one
+     *  of these is the funnel leak we most want to see. */
+    build_completed: new Set(['files_bucket', 'langs', 'mode', 'duration_bucket', 'incremental']),
+    /** A build threw. `stage`/`code` are enums; the message never travels. */
+    build_failed: new Set(['stage', 'code']),
+    /** One query, from any surface. The DAU backbone and the dead-command detector. */
+    query: new Set(['command', 'surface', 'hit', 'notes']),
+    /** A trail command handing the agent a sign-in link to pass on. Queued the
+     *  moment the link is printed, so a sign-in somebody walked away from is still
+     *  counted — the settle below never fires for those. */
+    brain_signup_opened: new Set(['mode', 'command', 'wording']),
+    /** That handoff reaching an end. `outcome` is a closed set, so the reason a
+     *  signup failed travels as a category and never as the error's own words. */
+    brain_signup_settled: new Set(['outcome', 'mode', 'duration_bucket']),
+    /** `trail note` saved a session note (into `~/.trail/`). Whether it carries
+     *  a cost, and how many files it is about, as a bucket. The title, the text
+     *  and the paths never travel. The supply side of the notes loop; the
+     *  `notes` property on `query` is the demand side. */
+    note_saved: new Set(['has_cost', 'touches_bucket', 'scope']),
+    /** Once a day per repo, from the session-start hook, for a repo trail runs
+     *  in: whether `.trail/` is committed there, how many learnings it holds,
+     *  as a bucket, and whether this machine shares it with a workspace. With
+     *  `repo_id` and the install id this counts devs and repos touched, and
+     *  repos with Trail committed. Paths and names never travel. */
+    repo_seen: new Set(['trail_committed', 'learnings_bucket', 'workspace']),
+    /** At session start, when the learnings committed on HEAD went up since the
+     *  last session in that clone: how many came in and how many there are, as
+     *  buckets, and whether it's the clone's first look. Committed learnings
+     *  are trail's activation. Paths and titles never travel. */
+    learnings_committed: new Set(['added_bucket', 'total_bucket', 'first_look']),
+    /** `trail init` read the repo's past Claude sessions, the review comments
+     *  on its merged PRs, or Claude Code's memory notes of it (`source`), for
+     *  learnings: how it went, how many sessions or reviewed PRs there were,
+     *  findings offered and saved, how many were left out for naming no code
+     *  (`filtered`), and how many of those offered and saved were the team's,
+     *  as buckets, how long it took, and the model. The messages, the comments,
+     *  the notes and the findings never travel. */
+    cold_start: new Set(['source', 'outcome', 'sessions_bucket', 'reviews_bucket', 'offered_bucket', 'filtered_bucket', 'picked_bucket', 'team_offered_bucket', 'team_picked_bucket', 'duration_bucket', 'model']),
+    /** One closed agent session, summarised. `graft_reads` vs `source_reads` is
+     *  the single number that says whether an agent prefers graft to grep; the two
+     *  `*_turns` buckets are the follow-up question — of the turns that used graft,
+     *  how many told the user what it saved. Both are counts of turns, never text. */
+    session_summary: new Set([
+        'graft_reads_bucket', 'source_reads_bucket', 'saved_tokens_bucket',
+        'graft_turns_bucket', 'reported_turns_bucket',
+    ]),
+    /* Learned skills (spec section 20). Every value is a member of a closed set
+     * in {@link VALUES}; a skill's name, its steps, a command, a prompt, a lesson
+     * or a path is never one of them, so none of those can travel. */
+    /** Trail offered to keep a skill (or a lesson, an update, a promotion): at which moment. */
+    skill_offered: new Set(['moment']),
+    /** The person's answer to an offer. A withdrawn offer sends nothing. */
+    skill_answer: new Set(['answer']),
+    /** A skill was saved: what it came from, and whose it is. */
+    skill_saved: new Set(['from', 'scope']),
+    /** Trail changed a skill it wrote, on the person's yes or their own command (phase 2): how. */
+    skill_changed: new Set(['op']),
+    /** A skill moved up a scope (phase 3). */
+    skill_promoted: new Set(['to']),
+    /** A joined team repo was pulled (phase 3): how it went. */
+    team_pull: new Set(['outcome']),
+    /** A skill the agent was given ran: whether its own check passed. */
+    skill_used: new Set(['outcome']),
+    /** The weekly value line was said (phase 2): where it went. */
+    skill_value: new Set(['channel']),
+    /** A skill stopped being offered to the agent as is: why. */
+    skill_stale: new Set(['reason']),
+    /** A guardrail fired: which built-in one, and what it did. */
+    guardrail: new Set(['class', 'outcome']),
+    /** A failing command matched a known wall: which one, and whether the person had kept a lesson for it. */
+    wall_hit: new Set(['class', 'had_lesson']),
+    /** How long one hook took, as a bucket: which hook. */
+    hook_ms: new Set(['event', 'bucket']),
+};
+/** The labels {@link hookMsBucket} returns. */
+export const HOOK_MS_BUCKETS = ['<50ms', '50-100ms', '100-300ms', '300ms-1s', '1-3s', '3s+'];
+/**
+ * The values an event's key may take, where the contract fixes them. `track()`
+ * drops a value outside the set, key and all, so a call site that passes a
+ * skill's name, a prompt or an error line under an allowed key sends nothing
+ * for it. Every key of the skills events is listed here.
+ */
+export const VALUES = {
+    skill_offered: { moment: new Set(['asked', 'repeated', 'repaired', 'correction', 'update', 'drift', 'retire', 'promote']) },
+    skill_answer: { answer: new Set(['yes', 'no', 'show', 'none', 'off', 'retire']) },
+    skill_changed: { op: new Set(['update', 'extend', 'split', 'replace', 'retire', 'adopted', 'restore-version']) },
+    skill_value: { channel: new Set(['context', 'notice', 'list']) },
+    skill_saved: { from: new Set(['init', 'repeated', 'repaired', 'asked']), scope: new Set(['personal', 'repo', 'team']) },
+    skill_promoted: { to: new Set(['repo', 'team']) },
+    team_pull: { outcome: new Set(['updated', 'unchanged', 'diverged', 'failed']) },
+    skill_used: { outcome: new Set(['checked', 'failed', 'unchecked']) },
+    skill_stale: { reason: new Set(['failed', 'corrected', 'missing', 'unused', 'unfollowed']) },
+    guardrail: {
+        class: new Set(['no-timeout', 'prod-after-beta']),
+        outcome: new Set(['hint', 'ask', 'deny', 'sure-fail', 'avoided']),
+    },
+    wall_hit: {
+        class: new Set(['timeout-missing', 'zsh-no-match', 'git-https-auth', 'docker-rootless', 'npm-e401-eotp', 'claude-not-logged-in', 'enospc']),
+        had_lesson: new Set(['true', 'false']),
+    },
+    hook_ms: {
+        event: new Set(['session-start', 'prompt', 'pre-bash', 'pre-edit', 'tool-savings', 'post-bash', 'post-bash-fail', 'post-edit', 'post-edit-sync', 'stop']),
+        bucket: new Set(HOOK_MS_BUCKETS),
+    },
+};
+/** Whether `value` may go under `key` of `event`: always, unless {@link VALUES} fixes the key's values. */
+export function allowedValue(event, key, value) {
+    if (!Object.hasOwn(VALUES, event))
+        return true;
+    const keys = VALUES[event];
+    return !Object.hasOwn(keys, key) || keys[key].has(value);
+}
+/** Stamped on every event by `track()`; not listed per event above. */
+export const COMMON_KEYS = [
+    'app_version',
+    'os',
+    'arch',
+    'node_major',
+    'ci',
+    'agent_host',
+    'cli_name',
+    'repo_id',
+];
+/**
+ * The commands worth counting. A command absent here is simply not reported —
+ * `track()` drops the event rather than sending a free-form string, which is
+ * what keeps a future `graft <something-user-named>` from becoming a data leak.
+ */
+export const TRACKED_COMMANDS = [
+    'ask', 'grep', 'callers', 'skeleton', 'map', 'check', 'blast', 'viz',
+];
+export function isTrackedCommand(name) {
+    return TRACKED_COMMANDS.includes(name);
+}
+/**
+ * How a sign-in handoff ended.
+ *
+ * Five categories and nothing else, because the alternative — the error string
+ * the CLI already prints — carries a repo slug and a URL. `timed_out` and
+ * `no_tty` are deliberately apart: one is a person who opened the browser and
+ * did not finish, the other is a machine that was never able to open one, and
+ * treating them alike would read as a product problem where there is only a
+ * remote shell. `stopped` is Ctrl-C while waiting: a person changing their
+ * mind, not a browser that never came back.
+ */
+export const BRAIN_SIGNUP_OUTCOMES = ['linked', 'timed_out', 'no_tty', 'bad_callback', 'stopped'];
+/** Where a failing build died. Coarse on purpose: enough to route a bug, not
+ *  enough to describe anyone's repo. */
+export const BUILD_STAGES = ['walk', 'extract', 'graph', 'summarize', 'synthesize', 'write'];
+/**
+ * The failure taxonomy. Anything unrecognised becomes `E_UNKNOWN` — the point of
+ * a closed set is that an unclassified error contributes a count and nothing
+ * else, so no message text can ride along inside a "code".
+ */
+export const ERROR_CODES = [
+    'E_UNKNOWN', 'E_PARSE', 'E_TIMEOUT', 'E_LLM', 'E_AUTH', 'E_RATE_LIMIT',
+    'E_NETWORK', 'E_DISK', 'E_PERMISSION', 'E_OOM', 'E_LOCK',
+];
+/**
+ * Map a thrown value to a code without letting its text through. Only fixed
+ * substrings are matched, and only a member of {@link ERROR_CODES} is returned —
+ * the error's own message is never the return value, not even in part.
+ */
+export function errorCode(err) {
+    const code = err?.code;
+    if (typeof code === 'string') {
+        if (code === 'ENOSPC' || code === 'EDQUOT')
+            return 'E_DISK';
+        if (code === 'EACCES' || code === 'EPERM')
+            return 'E_PERMISSION';
+        if (code === 'ENOMEM')
+            return 'E_OOM';
+        if (code === 'ETIMEDOUT' || code === 'ESOCKETTIMEDOUT')
+            return 'E_TIMEOUT';
+        if (code === 'ENOTFOUND' || code === 'ECONNREFUSED' || code === 'ECONNRESET')
+            return 'E_NETWORK';
+    }
+    const status = err?.status;
+    if (typeof status === 'number') {
+        if (status === 401 || status === 403)
+            return 'E_AUTH';
+        if (status === 429)
+            return 'E_RATE_LIMIT';
+        if (status >= 500)
+            return 'E_LLM';
+    }
+    const msg = err instanceof Error ? err.message.toLowerCase() : '';
+    if (msg.includes('timeout') || msg.includes('timed out'))
+        return 'E_TIMEOUT';
+    if (msg.includes('parse') || msg.includes('syntax'))
+        return 'E_PARSE';
+    if (msg.includes('lock'))
+        return 'E_LOCK';
+    return 'E_UNKNOWN';
+}
+/* -------------------------------------------------------------------------- */
+/* buckets — every number crosses the wire as a label                         */
+/* -------------------------------------------------------------------------- */
+/** Repo scale. Exact counts fingerprint a repo; these five labels answer the
+ *  only question we have ("toy, service, or monorepo?"). */
+export function filesBucket(n) {
+    if (n <= 0)
+        return '0';
+    if (n < 50)
+        return '1-49';
+    if (n < 200)
+        return '50-199';
+    if (n < 1000)
+        return '200-999';
+    if (n < 5000)
+        return '1000-4999';
+    return '5000+';
+}
+/** Wall-clock for a build. Coarse enough that it says "fast/slow", not "this
+ *  exact machine on this exact tree". */
+export function durationBucket(ms) {
+    const s = ms / 1000;
+    if (s < 1)
+        return '<1s';
+    if (s < 5)
+        return '1-5s';
+    if (s < 30)
+        return '5-30s';
+    if (s < 120)
+        return '30s-2m';
+    if (s < 600)
+        return '2-10m';
+    return '10m+';
+}
+/** Generic small-count bucket, for the per-session read counters. */
+export function countBucket(n) {
+    if (n <= 0)
+        return '0';
+    if (n < 5)
+        return '1-4';
+    if (n < 20)
+        return '5-19';
+    if (n < 50)
+        return '20-49';
+    if (n < 200)
+        return '50-199';
+    return '200+';
+}
+/** One hook's wall-clock. The budgets are 50 ms (PreToolUse) and 300 ms (the
+ *  rest), so the labels split there. */
+export function hookMsBucket(ms) {
+    if (ms < 50)
+        return '<50ms';
+    if (ms < 100)
+        return '50-100ms';
+    if (ms < 300)
+        return '100-300ms';
+    if (ms < 1000)
+        return '300ms-1s';
+    if (ms < 3000)
+        return '1-3s';
+    return '3s+';
+}
+/** Estimated tokens saved in one session — the README's central claim, in the
+ *  only resolution we need to defend it. */
+export function savedTokensBucket(n) {
+    if (n <= 0)
+        return '0';
+    if (n < 1000)
+        return '<1k';
+    if (n < 5000)
+        return '1-5k';
+    if (n < 20000)
+        return '5-20k';
+    if (n < 100000)
+        return '20-100k';
+    return '100k+';
+}
+/**
+ * Languages, normalised, filtered to a safe shape, and capped.
+ *
+ * Sorted so `["go","ts"]` and `["ts","go"]` aggregate as one value, deduped, and
+ * cut to eight — a repo with a very long tail of languages is itself a
+ * distinguishing fact, and the tail answers no question we have.
+ *
+ * The character filter is the part that matters. This is the only property in
+ * the contract that is not drawn from a closed set defined in this file: the
+ * values come from the parser registry, several modules away, via
+ * `languageLabelOf() ?? container.name ?? generic.name ?? "unknown"`. That is
+ * safe today, but it means the no-free-text guarantee would rest on a promise
+ * made elsewhere — and a future generic extractor naming itself after the
+ * extension it matched would quietly turn this into a channel for file
+ * metadata. Anything outside `[a-z0-9+#._-]`, or longer than 24 characters, is
+ * therefore dropped here rather than trusted.
+ */
+export function langsValue(langs) {
+    const clean = langs
+        .map((l) => l.toLowerCase().trim())
+        .filter((l) => l.length > 0 && l.length <= 24 && /^[a-z0-9+#._-]+$/.test(l));
+    return [...new Set(clean)].sort().slice(0, 8).join(',');
+}
+//# sourceMappingURL=contract.js.map

package/dist/telemetry/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/telemetry/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,MAAM,GAAwC;IACzD;;;;;;kEAM8D;IAC9D,OAAO,EAAE,IAAI,GAAG,CAAS,CAAC,QAAQ,CAAC,CAAC;IACpC;uEACmE;IACnE,SAAS,EAAE,IAAI,GAAG,EAAU;IAC5B;oDACgD;IAChD,cAAc,EAAE,IAAI,GAAG,CAAS,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACtD;2DACuD;IACvD,eAAe,EAAE,IAAI,GAAG,CAAS,CAAC,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAC;IACrG,0EAA0E;IAC1E,YAAY,EAAE,IAAI,GAAG,CAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,mFAAmF;IACnF,KAAK,EAAE,IAAI,GAAG,CAAS,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9D;;4DAEwD;IACxD,mBAAmB,EAAE,IAAI,GAAG,CAAS,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IACpE;kFAC8E;IAC9E,oBAAoB,EAAE,IAAI,GAAG,CAAS,CAAC,SAAS,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC7E;;;0DAGsD;IACtD,UAAU,EAAE,IAAI,GAAG,CAAS,CAAC,UAAU,EAAE,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACpE;;;;oEAIgE;IAChE,SAAS,EAAE,IAAI,GAAG,CAAS,CAAC,iBAAiB,EAAE,kBAAkB,EAAE,WAAW,CAAC,CAAC;IAChF;;;iEAG6D;IAC7D,mBAAmB,EAAE,IAAI,GAAG,CAAS,CAAC,cAAc,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;IACpF;;;;;;mDAM+C;IAC/C,UAAU,EAAE,IAAI,GAAG,CAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,OAAO,CAAC,CAAC;IACtN;;;sFAGkF;IAClF,eAAe,EAAE,IAAI,GAAG,CAAS;QAC/B,oBAAoB,EAAE,qBAAqB,EAAE,qBAAqB;QAClE,oBAAoB,EAAE,uBAAuB;KAC9C,CAAC;IAEF;;sEAEkE;IAElE,4FAA4F;IAC5F,aAAa,EAAE,IAAI,GAAG,CAAS,CAAC,QAAQ,CAAC,CAAC;IAC1C,wEAAwE;IACxE,YAAY,EAAE,IAAI,GAAG,CAAS,CAAC,QAAQ,CAAC,CAAC;IACzC,6DAA6D;IAC7D,WAAW,EAAE,IAAI,GAAG,CAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,+FAA+F;IAC/F,aAAa,EAAE,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,CAAC;IACtC,0CAA0C;IAC1C,cAAc,EAAE,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,CAAC;IACvC,4DAA4D;IAC5D,SAAS,EAAE,IAAI,GAAG,CAAS,CAAC,SAAS,CAAC,CAAC;IACvC,qEAAqE;IACrE,UAAU,EAAE,IAAI,GAAG,CAAS,CAAC,SAAS,CAAC,CAAC;IACxC,+DAA+D;IAC/D,WAAW,EAAE,IAAI,GAAG,CAAS,CAAC,SAAS,CAAC,CAAC;IACzC,6DAA6D;IAC7D,WAAW,EAAE,IAAI,GAAG,CAAS,CAAC,QAAQ,CAAC,CAAC;IACxC,8DAA8D;IAC9D,SAAS,EAAE,IAAI,GAAG,CAAS,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAChD,0GAA0G;IAC1G,QAAQ,EAAE,IAAI,GAAG,CAAS,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAClD,uDAAuD;IACvD,OAAO,EAAE,IAAI,GAAG,CAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;CAC9C,CAAC;AAEF,+CAA+C;AAC/C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAU,CAAC;AAEtG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAwD;IACzE,aAAa,EAAE,EAAE,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,EAAE;IAC3H,YAAY,EAAE,EAAE,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,EAAE;IACjF,aAAa,EAAE,EAAE,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC,EAAE;IAChH,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE;IAChE,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE;IACvH,cAAc,EAAE,EAAE,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE;IACjD,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,EAAE;IAC/E,UAAU,EAAE,EAAE,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE;IACpE,WAAW,EAAE,EAAE,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE;IAC5F,SAAS,EAAE;QACT,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;QACjD,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;KAClE;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,sBAAsB,EAAE,QAAQ,CAAC,CAAC;QAC3I,UAAU,EAAE,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACvC;IACD,OAAO,EAAE;QACP,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,eAAe,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;QACzJ,MAAM,EAAE,IAAI,GAAG,CAAC,eAAe,CAAC;KACjC;CACF,CAAC;AAEF,2GAA2G;AAC3G,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,GAAW,EAAE,KAAa;IACpE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAE,CAAC;IAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,aAAa;IACb,IAAI;IACJ,MAAM;IACN,YAAY;IACZ,IAAI;IACJ,YAAY;IACZ,UAAU;IACV,SAAS;CACD,CAAC;AAcX;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK;CAC5D,CAAC;AAGX,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAQ,gBAAsC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,CAAU,CAAC;AAG3G;wCACwC;AACxC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,CAAU,CAAC;AAGtG;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc;IACtE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ;CAChD,CAAC;AAGX;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAY;IACpC,MAAM,IAAI,GAAI,GAAiC,EAAE,IAAI,CAAC;IACtD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC5D,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,cAAc,CAAC;QACjE,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,OAAO,CAAC;QACtC,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,iBAAiB;YAAE,OAAO,WAAW,CAAC;QAC3E,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,cAAc,IAAI,IAAI,KAAK,YAAY;YAAE,OAAO,WAAW,CAAC;IACnG,CAAC;IACD,MAAM,MAAM,GAAI,GAAmC,EAAE,MAAM,CAAC;IAC5D,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,QAAQ,CAAC;QACtD,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,cAAc,CAAC;QAC1C,IAAI,MAAM,IAAI,GAAG;YAAE,OAAO,OAAO,CAAC;IACpC,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAClE,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,WAAW,CAAC;IAC7E,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IACtE,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF;4DAC4D;AAC5D,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IACvB,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,CAAC,GAAG,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC7B,IAAI,CAAC,GAAG,IAAI;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI;QAAE,OAAO,WAAW,CAAC;IACjC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;yCACyC;AACzC,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IACpB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,OAAO,CAAC;IAC3B,IAAI,CAAC,GAAG,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC7B,IAAI,CAAC,GAAG,GAAG;QAAE,OAAO,OAAO,CAAC;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IACvB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,OAAO,CAAC;IAC3B,IAAI,CAAC,GAAG,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC7B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;wCACwC;AACxC,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,OAAO,CAAC;IAC5B,IAAI,EAAE,GAAG,GAAG;QAAE,OAAO,UAAU,CAAC;IAChC,IAAI,EAAE,GAAG,GAAG;QAAE,OAAO,WAAW,CAAC;IACjC,IAAI,EAAE,GAAG,IAAI;QAAE,OAAO,UAAU,CAAC;IACjC,IAAI,EAAE,GAAG,IAAI;QAAE,OAAO,MAAM,CAAC;IAC7B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;4CAC4C;AAC5C,MAAM,UAAU,iBAAiB,CAAC,CAAS;IACzC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IACvB,IAAI,CAAC,GAAG,IAAI;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,CAAC,GAAG,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5B,IAAI,CAAC,GAAG,KAAK;QAAE,OAAO,OAAO,CAAC;IAC9B,IAAI,CAAC,GAAG,MAAM;QAAE,OAAO,SAAS,CAAC;IACjC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU,CAAC,KAAwB;IACjD,MAAM,KAAK,GAAG,KAAK;SAChB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/dist/telemetry/flush.d.ts

@@ -0,0 +1,21 @@
+import { type SendResult } from './send.js';
+/** Matches `UPDATE_TTL_MS`: a day is the natural period for both. */
+export declare const FLUSH_TTL_MS: number;
+export declare function needsFlush(flushedAt: number | undefined, now?: number): boolean;
+/**
+ * Spawn the flush if the queue has something in it and a day has passed. Returns
+ * whether a child was started, for tests. Never waits, never throws.
+ */
+export declare function maybeFlushInBackground(home?: string, now?: number): boolean;
+/**
+ * Whether a failed send is worth keeping the batch for.
+ *
+ * A 5xx or a transport failure is ours to retry — a week offline should not be
+ * a week of lost events. A 4xx is not: a bad key or a malformed batch will fail
+ * identically forever, and retrying it would pin the queue at its cap until it
+ * starts dropping the events that WOULD have sent.
+ */
+export declare function shouldRequeue(res: SendResult): boolean;
+/** The `graft _telemetry-flush` body, running in the detached child. */
+export declare function runFlush(home?: string): Promise<void>;
+//# sourceMappingURL=flush.d.ts.map

package/dist/telemetry/flush.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush.d.ts","sourceRoot":"","sources":["../../src/telemetry/flush.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvD,qEAAqE;AACrE,eAAO,MAAM,YAAY,QAAsB,CAAC;AAMhD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAa,GAAG,OAAO,CAEnF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,OAAO,CAgB/E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAGtD;AAED,wEAAwE;AACxE,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO3D"}

package/dist/telemetry/flush.js

@@ -0,0 +1,85 @@
+/**
+ * Getting the queue off the machine without any command ever waiting for it.
+ *
+ * Deliberately the same shape as `maybeRefreshInBackground` in `upkeep.ts`,
+ * which has been doing this for the npm registry check since 0.7: check a
+ * timestamp, write the timestamp BEFORE spawning so a child that dies cannot
+ * make every subsequent command spawn another one, then `spawn` detached and
+ * `unref`. The parent returns immediately and never learns the outcome.
+ *
+ * Once a day, not once a command. Events are cheap to hold and the questions we
+ * are asking ("how many repos activated this week") do not get better answers
+ * from lower latency.
+ */
+import { spawn } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { graftCliPath } from '../claude/paths.js';
+import { drain, queuePath, requeue } from './queue.js';
+import { patchState, readState } from './identity.js';
+import { sendBatch } from './send.js';
+import { telemetryOn } from './gate.js';
+/** Matches `UPDATE_TTL_MS`: a day is the natural period for both. */
+export const FLUSH_TTL_MS = 24 * 60 * 60 * 1000;
+function queueHasEvents(home) {
+    try {
+        return statSync(queuePath(home)).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function needsFlush(flushedAt, now = Date.now()) {
+    return typeof flushedAt !== 'number' || now - flushedAt >= FLUSH_TTL_MS;
+}
+/**
+ * Spawn the flush if the queue has something in it and a day has passed. Returns
+ * whether a child was started, for tests. Never waits, never throws.
+ */
+export function maybeFlushInBackground(home, now = Date.now()) {
+    try {
+        if (!telemetryOn(home))
+            return false;
+        if (!queueHasEvents(home))
+            return false;
+        if (!needsFlush(readState(home)?.flushedAt, now))
+            return false;
+        patchState({ flushedAt: now }, home); // before the spawn, so a dying child costs one attempt
+        const child = spawn(process.execPath, [graftCliPath(), '_telemetry-flush'], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false; // no spawn available (sandbox, ENOMEM) — try again tomorrow
+    }
+}
+/**
+ * Whether a failed send is worth keeping the batch for.
+ *
+ * A 5xx or a transport failure is ours to retry — a week offline should not be
+ * a week of lost events. A 4xx is not: a bad key or a malformed batch will fail
+ * identically forever, and retrying it would pin the queue at its cap until it
+ * starts dropping the events that WOULD have sent.
+ */
+export function shouldRequeue(res) {
+    if (res.ok)
+        return false;
+    return res.status === undefined || res.status >= 500;
+}
+/** The `graft _telemetry-flush` body, running in the detached child. */
+export async function runFlush(home) {
+    try {
+        if (!telemetryOn(home))
+            return;
+        const events = drain(home);
+        if (events.length === 0)
+            return;
+        if (shouldRequeue(await sendBatch(events)))
+            requeue(events, home);
+    }
+    catch { /* a failed flush is a non-event by design */ }
+}
+//# sourceMappingURL=flush.js.map

package/dist/telemetry/flush.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush.js","sourceRoot":"","sources":["../../src/telemetry/flush.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,SAAS,EAAmB,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,qEAAqE;AACrE,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhD,SAAS,cAAc,CAAC,IAAa;IACnC,IAAI,CAAC;QAAC,OAAO,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,SAA6B,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACxE,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,GAAG,GAAG,SAAS,IAAI,YAAY,CAAC;AAC1E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAa,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACpE,IAAI,CAAC;QACH,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACrC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACxC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAC/D,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,uDAAuD;QAC7F,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,YAAY,EAAE,EAAE,kBAAkB,CAAC,EAAE;YAC1E,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,CAAC,4DAA4D;IAC5E,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,GAAe;IAC3C,IAAI,GAAG,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC;AACvD,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAa;IAC1C,IAAI,CAAC;QACH,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;YAAE,OAAO;QAC/B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAChC,IAAI,aAAa,CAAC,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;YAAE,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC,CAAC,6CAA6C,CAAC,CAAC;AAC3D,CAAC"}

package/dist/telemetry/gate.d.ts

@@ -0,0 +1,30 @@
+export type OffReason = 'no-key' | 'do-not-track' | 'ci' | 'disabled';
+/** The `DO_NOT_TRACK` convention: set and not `0`/empty means "off". */
+export declare function doNotTrack(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Every variable {@link inCi} reads, named once.
+ *
+ * Exported because a test that needs telemetry actually ON has to clear all of
+ * them, and clearing a hand-copied subset is how this list silently drifts: the
+ * `cursor-session-end` test cleared `CI` alone, so it passed on a laptop and failed
+ * on GitHub Actions — where `GITHUB_ACTIONS` is set — for every run until someone
+ * read the log. One list, both callers.
+ */
+export declare const CI_ENV_VARS: readonly ["CI", "GITHUB_ACTIONS", "GITLAB_CI", "BUILDKITE", "CIRCLECI", "TEAMCITY_VERSION", "JENKINS_URL", "TF_BUILD", "BUILD_NUMBER"];
+/**
+ * CI detection. `CI` covers essentially every provider; the rest are the ones
+ * that historically did not set it. Deliberately generous — a false positive
+ * costs one uncounted user, a false negative pollutes the dataset.
+ *
+ * `CI` is the one read with a value test: `CI=false` is a real thing a user sets
+ * to mean "not CI", while the provider-specific vars are presence-only — none of
+ * them is ever deliberately set to a falsy string.
+ */
+export declare function inCi(env?: NodeJS.ProcessEnv): boolean;
+/** Null when telemetry may run, otherwise the first gate that closed. */
+export declare function offReason(home?: string, env?: NodeJS.ProcessEnv): OffReason | null;
+export declare function telemetryOn(home?: string, env?: NodeJS.ProcessEnv): boolean;
+/** One line for `graft telemetry status`, naming the gate that is closed so a
+ *  user who thinks they disabled it can see which switch actually took. */
+export declare function explainOff(reason: OffReason): string;
+//# sourceMappingURL=gate.d.ts.map

package/dist/telemetry/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/telemetry/gate.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,cAAc,GAAG,IAAI,GAAG,UAAU,CAAC;AAEtE,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAGxE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,wIAGd,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAGlE;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,GAAG,IAAI,CAM/F;AAED,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAExF;AAED;2EAC2E;AAC3E,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAOpD"}