@aligndottech/cli 0.37.1 → 0.38.1

package/dist/lib/telemetry-consent.js

@@ -1,13 +1,23 @@
 import * as p from '@clack/prompts';
+import { telemetryDisabledByEnv } from './telemetry-env.js';
 /**
  * ALI-618 D3: the one-time local-mode consent prompt, shown from `runLocalSetup()`.
  *
- * Never asks twice - a decision already on disk (granted OR declined) is left alone. Never
- * prompts without a TTY on both streams: a piped `setup --local` run hangs on a prompt it
- * cannot answer, and a closed stdin crashes clack's raw-mode init AFTER the real setup work has
- * already succeeded (the align-cli#118 lesson, `setup-local-non-tty.test.ts`). A non-interactive
- * run leaves consent UNSET rather than implicitly declined - a scripted first run may be a CI
- * smoke test, not a real user's choice, and it can still be asked on a later interactive run.
+ * Never asks twice - a decision already on disk (granted, declined, or `align telemetry off`)
+ * is left alone. Never prompts without a TTY on both streams: a piped `setup --local` run
+ * hangs on a prompt it cannot answer, and a closed stdin crashes clack's raw-mode init AFTER
+ * the real setup work has already succeeded (the align-cli#118 lesson,
+ * `setup-local-non-tty.test.ts`). A non-interactive run leaves consent UNSET rather than
+ * implicitly declined - a scripted first run may be a CI smoke test, not a real user's choice,
+ * and it can still be asked on a later interactive run.
+ *
+ * ALI-954: an env var that already turns everything off (`DO_NOT_TRACK=1`, `ALIGN_TELEMETRY=0`)
+ * skips the question with a one-line note - asking would imply the answer matters - and
+ * leaves the decision unset for the same reason as the non-interactive case.
+ *
+ * The question is about USAGE (which commands you run). The two anonymous counts the docs
+ * describe (install, setup completed) are not what is being asked about here and send either
+ * way; `align telemetry off` is what stops those (docs/telemetry.md).
  *
  * Default is No: anything other than an explicit yes - the default answer, or Ctrl-C - leaves
  * telemetry off (D3).
@@ -17,6 +27,11 @@ export async function maybeRequestTelemetryConsent(config, interactive) {
         return;
     if (!interactive)
         return;
+    const envSwitch = telemetryDisabledByEnv();
+    if (envSwitch !== undefined) {
+        p.log.info(`Telemetry is off (${envSwitch} is set), so nothing is sent and you won't be asked.`);
+        return;
+    }
     const answer = await p.confirm({
         message: 'Help improve Align? Send an anonymous count of which commands you run - no code, no ' +
             'decisions, no file names, ever. You can change this any time with `align telemetry off`.',

package/dist/lib/telemetry-consent.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-consent.js","sourceRoot":"","sources":["../../src/lib/telemetry-consent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gBAAgB,CAAC;AAWpC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,MAA6B,EAC7B,WAAoB;IAEpB,IAAI,MAAM,CAAC,mBAAmB,EAAE,KAAK,SAAS;QAAE,OAAO;IACvD,IAAI,CAAC,WAAW;QAAE,OAAO;IAEzB,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC;QAC7B,OAAO,EACL,sFAAsF;YACtF,0FAA0F;QAC5F,YAAY,EAAE,KAAK;KACpB,CAAC,CAAC;IAEH,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;AACrF,CAAC"}
+{"version":3,"file":"telemetry-consent.js","sourceRoot":"","sources":["../../src/lib/telemetry-consent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gBAAgB,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAW5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,MAA6B,EAC7B,WAAoB;IAEpB,IAAI,MAAM,CAAC,mBAAmB,EAAE,KAAK,SAAS;QAAE,OAAO;IACvD,IAAI,CAAC,WAAW;QAAE,OAAO;IAEzB,MAAM,SAAS,GAAG,sBAAsB,EAAE,CAAC;IAC3C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,qBAAqB,SAAS,sDAAsD,CAAC,CAAC;QACjG,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC;QAC7B,OAAO,EACL,sFAAsF;YACtF,0FAA0F;QAC5F,YAAY,EAAE,KAAK;KACpB,CAAC,CAAC;IAEH,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;AACrF,CAAC"}

package/dist/lib/telemetry-env.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ALI-954: the two environment variables that turn ALL telemetry off - both tiers, the
+ * default-on beacons included. Its own module so the consent prompt (telemetry-consent.ts)
+ * can ask the same question without importing the emitter, which setup.test.ts mocks down to
+ * one function.
+ *
+ * The two read in opposite directions, each erring toward sending nothing:
+ * - `ALIGN_TELEMETRY` (ours, ALI-618): set and not recognisably ON means OFF. Enumerating the
+ *   falsy words instead guesses at what a user will type, and every miss is a live send by
+ *   someone who believes they opted out.
+ * - `DO_NOT_TRACK` (consoledonottrack.com, the cross-tool convention): set and not
+ *   recognisably OFF means "do not track". The convention says `1`; a user who exports `true`
+ *   means the same thing, and `DO_NOT_TRACK=0` is the one spelling that means nothing.
+ * Both trimmed, because a trailing newline comes free from a `.env` file or a here-doc.
+ */
+export type TelemetryEnvSwitch = 'DO_NOT_TRACK' | 'ALIGN_TELEMETRY';
+/** The variable that disables telemetry, or undefined when neither does. */
+export declare function telemetryDisabledByEnv(): TelemetryEnvSwitch | undefined;
+//# sourceMappingURL=telemetry-env.d.ts.map

