@aligndottech/cli 0.37.1 → 0.38.0

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.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"usage-telemetry.js","sourceRoot":"","sources":["../../src/lib/usage-telemetry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"usage-telemetry.js","sourceRoot":"","sources":["../../src/lib/usage-telemetry.ts"],"names":[],"mappings":"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"}

package/dist/lib/user-hooks.d.ts

@@ -0,0 +1,15 @@
+export type HookHost = 'codex' | 'cursor' | 'copilot';
+export interface UserHookTarget {
+    host: HookHost;
+    /** The hook file for this host, e.g. ~/.codex/hooks.json. */
+    path: string;
+}
+export declare function advisoryHookCommand(host: HookHost, env?: string): string;
+export declare function writeUserHooks(target: UserHookTarget, env?: string): void;
+/**
+ * Take our entries back out. Returns whether there was anything of ours to remove.
+ * Deletes the file only when nothing but what we wrote (plus the version we added) is left,
+ * so a file the user pre-populated survives with their hooks in it.
+ */
+export declare function removeUserHooks(target: UserHookTarget): boolean;
+//# sourceMappingURL=user-hooks.d.ts.map

package/dist/lib/user-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-hooks.d.ts","sourceRoot":"","sources":["../../src/lib/user-hooks.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAIxE;AA6FD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAkBzE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAwB/D"}