@planu/cli 5.6.0 → 5.7.1

package/dist/engine/housekeeping/legacy-planu-demolisher.js

@@ -0,0 +1,164 @@
+// engine/housekeeping/legacy-planu-demolisher.ts — SPEC-1709
+import { homedir } from 'node:os';
+import { lstat, readdir, realpath, rm, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, relative } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1709
+import { globalDataDir, projectDataDir } from '../../storage/base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1709
+import { getRegistry, readLogicalProjectId } from '../../storage/global-projects-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1709
+import { migrateCanonicalStorage } from '../../storage/migrations/canonical-storage.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1709
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { pathExistsStrictByStat as pathExists } from '../../core/shared/fs.js';
+const CANONICAL_ROOT_COLLISION_REASON = 'legacy root coincides with the canonical storage root; refusing to demolish';
+function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function isInsideDirectory(parent, candidate) {
+    const rel = relative(parent, candidate);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+async function realpathOrSelf(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return path;
+    }
+}
+async function isRealPathContained(parentReal, candidate) {
+    const candidateReal = await realpathOrSelf(candidate);
+    return candidateReal === parentReal || isInsideDirectory(parentReal, candidateReal);
+}
+async function canonicalRootCollidesWithLegacy(legacyRoot) {
+    const legacyReal = await realpathOrSelf(legacyRoot);
+    const canonicalCandidates = [resolveStorageLayout().data, globalDataDir()];
+    for (const candidate of canonicalCandidates) {
+        if (await isRealPathContained(legacyReal, candidate)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function directorySizeBytes(root) {
+    let total = 0;
+    const entries = await readdir(root, { withFileTypes: true });
+    for (const entry of entries) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory()) {
+            total += await directorySizeBytes(path);
+        }
+        else if (entry.isFile()) {
+            total += (await stat(path)).size;
+        }
+    }
+    return total;
+}
+async function defaultResolveDestination(project) {
+    const logicalProjectId = await readLogicalProjectId(project.path);
+    const projectId = logicalProjectId !== undefined
+        ? logicalProjectId.replaceAll('-', '').toLowerCase()
+        : project.hash;
+    return projectDataDir(projectId);
+}
+async function buildDestinationMap(registry, resolveDestination) {
+    const map = new Map();
+    for (const project of registry.projects) {
+        const destination = await resolveDestination(project);
+        const fullDigest = sha256Hex(project.path);
+        map.set(fullDigest, destination);
+        map.set(fullDigest.slice(0, 16), destination);
+    }
+    return map;
+}
+async function migrateOrRecordFailure(dirName, dirPath, destination, migrated, failures) {
+    const sizeBeforeMigration = await directorySizeBytes(dirPath);
+    try {
+        const migration = await migrateCanonicalStorage({
+            legacyRoots: [dirPath],
+            destinationRoot: destination,
+        });
+        if (migration.status === 'error' || migration.status === 'rolled-back') {
+            failures.push({ dir: dirName, reason: migration.reason ?? migration.status });
+            return 0;
+        }
+        migrated.push(dirName);
+        return sizeBeforeMigration;
+    }
+    catch (error) {
+        failures.push({ dir: dirName, reason: error instanceof Error ? error.message : String(error) });
+        return 0;
+    }
+}
+async function sweepLegacyProjectsDir(legacyProjectsDir, trustedProjectsDirReal, destinationMap) {
+    const migrated = [];
+    const failures = [];
+    let demolishedUnmappable = 0;
+    let freedBytes = 0;
+    if (!(await pathExists(legacyProjectsDir))) {
+        return { migrated, demolishedUnmappable, failures, freedBytes };
+    }
+    const entries = await readdir(legacyProjectsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const dirPath = join(legacyProjectsDir, entry.name);
+        if (entry.isSymbolicLink()) {
+            freedBytes += (await lstat(dirPath)).size;
+            await rm(dirPath, { force: true });
+            demolishedUnmappable += 1;
+            continue;
+        }
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        if (!(await isRealPathContained(trustedProjectsDirReal, dirPath))) {
+            failures.push({ dir: entry.name, reason: 'path escapes the legacy projects directory' });
+            continue;
+        }
+        const destination = destinationMap.get(entry.name);
+        if (destination !== undefined) {
+            freedBytes += await migrateOrRecordFailure(entry.name, dirPath, destination, migrated, failures);
+            continue;
+        }
+        freedBytes += await directorySizeBytes(dirPath);
+        await rm(dirPath, { recursive: true, force: true });
+        demolishedUnmappable += 1;
+    }
+    return { migrated, demolishedUnmappable, failures, freedBytes };
+}
+async function remainingProjectEntryCount(legacyProjectsDir) {
+    if (!(await pathExists(legacyProjectsDir))) {
+        return 0;
+    }
+    const entries = await readdir(legacyProjectsDir, { withFileTypes: true });
+    return entries.length;
+}
+export async function demolishLegacyPlanuRoot(options = {}) {
+    const legacyRoot = options.legacyRoot ?? join(homedir(), '.planu');
+    if (await canonicalRootCollidesWithLegacy(legacyRoot)) {
+        return {
+            status: 'retained',
+            migrated: [],
+            demolishedUnmappable: 0,
+            failures: [{ dir: '.', reason: CANONICAL_ROOT_COLLISION_REASON }],
+            freedBytes: 0,
+        };
+    }
+    if (!(await pathExists(legacyRoot))) {
+        return { status: 'absent', migrated: [], demolishedUnmappable: 0, failures: [], freedBytes: 0 };
+    }
+    const registry = options.registry ?? (await getRegistry());
+    const resolveDestination = options.resolveDestination ?? defaultResolveDestination;
+    const destinationMap = await buildDestinationMap(registry, resolveDestination);
+    const legacyProjectsDir = join(legacyRoot, 'data', 'projects');
+    const trustedProjectsDirReal = join(await realpathOrSelf(legacyRoot), 'data', 'projects');
+    const { migrated, demolishedUnmappable, failures, freedBytes: sweptBytes, } = await sweepLegacyProjectsDir(legacyProjectsDir, trustedProjectsDirReal, destinationMap);
+    if ((await remainingProjectEntryCount(legacyProjectsDir)) > 0) {
+        return { status: 'retained', migrated, demolishedUnmappable, failures, freedBytes: 0 };
+    }
+    const freedBytes = sweptBytes + (await directorySizeBytes(legacyRoot));
+    await rm(legacyRoot, { recursive: true, force: true });
+    return { status: 'demolished', migrated, demolishedUnmappable, failures, freedBytes };
+}
+//# sourceMappingURL=legacy-planu-demolisher.js.map

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