package/dist/lib/telemetry-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-env.d.ts","sourceRoot":"","sources":["../../src/lib/telemetry-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG,iBAAiB,CAAC;AAKpE,4EAA4E;AAC5E,wBAAgB,sBAAsB,IAAI,kBAAkB,GAAG,SAAS,CAMvE"}

package/dist/lib/telemetry-env.js

@@ -0,0 +1,13 @@
+const ON_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const OFF_VALUES = new Set(['0', 'false', 'no', 'off']);
+/** The variable that disables telemetry, or undefined when neither does. */
+export function telemetryDisabledByEnv() {
+    const dnt = process.env['DO_NOT_TRACK']?.trim().toLowerCase();
+    if (dnt !== undefined && dnt !== '' && !OFF_VALUES.has(dnt))
+        return 'DO_NOT_TRACK';
+    const ours = process.env['ALIGN_TELEMETRY']?.trim().toLowerCase();
+    if (ours !== undefined && ours !== '' && !ON_VALUES.has(ours))
+        return 'ALIGN_TELEMETRY';
+    return undefined;
+}
+//# sourceMappingURL=telemetry-env.js.map

package/dist/lib/telemetry-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-env.js","sourceRoot":"","sources":["../../src/lib/telemetry-env.ts"],"names":[],"mappings":"AAiBA,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AACtD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAExD,4EAA4E;AAC5E,MAAM,UAAU,sBAAsB;IACpC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9D,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,cAAc,CAAC;IACnF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClE,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,iBAAiB,CAAC;IACxF,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/lib/usage-telemetry.d.ts

@@ -5,13 +5,20 @@ import { type EnvironmentConfig, type TelemetryConsent } from './config.js';
  *
  * Cloud mode is opt-out: a cloud user is already on an authenticated connection to our
  * gateway, so an event about a call already being made is not a new phone-home. Local-embedded
- * mode (ALI-618) is opt-in instead: `--local` users have no account and no tenant, so there is
- * nothing to authenticate an event against, and nothing is sent until the user explicitly
- * consents (see `config.ts`'s `getTelemetryConsent`, set by the one-time prompt in
- * `commands/setup.ts`). Both modes send only a command name, never arguments or content.
+ * mode has two tiers (ALI-954, superseding the ALI-618 "nothing by default" for local mode):
+ * - Two anonymous BEACONS send by default: `cli.funnel.install` (once, on the first ever run,
+ *   see recordInstallBeacon) and `cli.funnel.setup_completed`. They exist so the funnel has a
+ *   denominator - opt-in usage alone cannot tell a 10% consent rate from 90%.
+ * - Everything else (`cli.command`, the other funnel stages) sends only with the stored
+ *   consent (`config.ts`'s `getTelemetryConsent`, set by the one-time prompt at the end of
+ *   setup, default No). `--local` users have no account and no tenant, so there is nothing
+ *   to authenticate an event against - the consent is the gate.
+ * Both modes send only a command name, never arguments or content. docs/telemetry.md lists
+ * every event and field, and telemetry-docs-parity.test.ts keeps that page true.
  *
