@planu/cli 5.6.0 → 5.7.0

package/dist/engine/lifecycle-reconciliation.js

@@ -110,6 +110,41 @@ async function completeForwardReconciliation(args) {
     await args.persistReceipt(args.receiptPath, committed);
     return committed;
 }
+async function resolveReviewDigest(args) {
+    const { input, spec, reason } = args;
+    if (input.declaredDriftKind === 'architectural-premise') {
+        const reviewDigest = digest(reason.trim());
+        if (reviewDigest !== input.implementationReviewDigest) {
+            return failure('declared drift review digest does not match the declared reason', 'RECONCILIATION_STALE');
+        }
+        return { reviewDigest, driftSource: 'declared-architectural-premise' };
+    }
+    const reportPath = join(projectDataDir(args.projectId), 'handoffs', spec.id, 'validation-report.json');
+    let reportBytes;
+    try {
+        const status = await lstat(reportPath);
+        if (status.isSymbolicLink() || !status.isFile()) {
+            return failure('validation report is unsafe');
+        }
+        reportBytes = await readFile(reportPath);
+    }
+    catch {
+        return failure('validation report is missing');
+    }
+    const report = ValidationReportV1Schema.safeParse(JSON.parse(reportBytes.toString('utf8')));
+    if (!report.success ||
+        report.data.passed ||
+        report.data.reviewer.kind !== 'automation' ||
+        report.data.reviewer.agent !== AUTOMATED_VALIDATOR_AGENT ||
+        report.data.reviewer.verdict !== 'changes-requested') {
+        return failure('validation report is not an automated changes-requested finding');
+    }
+    const reviewDigest = digest(reportBytes);
+    if (reviewDigest !== input.implementationReviewDigest) {
+        return failure('implementation review digest does not match validation report', 'RECONCILIATION_STALE');
+    }
+    return { reviewDigest };
+}
 async function validateRequest(args) {
     const { input, spec, context } = args;
     if (context.surface !== 'local-mcp') {
@@ -136,42 +171,41 @@ async function validateRequest(args) {
     if (!latest?.transitionId || latest.transitionId !== input.expectedImplementingTransitionId) {
         return failure('expected implementing transition is stale', 'RECONCILIATION_STALE');
     }
-    const reportPath = join(projectDataDir(args.projectId), 'handoffs', spec.id, 'validation-report.json');
-    let reportBytes;
-    try {
-        const status = await lstat(reportPath);
-        if (status.isSymbolicLink() || !status.isFile()) {
-            return failure('validation report is unsafe');
-        }
-        reportBytes = await readFile(reportPath);
-    }
-    catch {
-        return failure('validation report is missing');
-    }
-    const report = ValidationReportV1Schema.safeParse(JSON.parse(reportBytes.toString('utf8')));
-    if (!report.success ||
-        report.data.passed ||
-        report.data.reviewer.kind !== 'automation' ||
-        report.data.reviewer.agent !== AUTOMATED_VALIDATOR_AGENT ||
-        report.data.reviewer.verdict !== 'changes-requested') {
-        return failure('validation report is not an automated changes-requested finding');
-    }
-    const reviewDigest = digest(reportBytes);
-    if (reviewDigest !== input.implementationReviewDigest) {
-        return failure('implementation review digest does not match validation report', 'RECONCILIATION_STALE');
+    const resolution = await resolveReviewDigest({
+        input,
+        spec,
+        projectId: args.projectId,
+        reason: input.reason,
+    });
+    if (!('reviewDigest' in resolution) || typeof resolution.reviewDigest !== 'string') {
+        return resolution;
     }
+    const resolved = resolution;
     return {
-        reviewDigest,
-        bindingDigest: digest([
-            args.projectId,
-            spec.id,
-            input.reconciliationRequestId,
-            latest.transitionId,
-            reviewDigest,
-            digest(input.reason.trim()),
-        ].join('\0')),
+        reviewDigest: resolved.reviewDigest,
+        driftSource: resolved.driftSource,
+        bindingDigest: computeBindingDigest({
+            projectId: args.projectId,
+            specId: spec.id,
+            requestId: input.reconciliationRequestId,
+            transitionId: latest.transitionId,
+            reviewDigest: resolved.reviewDigest,
+            reasonDigest: digest(input.reason.trim()),
+            driftSource: resolved.driftSource,
+        }),
     };
 }
+function computeBindingDigest(args) {
+    return digest([
+        args.projectId,
+        args.specId,
+        args.requestId,
+        args.transitionId,
+        args.reviewDigest,
+        args.reasonDigest,
+        ...(args.driftSource ? [args.driftSource] : []),
+    ].join('\0'));
+}
 function validateDurableReceiptBinding(args) {
     const { input, receipt } = args;
     if (input.expectedImplementingTransitionId !== receipt.sourceImplementingTransitionId ||
@@ -180,14 +214,15 @@ function validateDurableReceiptBinding(args) {
         digest(input.reason.trim()) !== receipt.reasonDigest) {
         return failure('reconciliation retry binding conflicts with the durable receipt', 'RECONCILIATION_BINDING_CONFLICT');
     }
-    const bindingDigest = digest([
-        args.projectId,
-        args.specId,
-        receipt.requestId,
-        receipt.sourceImplementingTransitionId,
-        receipt.implementationReviewDigest,
-        receipt.reasonDigest,
-    ].join('\0'));
+    const bindingDigest = computeBindingDigest({
+        projectId: args.projectId,
+        specId: args.specId,
+        requestId: receipt.requestId,
+        transitionId: receipt.sourceImplementingTransitionId,
+        reviewDigest: receipt.implementationReviewDigest,
+        reasonDigest: receipt.reasonDigest,
+        driftSource: receipt.driftSource,
+    });
     if (bindingDigest !== receipt.bindingDigest) {
         return failure('durable reconciliation binding is invalid', 'RECONCILIATION_BINDING_CONFLICT');
     }
@@ -198,6 +233,11 @@ async function validateStoredBinding(args) {
     if (durableBindingError) {
         return durableBindingError;
     }
+    if (args.receipt.driftSource === 'declared-architectural-premise') {
+        // No validation-report.json exists for a declared drift; the durable binding
+        // check above already re-derives and verifies the receipt's bindingDigest.
+        return null;
+    }
     const reportPath = join(projectDataDir(args.projectId), 'handoffs', args.specId, 'validation-report.json');
     try {
         const reportBytes = await readFile(reportPath);
@@ -220,6 +260,11 @@ async function validateStoredBinding(args) {
 export async function readCommittedReconciliations(projectId, specId) {
     return readCommittedReconciliationReceipts(projectId, specId);
 }
+function extractDriftSource(validated) {
+    return 'driftSource' in validated && validated.driftSource === 'declared-architectural-premise'
+        ? validated.driftSource
+        : undefined;
+}
 function receiptMatchesRequest(receipt, projectId, specId, requestId) {
     return (receipt.projectId === projectId && receipt.specId === specId && receipt.requestId === requestId);
 }
@@ -315,6 +360,7 @@ export async function reconcileImplementingSpec(args) {
             typeof validated.reviewDigest !== 'string') {
             return validated;
         }
+        const driftSource = extractDriftSource(validated);
         const expectedTransitionId = args.input.expectedImplementingTransitionId;
         const reason = args.input.reason;
         if (!expectedTransitionId || !reason) {
@@ -338,6 +384,7 @@ export async function reconcileImplementingSpec(args) {
                     stateHistory: [{ state: 'prepared', at: preparedAt }],
                     preparedAt,
                     phase: 'prepared',
+                    ...(driftSource ? { driftSource } : {}),
                 };
             })();
         if (!existing) {

package/dist/engine/readiness-checker.js

@@ -10,6 +10,7 @@ import { findScenariosWithoutTests, parseFrontmatterScenarios, } from './validat
 import { normalizeExecutableEvidence } from './validator/executable-evidence.js';
 import { evaluateImplementationContract } from './implementation-contract/index.js';
 import { extractNormalizedAcceptanceCriteria } from './spec-format/acceptance-criteria.js';
+import { detectCrossSpecPremiseContradictions } from './contradiction-detector.js';
 // ── SPEC-784: Technical section quality constants ─────────────────────────────
 const TECHNICAL_MIN_CHARS = 500;
 // Detects "See technical.md", "See spec.md", or "See `<file>` technical.md" patterns
@@ -454,7 +455,18 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     // concrete file paths, function names, or anticipated test breaks.
     const specificityBlockers = checkSpecificityGate(spec, specificityEvidenceLines, fichaContent, anticipatedTestBreaksContent);
     allBlockers.push(...specificityBlockers);
-    const effectiveScore = specificityBlockers.length > 0 && spec.difficulty >= 3 ? Math.min(totalScore, 60) : totalScore;
+    const scoreAfterSpecificityGate = specificityBlockers.length > 0 && spec.difficulty >= 3 ? Math.min(totalScore, 60) : totalScore;
+    // SPEC-1702: strict mode cross-checks premise claims about done/approved sibling
+    // specs against those siblings' own contracts and caps the score below 100.
+    const crossSpecPremiseFindings = mode === 'strict'
+        ? await detectCrossSpecPremiseContradictions(spec.id, huRaw, projectPathFromSpecPath(spec.specPath))
+        : [];
+    for (const finding of crossSpecPremiseFindings) {
+        allBlockers.push(`cross-spec-premise: ${finding.targetSpecId} claims "${finding.targetSentence}" but ${finding.siblingSpecId} states "${finding.siblingSentence}" (shared file: ${finding.sharedFilePath})`);
+    }
+    const effectiveScore = crossSpecPremiseFindings.length > 0
+        ? Math.min(scoreAfterSpecificityGate, 90)
+        : scoreAfterSpecificityGate;
     const breakdown = {
         hu: hu.points,
         criteria: criteria.points,

package/dist/engine/telemetry/error-reporter.d.ts

@@ -8,20 +8,20 @@ export declare function isErrorReportingEnabled(): boolean;
  */
 export declare function sanitizeErrorMessage(message: string): string;
 /**
- * Classifies a telemetry event as tool_blocked or tool_error.
- * Gate blocks (DoD, validate score, spec locked, invalid transition) → tool_blocked.
- * Unhandled exceptions → tool_error.
+ * Classifies a telemetry event as blocked or error, mapping onto the envelope's `result` field.
+ * Gate blocks (DoD, validate score, spec locked, invalid transition) → blocked.
+ * Unhandled exceptions → error.
  */
-export declare function classifyToolEvent(errorMessage: string, errorType?: string): 'tool_error' | 'tool_blocked';
+export declare function classifyToolEvent(errorMessage: string, errorType?: string): 'error' | 'blocked';
 /**
- * Sends a tool_error event to Supabase. Fire-and-forget — never throws.
+ * Emits an mcp_tool_failed envelope for an unhandled exception. Fire-and-forget — never throws.
+ * The envelope has no message field in Phase 1, so no error text is ever transmitted.
  * Call this from safe-handler catch blocks after returning isError:true to the user.
  */
-export declare function reportToolError(toolName: string, error: unknown): void;
+export declare function reportToolError(toolName: string, _error: unknown): void;
 /**
- * Sends a tool_error or tool_blocked event for business-logic validation failures.
- * Gate/policy blocks (DoD, spec locked, invalid transitions) emit tool_blocked.
- * Other expected errors (missing params, not-found, etc.) emit tool_error.
+ * Emits an mcp_tool_failed envelope for a business-logic validation failure, classifying
+ * `result` as blocked (gate/policy blocks) or error (other expected failures).
  * Fire-and-forget — never throws.
  */
 export declare function reportToolValidationError(toolName: string, message: string): void;

package/dist/engine/telemetry/error-reporter.js

@@ -3,8 +3,7 @@
 // Fire-and-forget. Sends sanitized error info to Supabase on unhandled tool exceptions.
 // Opt-out: set PLANU_TELEMETRY=off to disable remote reporting.
 // No PII: only tool name, sanitized error message, version, and Node version are sent.
-import { sendTelemetryEvent } from './telemetry-client.js';
-import { PLANU_VERSION } from '../../config/version.js';
+import { sendTelemetryEnvelopeEvent } from './telemetry-client.js';
 import { redactText } from '../../security/redactor.js';
 import { TELEMETRY_CONSENT_VERSION } from './telemetry-store.js';
 /**
@@ -31,58 +30,40 @@ const BLOCKED_PATTERNS = [
     'does not meet',
 ];
 /**
- * Classifies a telemetry event as tool_blocked or tool_error.
- * Gate blocks (DoD, validate score, spec locked, invalid transition) → tool_blocked.
- * Unhandled exceptions → tool_error.
+ * Classifies a telemetry event as blocked or error, mapping onto the envelope's `result` field.
+ * Gate blocks (DoD, validate score, spec locked, invalid transition) → blocked.
+ * Unhandled exceptions → error.
  */
 export function classifyToolEvent(errorMessage, errorType) {
     if (errorType === 'validation' || errorType === 'gate') {
-        return 'tool_blocked';
+        return 'blocked';
     }
     if (BLOCKED_PATTERNS.some((pattern) => errorMessage.includes(pattern))) {
-        return 'tool_blocked';
+        return 'blocked';
     }
-    return 'tool_error';
+    return 'error';
 }
 /**
- * Sends a tool_error event to Supabase. Fire-and-forget — never throws.
+ * Emits an mcp_tool_failed envelope for an unhandled exception. Fire-and-forget — never throws.
+ * The envelope has no message field in Phase 1, so no error text is ever transmitted.
  * Call this from safe-handler catch blocks after returning isError:true to the user.
  */
-export function reportToolError(toolName, error) {
+export function reportToolError(toolName, _error) {
     if (process.env.PLANU_TELEMETRY === 'off') {
         return;
     }
-    const errorClass = error instanceof Error ? error.name : typeof error;
-    sendTelemetryEvent({
-        event: 'tool_error',
-        properties: {
-            tool: toolName,
-            errorType: 'exception',
-            errorClass,
-            planVersion: PLANU_VERSION,
-            nodeVersion: process.version,
-        },
-    });
+    sendTelemetryEnvelopeEvent('mcp_tool_failed', { toolName, result: 'error' });
 }
 /**
- * Sends a tool_error or tool_blocked event for business-logic validation failures.
- * Gate/policy blocks (DoD, spec locked, invalid transitions) emit tool_blocked.
- * Other expected errors (missing params, not-found, etc.) emit tool_error.
+ * Emits an mcp_tool_failed envelope for a business-logic validation failure, classifying
+ * `result` as blocked (gate/policy blocks) or error (other expected failures).
  * Fire-and-forget — never throws.
  */
 export function reportToolValidationError(toolName, message) {
     if (process.env.PLANU_TELEMETRY === 'off') {
         return;
     }
-    const event = classifyToolEvent(message, 'validation');
-    sendTelemetryEvent({
-        event,
-        properties: {
-            tool: toolName,
-            errorType: 'validation',
-            planVersion: PLANU_VERSION,
-            nodeVersion: process.version,
-        },
-    });
+    const result = classifyToolEvent(message, 'validation');
+    sendTelemetryEnvelopeEvent('mcp_tool_failed', { toolName, result });
 }
 //# sourceMappingURL=error-reporter.js.map

package/dist/engine/telemetry/event-envelope.d.ts

@@ -0,0 +1,11 @@
+import type { TelemetryEnvelopeV1, TelemetryEnvelopeEventName, TelemetryEnvelopeInput, TelemetryEnvelopeBuildOptions, TelemetryDurationBucket } from '../../types/index.js';
+/** Ephemeral per-process session id, generated once at module load. */
+export declare const TELEMETRY_SESSION_ID: `${string}-${string}-${string}-${string}-${string}`;
+export declare function bucketDuration(durationMs: number): TelemetryDurationBucket;
+/**
+ * Builds a schemaVersion-1 telemetry envelope with exactly the allowlisted fields.
+ * Unknown fields on `fields` and unknown enum values are rejected (throw), never stored.
+ * `options.uuid`/`options.clock` make eventId/occurredAt deterministic for tests and `show`.
+ */
+export declare function buildTelemetryEnvelope(name: TelemetryEnvelopeEventName, fields: TelemetryEnvelopeInput, options?: TelemetryEnvelopeBuildOptions): TelemetryEnvelopeV1;
+//# sourceMappingURL=event-envelope.d.ts.map

package/dist/engine/telemetry/event-envelope.js

@@ -0,0 +1,124 @@
+// engine/telemetry/event-envelope.ts — SPEC-1704: versioned, allowlisted telemetry envelope v1.
+// Every field is typed and closed; unknown fields or enum values are rejected rather than
+// stored, so no free-form data (paths, args, spec content) has a code path into the envelope.
+import { randomUUID } from 'node:crypto';
+import { PLANU_VERSION } from '../../config/version.js';
+/** Ephemeral per-process session id, generated once at module load. */
+export const TELEMETRY_SESSION_ID = randomUUID();
+const EVENT_NAMES = new Set([
+    'installation_activated',
+    'mcp_server_started',
+    'mcp_tool_completed',
+    'mcp_tool_failed',
+    'spec_lifecycle_transitioned',
+    'release_check_completed',
+]);
+const RESULTS = new Set([
+    'success',
+    'error',
+    'blocked',
+    'cancelled',
+]);
+const MCP_HOSTS = new Set([
+    'claude-code',
+    'claude-desktop',
+    'cursor',
+    'codex',
+    'other',
+    'unknown',
+]);
+const OPERATING_SYSTEMS = new Set(['darwin', 'linux', 'win32']);
+const ALLOWED_INPUT_KEYS = new Set([
+    'anonymousInstallationId',
+    'sessionId',
+    'toolName',
+    'result',
+    'durationMs',
+    'mcpHost',
+]);
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+const MAX_TOOL_NAME_LENGTH = 64;
+const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const FAST_MS = 100;
+const MEDIUM_MS = 1_000;
+const SLOW_MS = 5_000;
+export function bucketDuration(durationMs) {
+    if (durationMs < FAST_MS) {
+        return 'lt_100ms';
+    }
+    if (durationMs < MEDIUM_MS) {
+        return '100ms_1s';
+    }
+    if (durationMs < SLOW_MS) {
+        return '1s_5s';
+    }
+    return 'gte_5s';
+}
+function resolveOperatingSystem() {
+    return OPERATING_SYSTEMS.has(process.platform)
+        ? process.platform
+        : 'other';
+}
+function resolveNodeMajor() {
+    return Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+}
+function rejectUnknownFields(fields) {
+    for (const key of Object.keys(fields)) {
+        if (!ALLOWED_INPUT_KEYS.has(key)) {
+            throw new Error(`Rejected telemetry event: unknown field "${key}"`);
+        }
+    }
+}
+function rejectUnknownEnumValues(fields) {
+    if (fields.result !== undefined && !RESULTS.has(fields.result)) {
+        throw new Error(`Rejected telemetry event: unknown result "${fields.result}"`);
+    }
+    if (fields.mcpHost !== undefined && !MCP_HOSTS.has(fields.mcpHost)) {
+        throw new Error(`Rejected telemetry event: unknown mcpHost "${fields.mcpHost}"`);
+    }
+    if (fields.toolName !== undefined &&
+        fields.toolName !== '' &&
+        (fields.toolName.length > MAX_TOOL_NAME_LENGTH || !TOOL_NAME_PATTERN.test(fields.toolName))) {
+        throw new Error(`Rejected telemetry event: unknown toolName "${fields.toolName}"`);
+    }
+    if (!UUID_V4_PATTERN.test(fields.anonymousInstallationId)) {
+        throw new Error('Rejected telemetry event: malformed anonymousInstallationId');
+    }
+}
+/**
+ * Builds a schemaVersion-1 telemetry envelope with exactly the allowlisted fields.
+ * Unknown fields on `fields` and unknown enum values are rejected (throw), never stored.
+ * `options.uuid`/`options.clock` make eventId/occurredAt deterministic for tests and `show`.
+ */
+export function buildTelemetryEnvelope(name, fields, options = {}) {
+    if (!EVENT_NAMES.has(name)) {
+        throw new Error(`Rejected telemetry event: unknown eventName "${name}"`);
+    }
+    rejectUnknownFields(fields);
+    rejectUnknownEnumValues(fields);
+    const uuid = options.uuid ?? randomUUID;
+    const clock = options.clock ?? (() => new Date());
+    const envelope = {
+        schemaVersion: 1,
+        eventId: uuid(),
+        eventName: name,
+        occurredAt: clock().toISOString(),
+        anonymousInstallationId: fields.anonymousInstallationId,
+        sessionId: fields.sessionId,
+        planuVersion: PLANU_VERSION,
+        operatingSystem: resolveOperatingSystem(),
+        nodeMajor: resolveNodeMajor(),
+        mcpHost: fields.mcpHost ?? 'unknown',
+    };
+    if (fields.toolName !== undefined && fields.toolName !== '') {
+        envelope.toolName = fields.toolName;
+    }
+    if (fields.result !== undefined) {
+        envelope.result = fields.result;
+    }
+    if (fields.durationMs !== undefined) {
+        envelope.durationBucket = bucketDuration(fields.durationMs);
+    }
+    return envelope;
+}
+//# sourceMappingURL=event-envelope.js.map

package/dist/engine/telemetry/telemetry-client.d.ts

@@ -1,4 +1,11 @@
-import type { TelemetryEvent } from '../../types/index.js';
+import type { TelemetryEvent, TelemetryEnvelopeEventName, TelemetryEnvelopeInput } from '../../types/index.js';
 /** Fire-and-forget; absence or staleness of opt-in prevents any network access. */
 export declare function sendTelemetryEvent(event: TelemetryEvent): void;
+/**
+ * Builds a schemaVersion-1 envelope and emits it through sendTelemetryEvent.
+ * Fire-and-forget: never awaited by callers, and every failure (disabled consent, no
+ * installation id yet, an unknown enum value) resolves to a silent no-op — telemetry
+ * never blocks or delays the operation it is describing.
+ */
+export declare function sendTelemetryEnvelopeEvent(name: TelemetryEnvelopeEventName, fields: Omit<TelemetryEnvelopeInput, 'anonymousInstallationId' | 'sessionId'>): void;
 //# sourceMappingURL=telemetry-client.d.ts.map

package/dist/engine/telemetry/telemetry-client.js

@@ -1,7 +1,8 @@
 // Remote telemetry is disabled by default and always crosses consent + redaction boundaries.
 import { networkFetch, withNetworkConsent } from '../network-policy.js';
 import { redactSensitiveValue } from '../../security/redactor.js';
-import { isTelemetryEnabled } from './telemetry-store.js';
+import { isTelemetryEnabled, getOrCreateAnonymousInstallationId } from './telemetry-store.js';
+import { buildTelemetryEnvelope, TELEMETRY_SESSION_ID } from './event-envelope.js';
 function isLoopbackHost(hostname) {
     return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
 }
@@ -24,25 +25,19 @@ function isConfiguredTelemetryToken(token) {
     return Boolean(token?.trim());
 }
 const ALLOWED_PROPERTIES = new Set([
-    'allowed',
-    'context',
-    'diagnostic',
-    'duplicateCount',
-    'durationMs',
-    'errorClass',
-    'errorType',
-    'framework',
-    'freeGBObserved',
-    'language',
-    'nodeVersion',
-    'planVersion',
-    'platform',
-    'pressureLevel',
-    'requested',
-    'specCount',
-    'stack',
-    'timestamp',
-    'tool',
+    'schemaVersion',
+    'eventId',
+    'eventName',
+    'occurredAt',
+    'anonymousInstallationId',
+    'sessionId',
+    'planuVersion',
+    'toolName',
+    'result',
+    'durationBucket',
+    'operatingSystem',
+    'nodeMajor',
+    'mcpHost',
 ]);
 function safeProperties(properties) {
     const allowlisted = Object.fromEntries(Object.entries(properties).filter(([key]) => ALLOWED_PROPERTIES.has(key)));
@@ -75,4 +70,27 @@ export function sendTelemetryEvent(event) {
     })
         .catch(() => undefined);
 }
+/**
+ * Builds a schemaVersion-1 envelope and emits it through sendTelemetryEvent.
+ * Fire-and-forget: never awaited by callers, and every failure (disabled consent, no
+ * installation id yet, an unknown enum value) resolves to a silent no-op — telemetry
+ * never blocks or delays the operation it is describing.
+ */
+export function sendTelemetryEnvelopeEvent(name, fields) {
+    void (async () => {
+        const anonymousInstallationId = await getOrCreateAnonymousInstallationId();
+        if (!anonymousInstallationId) {
+            return;
+        }
+        const envelope = buildTelemetryEnvelope(name, {
+            ...fields,
+            anonymousInstallationId,
+            sessionId: TELEMETRY_SESSION_ID,
+        });
+        sendTelemetryEvent({
+            event: envelope.eventName,
+            properties: envelope,
+        });
+    })().catch(() => undefined);
+}
 //# sourceMappingURL=telemetry-client.js.map

package/dist/engine/telemetry/telemetry-store.d.ts

@@ -4,10 +4,23 @@ export declare function readTelemetryConfig(): Promise<TelemetryConfig | null>;
 export declare function writeTelemetryConfig(config: TelemetryConfig): Promise<void>;
 /**
  * Returns true if telemetry is enabled.
- * Default: disabled. Both environment and stored opt-ins are versioned so a
- * changed privacy contract requires renewed consent.
+ * Suppression precedence (each read fresh from process.env on every call, so an
+ * env change within a process lifetime is respected immediately):
+ *   PLANU_TELEMETRY_DISABLED=1 > DO_NOT_TRACK=1 > CI=true > PLANU_TELEMETRY=off
+ *   > PLANU_TELEMETRY=on (with matching consent version) > stored consent.
+ * A corrupted or unparseable telemetry.json reads as consent-unknown (false), never crashes.
  */
 export declare function isTelemetryEnabled(): Promise<boolean>;
+/** Enables telemetry and generates a fresh anonymousInstallationId, replacing any prior one. */
+export declare function enableTelemetry(): Promise<TelemetryConfig>;
+/** Disables telemetry and deletes the stored anonymousInstallationId. */
+export declare function disableTelemetry(): Promise<TelemetryConfig>;
+/**
+ * Returns the current anonymousInstallationId when telemetry is enabled, lazily generating
+ * and persisting one if enabled but none is stored yet (e.g. enabled via PLANU_TELEMETRY=on).
+ * Returns undefined when telemetry is not enabled — never creates an id in that case.
+ */
+export declare function getOrCreateAnonymousInstallationId(): Promise<string | undefined>;
 /** Returns true if the user has never been shown the opt-in prompt. */
 export declare function hasNeverBeenPrompted(): Promise<boolean>;
 /** Mark that the user was shown the opt-in prompt (so we don't show it again). */