Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
fix(upkeep): honor DO_NOT_TRACK for update checks (#651)
Junpei Zhang7326bdac05de
diff --git a/README.md b/README.mdindex 68a6a061..51daf0e7 100644--- a/README.md+++ b/README.md@@ -531,7 +531,7 @@ _Summary, sources, links, and your text ship today in markdown nodes. The crux s- **On your machine, no key, no network:** the structural code graph. `trail build` (wiring graph + per-file cards), `trail build --check`, `trail ask`, learnings and `trail check` are deterministic. They never call a model.- **Through your provider key:** the LLM-written parts. `trail build --deep` adds the concept nodes (file summaries + node synthesis) and the per-symbol summaries and cruxes. The graft map is vendor-neutral: set `GRAFT_PROVIDER` (`openai` for any OpenAI-compatible endpoint, `anthropic` for the native API, or `litellm` / `orcarouter` for a gateway that speaks the OpenAI-compatible format), your `GRAFT_API_KEY`, `GRAFT_MODEL`, and, for the `openai` wire format, `GRAFT_BASE_URL` to point at OpenRouter, Fireworks, Groq, a LiteLLM proxy, a local server, or OpenAI itself. Or pass `--provider/--model/--api-key/--base-url` on the command line. (`OPENROUTER_API_KEY` still works as a deprecated fallback, and `ORCAROUTER_API_KEY` as a second one.)- **Through Trail, only if you connect a workspace:** the learnings in the repos you picked, and the searches and checks that used them. See [What stays on your machine](#what-stays-on-your-machine).-- **Anonymous usage stats:** a daily npm version check and one batched usage ping. The ping carries buckets and fixed labels only: never your code, file paths, repo name, symbols, queries, learnings or error messages. [`TELEMETRY.md`](TELEMETRY.md) is the complete list and `trail telemetry debug` prints exactly what your machine would send. Turn it off with `trail telemetry disable`, `DO_NOT_TRACK=1`, or by unchecking the box in `trail init`; it is off in CI and in any build from source.+- **Anonymous usage stats:** a daily npm version check and one batched usage ping. The ping carries buckets and fixed labels only: never your code, file paths, repo name, symbols, queries, learnings or error messages. [`TELEMETRY.md`](TELEMETRY.md) is the complete list and `trail telemetry debug` prints exactly what your machine would send. `DO_NOT_TRACK=1` disables both network calls; `trail telemetry disable` or unchecking the box in `trail init` disables only the usage ping. The ping is off in CI and in any build from source.Settings keep their `GRAFT_` names. See [`.env.example`](.env.example) for the full list (model, base URL, graph directory).diff --git a/src/telemetry/notice.ts b/src/telemetry/notice.tsindex 93d1c70f..35b8c438 100644--- a/src/telemetry/notice.ts+++ b/src/telemetry/notice.ts@@ -14,7 +14,7 @@* who see it — this catches everyone else.*/import { patchState, readState } from './identity.js';-import { explainOff, offReason } from './gate.js';+import { doNotTrack, explainOff, offReason } from './gate.js';import { peek } from './queue.js';import { buildBatch } from './send.js';import { posthogHost } from './key.js';@@ -54,6 +54,7 @@ export function formatStatus(home?: string, env?: NodeJS.ProcessEnv): string {: `telemetry: ${explainOff(reason)}`,` contract: ${TELEMETRY_DOC_URL}`,];+ if (doNotTrack(env)) lines.push(' update check: off — DO_NOT_TRACK is set');if (reason === null || reason === 'disabled') {lines.push(` endpoint: ${posthogHost()}`);lines.push(` queued: ${pending} event${pending === 1 ? '' : 's'} waiting for the next daily flush`);diff --git a/src/upkeep.ts b/src/upkeep.tsindex 3414bdb6..5c1dfdc9 100644--- a/src/upkeep.ts+++ b/src/upkeep.ts@@ -127,7 +127,13 @@ export function needsRefresh(cache: UpdateCache | null, now = Date.now()): boole* Only called from long-lived or already-slow contexts (a CLI command, MCP* boot) — never from a hook, which reads the cache and nothing else.*/-export function maybeRefreshInBackground(home?: string, now = Date.now()): boolean {+export function maybeRefreshInBackground(+ home?: string,+ now = Date.now(),+ env: NodeJS.ProcessEnv = process.env,+): boolean {+ const doNotTrack = env.DO_NOT_TRACK;+ if (doNotTrack !== undefined && doNotTrack !== '' && doNotTrack !== '0') return false;const cache = readUpdateCache(home);if (!needsRefresh(cache, now)) return false;writeUpdateCache({ latest: cache?.latest ?? null, checkedAt: now }, home);diff --git a/test/telemetry-notice.test.ts b/test/telemetry-notice.test.tsindex df7529e1..ed539174 100644--- a/test/telemetry-notice.test.ts+++ b/test/telemetry-notice.test.ts@@ -123,5 +123,7 @@ test('CI gets no notice — there is no one there to read a disclosure', () => {test('DO_NOT_TRACK gets no notice either', () => {const h = home('notice-dnt', { installId: 'x' });assert.equal(firstRunNotice(h, { DO_NOT_TRACK: '1' }), null);- assert.match(formatStatus(h, { DO_NOT_TRACK: '1' }), /DO_NOT_TRACK/);+ const status = formatStatus(h, { DO_NOT_TRACK: '1' });+ assert.match(status, /DO_NOT_TRACK/);+ assert.match(status, /update check: off/);});diff --git a/test/upkeep.test.ts b/test/upkeep.test.tsindex 1f9850a3..e06cbd19 100644--- a/test/upkeep.test.ts+++ b/test/upkeep.test.ts@@ -9,6 +9,7 @@ import {formatUpdateNudge,formatWiringRefresh,isNewer,+ maybeRefreshInBackground,needsRefresh,readStamp,reconcileWiring,@@ -67,6 +68,14 @@ test('the update cache is machine-global, not per-repo', () => {assert.equal(updateCachePath('/home/dev'), join('/home/dev', '.graft', 'update-check.json'));});+test('DO_NOT_TRACK disables the automatic update check', () => {+ const home = tmpRepo('upkeep-do-not-track');+ const now = 1_700_000_000_000;++ assert.equal(maybeRefreshInBackground(home, now, { DO_NOT_TRACK: '1' }), false);+ assert.equal(existsSync(updateCachePath(home)), false, 'a disabled check leaves no attempt stamp');+});+test('runningVersion resolves this package, not the caller depth', () => {const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string };assert.equal(runningVersion(), pkg.version);