- * `ALIGN_TELEMETRY=0` (or `false` / `no` / `off`) is the single global off switch and wins in
- * both modes, over a granted local consent included (ALI-618 D3b - one consent model, not two).
+ * `ALIGN_TELEMETRY=0` and `DO_NOT_TRACK=1` (telemetry-env.ts) turn everything off, both tiers,
+ * in both modes, over a granted local consent included (ALI-618 D3b - one consent model, not
+ * two). `align telemetry off` stores 'off', which does the same thing without an env var.
  */
 export declare const TELEMETRY_TIMEOUT_MS = 2000;
 export interface TelemetryStatus {
@@ -22,8 +29,9 @@ export interface TelemetryStatus {
  * ALI-618 D3b: what `align telemetry status` prints. Takes the consent decision as a plain
  * argument rather than reading `config.ts` itself, so the two consent MODELS stay visibly
  * distinct in one function a reader can hold in their head - cloud's opt-out default and
- * local's stored opt-in decision - with `ALIGN_TELEMETRY=0` as the one thing that overrides
- * both, checked first.
+ * local's stored decision (ALI-954: three values, and the two default-on beacons named where
+ * usage is off but they are not) - with the env switches as the thing that overrides both,
+ * checked first.
  */
 export declare function getTelemetryStatus(env: EnvironmentConfig, localConsent: TelemetryConsent | undefined): TelemetryStatus;
 export declare function recordCommandUsage(env: EnvironmentConfig, command: string): Promise<void>;
@@ -31,20 +39,107 @@ export declare function recordCommandUsage(env: EnvironmentConfig, command: stri
  * ALI-795: the activation-funnel stages, matching the gateway's closed enum
  * (telemetryAnonymousRoutes.ts). Repeat-use and D7 are deliberately absent - both derive
  * server-side from install_id timestamps, so a client event would be a second writer.
+ *
+ * ALI-938: `teammate_requested` is the bottom-up-thesis signal - fired by `align invite`
+ * for every genuine attempt to bring a teammate in, whether or not the invite is
+ * actually sent (a member blocked by the org_admin gate is still demand). `align invite`
+ * refuses local-embedded mode outright (it needs a real cloud tenant to invite anyone
+ * into), so in practice this ALWAYS reaches recordFunnelStage with a cloud env and takes
+ * the /telemetry/ingest path, which accepts any eventName as a string. The gateway's
+ * FUNNEL_STAGES enum lists it too since ALI-954, so the local path no longer 400s either.
+ *
+ * ALI-954: `install` is the once-per-install beacon and has its own emitter
+ * (recordInstallBeacon) - it is not offered to recordFunnelStage, whose `command` argument
+ * is a provenance the install beacon must not carry.
+ */
+/**
+ * ALI-835: the stages the gateway ACCEPTS a measurement on. Permission, not obligation - three
+ * of the four come from one `align import sessions` run and carry a count and an agent name,
+ * while `decisions_ratified` comes from `align ratify` and deliberately carries neither, since
+ * a ratification is a person standing behind a claim rather than anything an agent counted.
+ *
+ * Session import is the first funnel event whose value IS a number; every earlier stage only
+ * had to happen.
+ *
+ * Declared above FUNNEL_STAGES and spread into it rather than listed in both, so the four
+ * strings have one writer here as they now do on the gateway side (align-stack #2237).
  */
-export type FunnelStage = 'setup_started' | 'setup_completed' | 'import_completed' | 'mcp_wired' | 'first_useful_decision';
+export declare const SESSION_IMPORT_STAGES: readonly ["sessions_scanned", "candidates_found", "candidates_confirmed", "decisions_ratified"];
+export declare const FUNNEL_STAGES: readonly ["setup_started", "setup_completed", "import_completed", "mcp_wired", "first_useful_decision", "teammate_requested", "sessions_scanned", "candidates_found", "candidates_confirmed", "decisions_ratified"];
+/**
+ * What a session-import stage reports. A count and the agent's name, and nothing else - never a
+ * repo, a path, a session id or a line of any transcript. The gateway refuses both fields on
+ * every other stage.
+ */
+export interface FunnelMeasurement {
+    count: number;
+    agent: string;
+}
+export type FunnelStage = (typeof FUNNEL_STAGES)[number];
+/**
+ * ALI-954: the two stages that send BY DEFAULT in local mode, with no consent - the
+ * denominator of the funnel. `install` goes through recordInstallBeacon; `setup_completed`
+ * goes through recordFunnelStage like every other stage and is the one stage there that
+ * does not read the consent decision. Adding a stage here is a documented promise changing:
+ * docs/telemetry.md lists this set, and telemetry-docs-parity.test.ts checks it.
+ */
+export declare const BEACON_STAGES: readonly ["install", "setup_completed"];
 /**
  * The single funnel-stage emitter. Same consent model as recordCommandUsage, no new
- * consent surface: cloud is opt-out behind a token, local is opt-in behind the stored
- * decision, ALIGN_TELEMETRY=0 beats both. `command` is the stage's provenance
- * ("first_useful_decision via ask"), never arguments or content.
+ * consent surface: cloud is opt-out behind a token, local is behind the stored decision
+ * except for the beacon tier (BEACON_STAGES), and the env switches beat everything.
+ * `command` is the stage's provenance ("first_useful_decision via ask"), never arguments
+ * or content.
  *
  * first_useful_decision is once-per-install, guarded HERE rather than at call sites so
  * there is exactly one enforcement point. Marked before the send, deliberately: a ping
  * lost to a timeout costs one funnel row in the undercount direction, while marking
  * after would re-send forever on a machine that cannot reach the gateway.
+ *
+ * Resolves `true` when a send was made (not necessarily delivered - see the once-mark
+ * reasoning above, the same trade), `false` when this call could not send: opted out, no
+ * consent, no token, the store threw, or - for first_useful_decision only, the one
+ * once-per-install stage - already recorded on this install. ALI-949: the setup wizard
+ * offers setup_started at several checkpoints because local-mode consent arrives
+ * mid-wizard, and this is how it knows which offer landed (lib/setup-funnel.ts).
+ */
+export declare function recordFunnelStage(env: EnvironmentConfig, stage: FunnelStage, command: string, measurement?: FunnelMeasurement): Promise<boolean>;
+/**
+ * ALI-954: the install beacon - the funnel's denominator. Sent from the preAction hook in
+ * index.ts, so it goes out BEFORE any prompt on the very first run of this install id, and
+ * never again. The payload is the CLI version, the OS (`process.platform`, a closed enum the
+ * gateway also constrains), the install id, and the literal command `align` - the endpoint
+ * requires a command and this one must not carry which command was run first, so it sends
+ * the program's own name, which carries no information. Nothing about the repo, the graph,
+ * or the user.
+ *
+ * "First ever run" is a moment, not a state, so the install is marked recorded on that run
+ * whether or not the beacon went out: `DO_NOT_TRACK=1` or `ALIGN_TELEMETRY=0` set before the
+ * first run means it is NEVER sent, by construction, even if the variable is later unset.
+ * That is the opposite trade from first_useful_decision's once-mark (which waits for
+ * sendability so a later opt-in still emits), and it is deliberate: a beacon on the fifth
+ * run would not be the install it claims to be, and "never" is the promise the docs make.
+ *
+ * Two cases do not consume the first run: `align telemetry ...` as the user's first command
+ * (the off switch must not be raced by the thing it switches off), and a run that already
+ * holds a cloud token (cloud mode is unchanged by this ticket - its funnel is the authed
+ * one). Resolves true when a send was made, false otherwise; never throws, like every other
+ * emitter here.
+ */
+export declare function recordInstallBeacon(commandPath: string): Promise<boolean>;
+/**
+ * The command path the postAction hook reports: the full path ("local ask", "import git")
+ * so recordCommandUsage can exclude the offline `local` group, and never the leaf alone.
+ *
+ * ALI-949: the ROOT command has no parent. Bare `align` (`program.action(runDefaultAction)`,
+ * ALI-773) is the primary first-run path, and walking `.parent` from the root yielded '' -
+ * so every bare invocation was reported as no command at all and the funnel's "activated"
+ * stage could not see it. The root reports under the program's own name.
  */
-export declare function recordFunnelStage(env: EnvironmentConfig, stage: FunnelStage, command: string): Promise<void>;
+export declare function invocationCommandPath(actionCommand: {
+    name(): string;
+    parent: unknown;
+}): string;
 /**
  * The `--env` the user actually typed, including one Commander handed to a parent.
  *

package/dist/lib/usage-telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-telemetry.d.ts","sourceRoot":"","sources":["../../src/lib/usage-telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGtG;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AA6C1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,gBAAgB,GAAG,SAAS,GACzC,eAAe,CAcjB;AAED,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8B/F;AAgDD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,iBAAiB,GACjB,kBAAkB,GAClB,WAAW,GACX,uBAAuB,CAAC;AAE5B;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA4Df;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE;IAAE,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CASjG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"usage-telemetry.d.ts","sourceRoot":"","sources":["../../src/lib/usage-telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAKtG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAkC1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,gBAAgB,GAAG,SAAS,GACzC,eAAe,CAyBjB;AAED,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B/F;AAwCD;;;;;;;;;;;;;;;;GAgBG;AACH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,iGAExB,CAAC;AAEX,eAAO,MAAM,aAAa,qNAUhB,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,yCAA0C,CAAC;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,iBAAiB,GAC9B,OAAO,CAAC,OAAO,CAAC,CA8ElB;AA2BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAyB/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE;IAAE,IAAI,IAAI,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAKhG;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE;IAAE,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CASjG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/lib/usage-telemetry.js

@@ -1,4 +1,6 @@
 import { ALIGN_HOSTED_GATEWAY_URL } from './config.js';
+import { telemetryDisabledByEnv } from './telemetry-env.js';
+import { inHookContext } from './hook-context.js';
 import pkg from '../../package.json' with { type: 'json' };
 /**
  * ALI-403: emit one `cli.command` event per invocation so cloud CLI activation and weekly
@@ -6,28 +8,24 @@ import pkg from '../../package.json' with { type: 'json' };
  *
  * Cloud mode is opt-out: a cloud user is already on an authenticated connection to our
  * gateway, so an event about a call already being made is not a new phone-home. Local-embedded
- * mode (ALI-618) is opt-in instead: `--local` users have no account and no tenant, so there is
- * nothing to authenticate an event against, and nothing is sent until the user explicitly
- * consents (see `config.ts`'s `getTelemetryConsent`, set by the one-time prompt in
- * `commands/setup.ts`). Both modes send only a command name, never arguments or content.
+ * mode has two tiers (ALI-954, superseding the ALI-618 "nothing by default" for local mode):
+ * - Two anonymous BEACONS send by default: `cli.funnel.install` (once, on the first ever run,
+ *   see recordInstallBeacon) and `cli.funnel.setup_completed`. They exist so the funnel has a
+ *   denominator - opt-in usage alone cannot tell a 10% consent rate from 90%.
+ * - Everything else (`cli.command`, the other funnel stages) sends only with the stored
+ *   consent (`config.ts`'s `getTelemetryConsent`, set by the one-time prompt at the end of
+ *   setup, default No). `--local` users have no account and no tenant, so there is nothing
+ *   to authenticate an event against - the consent is the gate.
+ * Both modes send only a command name, never arguments or content. docs/telemetry.md lists
+ * every event and field, and telemetry-docs-parity.test.ts keeps that page true.
  *
- * `ALIGN_TELEMETRY=0` (or `false` / `no` / `off`) is the single global off switch and wins in
- * both modes, over a granted local consent included (ALI-618 D3b - one consent model, not two).
+ * `ALIGN_TELEMETRY=0` and `DO_NOT_TRACK=1` (telemetry-env.ts) turn everything off, both tiers,
+ * in both modes, over a granted local consent included (ALI-618 D3b - one consent model, not
+ * two). `align telemetry off` stores 'off', which does the same thing without an env var.
  */
 export const TELEMETRY_TIMEOUT_MS = 2_000;
-/**
- * Set and not recognisably ON means OFF. Enumerating the falsy words instead - `0|false|no|off` -
- * guesses at what a user will type, and every guess that misses is a live send by someone who
- * believes they opted out: `disabled` and `n` both sent. Trimmed, because a trailing space or
- * newline comes free from a `.env` file or a here-doc. Unset is ON, which is the documented
- * cloud default and the only value this cannot see.
- */
-const OPT_IN_VALUES = new Set(['1', 'true', 'yes', 'on']);
 function telemetryOptedOut() {
-    const raw = process.env['ALIGN_TELEMETRY'];
-    if (raw === undefined || raw.trim() === '')
-        return false;
-    return !OPT_IN_VALUES.has(raw.trim().toLowerCase());
+    return telemetryDisabledByEnv() !== undefined;
 }
 /**
  * POST with a hard timeout, and never throw - telemetry must never fail or delay a command. A
@@ -61,21 +59,33 @@ async function postWithTimeout(url, init) {
  * ALI-618 D3b: what `align telemetry status` prints. Takes the consent decision as a plain
  * argument rather than reading `config.ts` itself, so the two consent MODELS stay visibly
  * distinct in one function a reader can hold in their head - cloud's opt-out default and
- * local's stored opt-in decision - with `ALIGN_TELEMETRY=0` as the one thing that overrides
- * both, checked first.
+ * local's stored decision (ALI-954: three values, and the two default-on beacons named where
+ * usage is off but they are not) - with the env switches as the thing that overrides both,
+ * checked first.
  */
 export function getTelemetryStatus(env, localConsent) {
-    if (telemetryOptedOut()) {
-        return { enabled: false, reason: 'off: ALIGN_TELEMETRY is set to an opt-out value' };
+    const envSwitch = telemetryDisabledByEnv();
+    if (envSwitch === 'DO_NOT_TRACK') {
+        return { enabled: false, reason: 'off: DO_NOT_TRACK is set - nothing is sent' };
+    }
+    if (envSwitch === 'ALIGN_TELEMETRY') {
+        return { enabled: false, reason: 'off: ALIGN_TELEMETRY is set to an opt-out value - nothing is sent' };
     }
     if (env.mode === 'local-embedded') {
+        // ALI-954: "off" here is about usage. The two beacons still send unless the user ran
+        // `align telemetry off` (stored 'off') - and the line has to say so, or "off" would be
+        // read as "nothing is sent" over a beacon that still is.
+        const beacons = ' - the two anonymous counts (install, setup completed) still send; `align telemetry off` stops those too';
         if (localConsent === 'granted') {
             return { enabled: true, reason: 'on: local mode, you opted in when asked' };
         }
         if (localConsent === 'declined') {
-            return { enabled: false, reason: 'off: local mode, you declined when asked' };
+            return { enabled: false, reason: `off: local mode, you declined when asked${beacons}` };
         }
-        return { enabled: false, reason: 'off: local mode, you have not been asked yet' };
+        if (localConsent === 'off') {
+            return { enabled: false, reason: 'off: local mode, you ran `align telemetry off` - nothing is sent' };
+        }
+        return { enabled: false, reason: `off: local mode, you have not been asked yet${beacons}` };
     }
     return { enabled: true, reason: 'on: cloud mode, opt-out default' };
 }
@@ -87,9 +97,10 @@ export async function recordCommandUsage(env, command) {
     // is not enough on its own.
     if (command === 'local' || command.startsWith('local '))
         return;
-    // The mode is the consent boundary (PR #77: cloud is opt-out; ALI-618: local is opt-in via a
-    // stored consent decision, never a phone-home by default). It has to gate on its own because
-    // a token can be in scope without cloud consent: ALIGN_TOKEN exported into the shell, or a
+    // The mode is the consent boundary (PR #77: cloud is opt-out; ALI-618: local usage sends
+    // only with the stored consent decision - the ALI-954 beacons are the two named exceptions,
+    // and this per-command ping is not one of them). It has to gate on its own because a token
+    // can be in scope without cloud consent: ALIGN_TOKEN exported into the shell, or a
     // logged-in default env resolved by the caller.
     if (env.mode === 'local-embedded') {
         await recordAnonymousCommandUsage(command);
@@ -131,14 +142,7 @@ async function recordAnonymousCommandUsage(command) {
     const config = createConfigStore();
     if (config.getTelemetryConsent() !== 'granted')
         return;
-    const installId = config.getInstallId();
-    const commandPath = commandPathOf(command);
-    const target = process.env['ALIGN_GATEWAY_URL'] || ALIGN_HOSTED_GATEWAY_URL;
-    await postWithTimeout(`${target}/telemetry/anonymous`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ installId, command: commandPath, cliVersion: pkg.version }),
-    });
+    await postAnonymous({ installId: config.getInstallId(), command: commandPathOf(command), cliVersion: pkg.version });
 }
 /**
  * ALI-795: the command groups whose second word is a SUBCOMMAND, mirroring the gateway's
@@ -155,18 +159,77 @@ function commandPathOf(command) {
         return `${top} ${sub}`;
     return top ?? command;
 }
+/**
+ * ALI-795: the activation-funnel stages, matching the gateway's closed enum
+ * (telemetryAnonymousRoutes.ts). Repeat-use and D7 are deliberately absent - both derive
+ * server-side from install_id timestamps, so a client event would be a second writer.
+ *
+ * ALI-938: `teammate_requested` is the bottom-up-thesis signal - fired by `align invite`
+ * for every genuine attempt to bring a teammate in, whether or not the invite is
+ * actually sent (a member blocked by the org_admin gate is still demand). `align invite`
+ * refuses local-embedded mode outright (it needs a real cloud tenant to invite anyone
+ * into), so in practice this ALWAYS reaches recordFunnelStage with a cloud env and takes
+ * the /telemetry/ingest path, which accepts any eventName as a string. The gateway's
+ * FUNNEL_STAGES enum lists it too since ALI-954, so the local path no longer 400s either.
+ *
+ * ALI-954: `install` is the once-per-install beacon and has its own emitter
+ * (recordInstallBeacon) - it is not offered to recordFunnelStage, whose `command` argument
+ * is a provenance the install beacon must not carry.
+ */
+/**
+ * ALI-835: the stages the gateway ACCEPTS a measurement on. Permission, not obligation - three
+ * of the four come from one `align import sessions` run and carry a count and an agent name,
+ * while `decisions_ratified` comes from `align ratify` and deliberately carries neither, since
+ * a ratification is a person standing behind a claim rather than anything an agent counted.
+ *
+ * Session import is the first funnel event whose value IS a number; every earlier stage only
+ * had to happen.
+ *
+ * Declared above FUNNEL_STAGES and spread into it rather than listed in both, so the four
+ * strings have one writer here as they now do on the gateway side (align-stack #2237).
+ */
+export const SESSION_IMPORT_STAGES = [
+    'sessions_scanned', 'candidates_found', 'candidates_confirmed', 'decisions_ratified',
+];
+export const FUNNEL_STAGES = [
+    'setup_started',
+    'setup_completed',
+    'import_completed',
+    'mcp_wired',
+    'first_useful_decision',
+    'teammate_requested',
+    // The gateway's own FUNNEL_STAGES must list these too or every ping 400s; that half
+    // shipped first, deliberately (align-stack #2237, the ALI-790 lesson).
+    ...SESSION_IMPORT_STAGES,
+];
+/**
+ * ALI-954: the two stages that send BY DEFAULT in local mode, with no consent - the
+ * denominator of the funnel. `install` goes through recordInstallBeacon; `setup_completed`
+ * goes through recordFunnelStage like every other stage and is the one stage there that
+ * does not read the consent decision. Adding a stage here is a documented promise changing:
+ * docs/telemetry.md lists this set, and telemetry-docs-parity.test.ts checks it.
+ */
+export const BEACON_STAGES = ['install', 'setup_completed'];
 /**
  * The single funnel-stage emitter. Same consent model as recordCommandUsage, no new
- * consent surface: cloud is opt-out behind a token, local is opt-in behind the stored
- * decision, ALIGN_TELEMETRY=0 beats both. `command` is the stage's provenance
- * ("first_useful_decision via ask"), never arguments or content.
+ * consent surface: cloud is opt-out behind a token, local is behind the stored decision
+ * except for the beacon tier (BEACON_STAGES), and the env switches beat everything.
+ * `command` is the stage's provenance ("first_useful_decision via ask"), never arguments
+ * or content.
  *
  * first_useful_decision is once-per-install, guarded HERE rather than at call sites so
  * there is exactly one enforcement point. Marked before the send, deliberately: a ping
  * lost to a timeout costs one funnel row in the undercount direction, while marking
  * after would re-send forever on a machine that cannot reach the gateway.
+ *
+ * Resolves `true` when a send was made (not necessarily delivered - see the once-mark
+ * reasoning above, the same trade), `false` when this call could not send: opted out, no
+ * consent, no token, the store threw, or - for first_useful_decision only, the one
+ * once-per-install stage - already recorded on this install. ALI-949: the setup wizard
+ * offers setup_started at several checkpoints because local-mode consent arrives
+ * mid-wizard, and this is how it knows which offer landed (lib/setup-funnel.ts).
  */
-export async function recordFunnelStage(env, stage, command) {
+export async function recordFunnelStage(env, stage, command, measurement) {
     // The whole body is guarded: telemetry must never fail or delay a command (the same
     // invariant postWithTimeout enforces for the network half, extended to the config
     // half). The concrete case: an emitter call site inside a command's try block plus a
@@ -174,11 +237,18 @@ export async function recordFunnelStage(env, stage, command) {
     // in a file this change never touched said so (tdd.md's hand-built-fake rule).
     try {
         if (telemetryOptedOut())
-            return;
+            return false;
+        // ALI-835: never from inside an agent hook. A hook runs on the agent's clock, many times a
+        // session, with nobody watching - so a ping from there would measure an editing loop rather
+        // than a person choosing to do something, which is what every funnel stage means. Guarded
+        // HERE for the same reason first_useful_decision's once-check is: one enforcement point
+        // rather than one per call site.
+        if (inHookContext())
+            return false;
         const { createConfigStore } = await import('./config.js');
         const config = createConfigStore();
         if (stage === 'first_useful_decision' && config.wasFunnelStageRecorded(stage))
-            return;
+            return false;
         // Whether this call CAN send, checked before the once-mark (Copilot on #215):
         // marking an unsendable call permanently burned the stage for exactly the opt-in
         // cohort - a not-yet-consented user's first real answer marked the install, and
@@ -187,26 +257,34 @@ export async function recordFunnelStage(env, stage, command) {
         // re-sending forever.
         const isLocal = env.mode === 'local-embedded';
         const canSend = isLocal
-            ? config.getTelemetryConsent() === 'granted'
+            ? localTierAllows(config.getTelemetryConsent(), stage)
             : Boolean(env.authToken && env.tenantId);
         if (!canSend)
-            return;
+            return false;
         if (stage === 'first_useful_decision')
             config.markFunnelStageRecorded(stage);
         const commandPath = commandPathOf(command);
+        // ALI-835 (Copilot on #286): the measurement is admitted only on the stages the gateway
+        // permits it on. Gated HERE rather than at the two payload sites below, for the same
+        // reason first_useful_decision's once-check is: one enforcement point. The gateway's
+        // schema is `.strict()` with a superRefine refusing `count` and `agent` on every other
+        // stage, so a future call site passing a measurement alongside, say, `mcp_wired` would
+        // 400 the whole ping - and the catch below swallows that, so the stage would go silently
+        // missing rather than fail loudly. Dropping the two fields keeps the stage itself.
+        const measured = measurement && SESSION_IMPORT_STAGES.includes(stage)
+            ? { count: measurement.count, agent: measurement.agent }
+            : {};
         if (isLocal) {
-            const target = process.env['ALIGN_GATEWAY_URL'] || ALIGN_HOSTED_GATEWAY_URL;
-            await postWithTimeout(`${target}/telemetry/anonymous`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    installId: config.getInstallId(),
-                    command: commandPath,
-                    cliVersion: pkg.version,
-                    stage,
-                }),
+            await postAnonymous({
+                installId: config.getInstallId(),
+                command: commandPath,
+                cliVersion: pkg.version,
+                stage,
+                // Spread rather than set: the gateway's schema is `.strict()`, and an explicit
+                // undefined key is still a key.
+                ...measured,
             });
-            return;
+            return true;
         }
         await postWithTimeout(`${env.gatewayUrl}/telemetry/ingest`, {
             method: 'POST',
@@ -219,14 +297,108 @@ export async function recordFunnelStage(env, stage, command) {
                 eventName: `cli.funnel.${stage}`,
                 category: 'engagement',
                 platform: 'cli',
-                properties: { command: commandPath },
+                properties: { command: commandPath, ...measured },
             }),
         });
+        return true;
     }
     catch {
         // Swallowed for the reason above. The funnel loses one row; the command survives.
+        return false;
     }
 }
+/**
+ * ALI-954: whether a local-mode stage may send, given the stored decision. A beacon stage
+ * sends unless the user ran `align telemetry off` (stored 'off'); every other stage needs
+ * a granted consent. A prompt-declined consent ('declined') is a decision about USAGE and
+ * leaves the beacons on - that split is the ticket's decision, and docs/telemetry.md says
+ * it in the user's words.
+ */
+function localTierAllows(consent, stage) {
+    if (BEACON_STAGES.includes(stage))
+        return consent !== 'off';
+    return consent === 'granted';
+}
+/**
+ * The anonymous payload, the one place its shape is spelled. Targets ALIGN_HOSTED_GATEWAY_URL,
+ * never a `gatewayUrl` off the env - see recordAnonymousCommandUsage for why.
+ */
+async function postAnonymous(payload) {
+    const target = process.env['ALIGN_GATEWAY_URL'] || ALIGN_HOSTED_GATEWAY_URL;
+    await postWithTimeout(`${target}/telemetry/anonymous`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+    });
+}
+/**
+ * ALI-954: the install beacon - the funnel's denominator. Sent from the preAction hook in
+ * index.ts, so it goes out BEFORE any prompt on the very first run of this install id, and
+ * never again. The payload is the CLI version, the OS (`process.platform`, a closed enum the
+ * gateway also constrains), the install id, and the literal command `align` - the endpoint
+ * requires a command and this one must not carry which command was run first, so it sends
+ * the program's own name, which carries no information. Nothing about the repo, the graph,
+ * or the user.
+ *
+ * "First ever run" is a moment, not a state, so the install is marked recorded on that run
+ * whether or not the beacon went out: `DO_NOT_TRACK=1` or `ALIGN_TELEMETRY=0` set before the
+ * first run means it is NEVER sent, by construction, even if the variable is later unset.
+ * That is the opposite trade from first_useful_decision's once-mark (which waits for
+ * sendability so a later opt-in still emits), and it is deliberate: a beacon on the fifth
+ * run would not be the install it claims to be, and "never" is the promise the docs make.
+ *
+ * Two cases do not consume the first run: `align telemetry ...` as the user's first command
+ * (the off switch must not be raced by the thing it switches off), and a run that already
+ * holds a cloud token (cloud mode is unchanged by this ticket - its funnel is the authed
+ * one). Resolves true when a send was made, false otherwise; never throws, like every other
+ * emitter here.
+ */
+export async function recordInstallBeacon(commandPath) {
+    try {
+        if (commandPath === 'telemetry' || commandPath.startsWith('telemetry '))
+            return false;
+        const { createConfigStore } = await import('./config.js');
+        const { resolveEnv } = await import('./resolve-env.js');
+        const config = createConfigStore();
+        if (config.wasFunnelStageRecorded('install'))
+            return false;
+        const env = config.getEnvironment(resolveEnv(undefined, { preferLocalEmbedded: true }));
+        if (env.authToken)
+            return false;
+        config.markFunnelStageRecorded('install');
+        if (telemetryOptedOut())
+            return false;
+        if (!localTierAllows(config.getTelemetryConsent(), 'install'))
+            return false;
+        await postAnonymous({
+            installId: config.getInstallId(),
+            command: 'align',
+            cliVersion: pkg.version,
+            stage: 'install',
+            os: process.platform,
+        });
+        return true;
+    }
+    catch {
+        // Telemetry must never fail or delay a command; the funnel loses one row.
+        return false;
+    }
+}
+/**
+ * The command path the postAction hook reports: the full path ("local ask", "import git")
+ * so recordCommandUsage can exclude the offline `local` group, and never the leaf alone.
+ *
+ * ALI-949: the ROOT command has no parent. Bare `align` (`program.action(runDefaultAction)`,
+ * ALI-773) is the primary first-run path, and walking `.parent` from the root yielded '' -
+ * so every bare invocation was reported as no command at all and the funnel's "activated"
+ * stage could not see it. The root reports under the program's own name.
+ */
+export function invocationCommandPath(actionCommand) {
+    const parts = [];
+    for (let c = actionCommand; c?.parent; c = c.parent)
+        parts.unshift(c.name());
+    return parts.length > 0 ? parts.join(' ') : actionCommand.name();
+}
 /**
  * The `--env` the user actually typed, including one Commander handed to a parent.
  *