create-principles-disciple 1.121.7 → 1.121.9

package/host-runtime/dist/product-telemetry/service.js

@@ -0,0 +1,532 @@
+/**
+ * Product telemetry service — Anonymous Product Telemetry v1
+ * (PRI-597/598/599 orchestration; review remediation: workspace unit).
+ *
+ * Single seam for the CLI control plane (`pd telemetry status/enable/disable/
+ * preview/reset`) and the two fire-and-forget export triggers (OpenClaw plugin
+ * workspace init, pd-console startup). Export requires ALL gates:
+ *
+ *   canExport = feature flag anonymous_product_telemetry (workspace config)
+ *             AND consent granted (~/.pd/product-telemetry.json)
+ *             AND environment not suppressed (eligibility.ts)
+ *
+ * Scope model (review remediation P1-1): the MEASUREMENT UNIT is the
+ * workspace. Consent, consentVersion, and the telemetry secret are
+ * machine-scope; the daily identity, dedup, retry bookkeeping, and export
+ * lock are workspace-scope. One workspace's success/backoff/lock never
+ * suppresses another workspace on the same installation.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bucketDateFromTime, buildProductTelemetrySnapshot, deriveDailyTelemetryId, isValidTelemetrySecretHex, } from '@principles/core/runtime-v2';
+import { getInstallLayoutPaths, parseInstallManifest, resolveInstallLayout } from '@principles/install-layout';
+import { loadFeatureFlagFromConfig, loadPdConfigForPlugin } from '../pd-config.js';
+import { deniedControlState, defaultProductTelemetryControlState, getProductTelemetryStatePath, grantedControlState, pruneWorkspaceExports, readProductTelemetryControlState, resetControlState, writeProductTelemetryControlState, } from './consent-store.js';
+import { computeTelemetryEnvironment } from './eligibility.js';
+import { DEFAULT_PRODUCT_TELEMETRY_ENDPOINT, exportSnapshot, nextRetryDelayMs } from './exporter.js';
+import { readMilestoneFacts } from './milestone-readers.js';
+import { workspaceExportLockPath, workspaceScopeIdFor } from './workspace-scope.js';
+export const ANONYMOUS_PRODUCT_TELEMETRY_FLAG = 'anonymous_product_telemetry';
+export const PD_TELEMETRY_DISABLED_ENV = 'PD_TELEMETRY_DISABLED';
+export const PREVIEW_BANNER = 'Preview only. Nothing was sent.';
+/** Hard cap on export attempts per UTC day per workspace (1 initial + 4 retries; review round 2). */
+export const MAX_DAILY_EXPORT_ATTEMPTS = 5;
+/** A lock older than this is treated as orphaned (holder crashed) and taken over. */
+const EXPORT_LOCK_STALE_MS = 5 * 60 * 1000;
+/**
+ * The state-update critical section (fresh read → prune → merge → atomic
+ * write) holds for a few ms, so the poll budget and stale threshold are
+ * tiny compared to the export lock's — a crashed holder blocks bookkeeping
+ * for seconds, not minutes, and live holders can never be evicted (the
+ * hold is far shorter than the stale threshold).
+ */
+const STATE_UPDATE_LOCK_STALE_MS = 5 * 1000;
+const STATE_UPDATE_LOCK_TIMEOUT_MS = 3 * 1000;
+const STATE_UPDATE_LOCK_POLL_MS = 15;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Per-workspace cross-process export lock: exclusive create ('wx') is atomic,
+ * so exactly one of N simultaneous holders wins — and the lock name embeds
+ * only the opaque scope key, so workspace A's in-flight export never blocks
+ * workspace B's (review remediation P1-1). Stale takeover uses mtime — a
+ * crashed holder can block that workspace for at most EXPORT_LOCK_STALE_MS.
+ * Never throws: any filesystem failure degrades to "not acquired"
+ * (telemetry skips, PD unaffected).
+ */
+function tryAcquireExportLock(stateFilePath, workspaceScopeId) {
+    const lockPath = workspaceExportLockPath(stateFilePath, workspaceScopeId);
+    const create = () => {
+        try {
+            const fd = fs.openSync(lockPath, 'wx');
+            try {
+                fs.writeSync(fd, `${process.pid} ${new Date().toISOString()}`);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (create())
+        return { acquired: true, lockPath };
+    try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > EXPORT_LOCK_STALE_MS) {
+            fs.rmSync(lockPath, { force: true });
+            if (create())
+                return { acquired: true, lockPath };
+        }
+    }
+    catch {
+        // stat/rm failure → treat as busy; never throw for telemetry
+    }
+    return { acquired: false };
+}
+function releaseExportLock(lockPath) {
+    try {
+        fs.rmSync(lockPath, { force: true });
+    }
+    catch {
+        // best effort; a leaked lock is reclaimed after EXPORT_LOCK_STALE_MS
+    }
+}
+/**
+ * Machine-scope state-update lock: serializes ONLY the control-state file
+ * read→merge→write across workspaces (a few ms each) — the network export
+ * itself stays fully concurrent. Review round 4: without it, two
+ * concurrently-completing exports built their writes from the same stale
+ * base and the later write silently dropped the earlier workspace's entry
+ * (lost update), defeating once/day dedup, backoff, and the attempt cap.
+ *
+ * Lock acquisition polls asynchronously (never blocks the event loop) and
+ * takes over a stale (crashed-holder) lock after STATE_UPDATE_LOCK_STALE_MS.
+ */
+async function acquireStateUpdateLock(stateFilePath) {
+    const lockPath = `${stateFilePath}.state-lock`;
+    const deadline = Date.now() + STATE_UPDATE_LOCK_TIMEOUT_MS;
+    const create = () => {
+        try {
+            const fd = fs.openSync(lockPath, 'wx');
+            try {
+                fs.writeSync(fd, `${process.pid} ${new Date().toISOString()}`);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    for (;;) {
+        if (create())
+            return { acquired: true, lockPath };
+        try {
+            const stat = fs.statSync(lockPath);
+            if (Date.now() - stat.mtimeMs > STATE_UPDATE_LOCK_STALE_MS) {
+                fs.rmSync(lockPath, { force: true });
+                if (create())
+                    return { acquired: true, lockPath };
+            }
+        }
+        catch {
+            // disappeared between poll attempts → next loop's create decides
+        }
+        if (Date.now() >= deadline)
+            return { acquired: false };
+        await sleep(STATE_UPDATE_LOCK_POLL_MS);
+    }
+}
+/**
+ * Merge ONE workspace's export entry into the control state inside the
+ * state-update critical section. The entry itself is built by the caller
+ * (its inputs are stable for this workspace under the per-workspace export
+ * lock); the OTHER workspaces' entries come from a FRESH read under the
+ * lock, so concurrent completions compose instead of overwrite. Identity
+ * transitions that raced the export (reset/disable/secret rotation mid-
+ * flight) are detected and win — an in-flight result is never merged into
+ * a rotated/denied identity. Best-effort by contract: every non-written
+ * outcome is observable at the call site via structured logs (rc-9).
+ */
+async function mergeWorkspaceExportEntry(args) {
+    const stateFilePath = getProductTelemetryStatePath(args.homeDir);
+    const lock = await acquireStateUpdateLock(stateFilePath);
+    if (!lock.acquired)
+        return 'skipped_contention';
+    try {
+        const read = readProductTelemetryControlState(args.homeDir);
+        if (!read.ok)
+            return 'skipped_unreadable';
+        if (read.state.consent !== 'granted' || read.state.telemetrySecret !== args.secret)
+            return 'skipped_identity_changed';
+        const pruned = pruneWorkspaceExports(read.state, args.timestamp);
+        const nextState = {
+            ...pruned,
+            workspaceExports: { ...(pruned.workspaceExports ?? {}), [args.scopeKey]: args.nextEntry },
+        };
+        return writeProductTelemetryControlState(args.homeDir, nextState).ok ? 'written' : 'skipped_unreadable';
+    }
+    finally {
+        releaseExportLock(lock.lockPath);
+    }
+}
+const DEFAULT_MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveInstallContext(homeDir) {
+    const paths = getInstallLayoutPaths(homeDir);
+    const manifestParsed = parseInstallManifest(readJsonFile(paths.manifest));
+    const manifest = manifestParsed.manifest;
+    const canonicalRuntimeExists = fs.existsSync(paths.hostRuntimeDir);
+    const legacyExtensionExists = fs.existsSync(paths.openClawExtensionDir);
+    const layout = resolveInstallLayout({ homeDir, manifest, canonicalRuntimeExists, legacyExtensionExists });
+    let hostKind = 'other';
+    if (manifest && manifest.hosts.length === 1 && (manifest.hosts[0] === 'codex' || manifest.hosts[0] === 'openclaw')) {
+        [hostKind] = manifest.hosts;
+    }
+    else if (legacyExtensionExists) {
+        hostKind = 'openclaw';
+    }
+    const pluginVersion = readJsonFile(path.join(paths.pluginDir, 'package.json')) ?? readJsonFile(path.join(paths.openClawExtensionDir, 'package.json'));
+    const versionValue = pluginVersion !== null && typeof pluginVersion === 'object' && !Array.isArray(pluginVersion)
+        ? pluginVersion.version
+        : undefined;
+    const pdVersion = typeof versionValue === 'string' ? versionValue.slice(0, 32) : 'unknown';
+    return { installMode: layout.mode, hostKind, pdVersion };
+}
+function workspaceEnvironmentOf(workspaceDir) {
+    if (!workspaceDir)
+        return 'unknown';
+    const loaded = loadPdConfigForPlugin(workspaceDir);
+    const environment = loaded.effective.config.workspace?.environment;
+    return environment ?? 'unknown';
+}
+export function createProductTelemetryService(deps = {}) {
+    const homeDir = () => path.resolve(deps.homeDir ?? os.homedir());
+    const env = () => deps.env ?? process.env;
+    const moduleDir = () => path.resolve(deps.moduleDir ?? DEFAULT_MODULE_DIR);
+    const now = () => (deps.now ?? Date.now)();
+    const logger = deps.logger ?? {};
+    function environmentResult(workspaceDir) {
+        return computeTelemetryEnvironment({
+            env: {
+                killSwitch: env()[PD_TELEMETRY_DISABLED_ENV],
+                ci: env().CI,
+                vitest: env().VITEST,
+                e2eMode: env().PD_E2E_MODE,
+            },
+            workspaceEnvironment: workspaceEnvironmentOf(workspaceDir),
+            installMode: resolveInstallContext(homeDir()).installMode,
+            moduleDir: moduleDir(),
+        });
+    }
+    function gatesFor(state, workspaceDir) {
+        let flagEnabled = null;
+        let flagSource = null;
+        if (workspaceDir) {
+            const flag = loadFeatureFlagFromConfig(workspaceDir, ANONYMOUS_PRODUCT_TELEMETRY_FLAG);
+            flagEnabled = flag.enabled;
+            flagSource = flag.source;
+        }
+        const environment = environmentResult(workspaceDir);
+        const blockers = [];
+        if (flagEnabled === null)
+            blockers.push('feature_flag_unresolved');
+        else if (flagEnabled !== true)
+            blockers.push('feature_flag_disabled');
+        if (state.consent !== 'granted')
+            blockers.push(`consent_${state.consent}`);
+        blockers.push(...environment.reasons);
+        return {
+            flagEnabled,
+            flagSource,
+            consent: state.consent,
+            environmentSuppressed: environment.suppressed,
+            suppressionReasons: environment.reasons,
+            canExport: blockers.length === 0,
+            blockers,
+        };
+    }
+    function nextActionFor(gates) {
+        if (gates.canExport)
+            return undefined;
+        if (gates.suppressionReasons.includes('env_kill_switch'))
+            return `Unset ${PD_TELEMETRY_DISABLED_ENV} to allow telemetry export.`;
+        if (gates.flagEnabled === false)
+            return `Set features.${ANONYMOUS_PRODUCT_TELEMETRY_FLAG}.enabled: true in the workspace .pd/config.yaml.`;
+        if (gates.consent !== 'granted')
+            return 'Run: pd telemetry enable --confirm';
+        if (gates.environmentSuppressed)
+            return `Telemetry is suppressed in this environment (${gates.suppressionReasons.join(', ')}). This is expected for CI/test/dev environments.`;
+        return 'Resolve the blockers listed above.';
+    }
+    return {
+        /** Status for `pd telemetry status`. Never exposes the secret. */
+        getStatus(workspaceDir) {
+            const read = readProductTelemetryControlState(homeDir());
+            if (!read.ok)
+                return read;
+            const gates = gatesFor(read.state, workspaceDir);
+            // Export bookkeeping is workspace-scoped: show this workspace's entry
+            // (when a workspace was given and its scope can be derived).
+            let workspaceEntry;
+            const storedSecret = read.state.telemetrySecret;
+            if (workspaceDir !== undefined && isValidTelemetrySecretHex(storedSecret)) {
+                const scopeKey = workspaceScopeIdFor(storedSecret, workspaceDir);
+                workspaceEntry = read.state.workspaceExports?.[scopeKey];
+            }
+            const view = {
+                ...gates,
+                consentVersion: read.state.consentVersion,
+                hasSecret: isValidTelemetrySecretHex(read.state.telemetrySecret),
+                ...(workspaceEntry?.lastAttemptedAt !== undefined ? { lastAttemptedAt: workspaceEntry.lastAttemptedAt } : {}),
+                ...(workspaceEntry?.lastSucceededAt !== undefined ? { lastSucceededAt: workspaceEntry.lastSucceededAt } : {}),
+                ...(workspaceEntry?.lastFailureCode !== undefined ? { lastFailureCode: workspaceEntry.lastFailureCode } : {}),
+                ...(workspaceEntry?.nextRetryAt !== undefined ? { nextRetryAt: workspaceEntry.nextRetryAt } : {}),
+                endpoint: deps.endpoint ?? DEFAULT_PRODUCT_TELEMETRY_ENDPOINT,
+                ...(nextActionFor(gates) !== undefined ? { nextAction: nextActionFor(gates) } : {}),
+            };
+            return { ok: true, view };
+        },
+        /** Exact outbound payload for `pd telemetry preview`. Never sends. */
+        preview(workspaceDir) {
+            const read = readProductTelemetryControlState(homeDir());
+            const state = read.ok ? read.state : defaultProductTelemetryControlState();
+            const gates = gatesFor(state, workspaceDir);
+            const timestamp = now();
+            const bucketDate = bucketDateFromTime(timestamp);
+            const secretEphemeral = !isValidTelemetrySecretHex(state.telemetrySecret);
+            // Without a stored secret there is no stable daily ID; an all-zero
+            // hex placeholder keeps the preview shape exact while the note says
+            // the ID would differ after enable.
+            const secret = state.telemetrySecret ?? '0'.repeat(64);
+            const scopeKey = workspaceScopeIdFor(secret, workspaceDir);
+            const install = resolveInstallContext(homeDir());
+            const { facts, notes } = readMilestoneFacts(workspaceDir);
+            const snapshot = buildProductTelemetrySnapshot({
+                dailyTelemetryId: deriveDailyTelemetryId(secret, scopeKey, bucketDate),
+                bucketDate,
+                pdVersion: install.pdVersion,
+                hostKind: install.hostKind,
+                milestones: {
+                    initialized: facts.initialized,
+                    painObserved: facts.painObserved,
+                    principleObserved: facts.principleObserved,
+                    activationObserved: facts.activationObserved,
+                    presenceReceiptObserved: facts.presenceReceiptObserved,
+                    effectReceiptObserved: facts.effectReceiptObserved,
+                },
+                reliability: { initializationFailed: facts.initializationFailed },
+            });
+            const previewNotes = [...notes];
+            if (secretEphemeral)
+                previewNotes.push('payload shape is exact; dailyTelemetryId is provisional and will change after pd telemetry enable');
+            if (!read.ok)
+                previewNotes.push(`control state unreadable (${read.reason}) — showing defaults`);
+            return { banner: PREVIEW_BANNER, snapshot, gates, notes: previewNotes, secretEphemeral };
+        },
+        /** `pd telemetry enable --confirm`: explicit granted consent (+ secret). */
+        enable() {
+            const read = readProductTelemetryControlState(homeDir());
+            if (!read.ok)
+                return read;
+            const next = grantedControlState(read.state);
+            const written = writeProductTelemetryControlState(homeDir(), next);
+            if (!written.ok)
+                return written;
+            logger.info?.(`[PD:Telemetry] Consent granted (control state: ${getProductTelemetryStatePath(homeDir())}).`);
+            return { ok: true, consent: 'granted' };
+        },
+        /** `pd telemetry disable --confirm`: deny consent and delete export identity. */
+        disable() {
+            const read = readProductTelemetryControlState(homeDir());
+            if (!read.ok)
+                return read;
+            const written = writeProductTelemetryControlState(homeDir(), deniedControlState());
+            if (!written.ok)
+                return written;
+            logger.info?.('[PD:Telemetry] Consent denied; local telemetry secret and export status deleted. Future export requests: 0.');
+            return { ok: true, consent: 'denied' };
+        },
+        /** `pd telemetry reset --confirm`: delete identity; fresh secret only if still enabled. */
+        reset() {
+            const read = readProductTelemetryControlState(homeDir());
+            if (!read.ok)
+                return read;
+            const next = resetControlState(read.state);
+            const written = writeProductTelemetryControlState(homeDir(), next);
+            if (!written.ok)
+                return written;
+            logger.info?.('[PD:Telemetry] Telemetry identity reset; previous daily IDs are unlinkable going forward.');
+            return { ok: true, consent: next.consent };
+        },
+        /**
+         * One gate-checked export attempt for a normal-activity trigger.
+         * Never throws; every path returns a structured outcome.
+         *
+         * Concurrency: a per-workspace lock file
+         * (`product-telemetry.json.export-lock.<scopeId>`) closes the read→send→
+         * write race between simultaneous triggers (OpenClaw gateway init +
+         * pd-console startup in different processes) WITHOUT coupling unrelated
+         * workspaces. Stale locks (crashed holder) are taken over after
+         * EXPORT_LOCK_STALE_MS.
+         */
+        async maybeExportDaily(workspaceDir) {
+            const read = readProductTelemetryControlState(homeDir());
+            if (!read.ok) {
+                logger.warn?.(`[PD:Telemetry] Export skipped: ${read.reason}`);
+                return { attempted: false, skipReason: 'control_state_unreadable' };
+            }
+            const { state } = read;
+            const gates = gatesFor(state, workspaceDir);
+            if (!gates.flagEnabled)
+                return { attempted: false, skipReason: 'feature_flag_disabled' };
+            if (state.consent !== 'granted')
+                return { attempted: false, skipReason: `consent_${state.consent}` };
+            if (gates.environmentSuppressed) {
+                logger.info?.(`[PD:Telemetry] Export suppressed (${gates.suppressionReasons.join(', ')}).`);
+                return { attempted: false, skipReason: `environment_suppressed:${gates.suppressionReasons.join('+')}` };
+            }
+            if (!isValidTelemetrySecretHex(state.telemetrySecret)) {
+                logger.warn?.('[PD:Telemetry] Export skipped: telemetry secret missing/invalid. Run: pd telemetry enable --confirm');
+                return { attempted: false, skipReason: 'secret_missing' };
+            }
+            const secret = state.telemetrySecret;
+            const timestamp = now();
+            const bucketDate = bucketDateFromTime(timestamp);
+            const scopeKey = workspaceScopeIdFor(secret, workspaceDir);
+            const workspaceEntry = state.workspaceExports?.[scopeKey];
+            if (workspaceEntry?.lastSucceededAt !== undefined && bucketDateFromTime(Date.parse(workspaceEntry.lastSucceededAt)) === bucketDate) {
+                return { attempted: false, skipReason: 'already_succeeded_today' };
+            }
+            if (workspaceEntry?.nextRetryAt !== undefined && timestamp < Date.parse(workspaceEntry.nextRetryAt)) {
+                return { attempted: false, skipReason: 'retry_backoff' };
+            }
+            // Hard daily attempt cap (review round 2): the 1h/6h backoff alone
+            // permits up to 5 attempts on a bad day (0h/1h/7h/13h/19h); the counter
+            // makes the bound explicit and independent of clock skew. Per-workspace.
+            const priorAttempts = workspaceEntry?.attemptBucketDate === bucketDate ? (workspaceEntry?.dailyAttemptCount ?? 0) : 0;
+            if (priorAttempts >= MAX_DAILY_EXPORT_ATTEMPTS) {
+                return { attempted: false, skipReason: 'daily_attempt_cap' };
+            }
+            const lock = tryAcquireExportLock(getProductTelemetryStatePath(homeDir()), scopeKey);
+            if (!lock.acquired || lock.lockPath === undefined) {
+                // Another process is mid-export for THIS workspace; it will record
+                // shared-day success and our next trigger will see
+                // already_succeeded_today.
+                logger.info?.('[PD:Telemetry] Export skipped: another export is in flight for this workspace (lock busy).');
+                return { attempted: false, skipReason: 'export_lock_busy' };
+            }
+            try {
+                // Re-read inside the lock: the lock holder before us may have just
+                // succeeded for today (fresh state beats the stale pre-lock copy).
+                const fresh = readProductTelemetryControlState(homeDir());
+                const freshSecret = fresh.ok ? fresh.state.telemetrySecret : undefined;
+                const effectiveState = fresh.ok && freshSecret === secret
+                    ? fresh.state
+                    : state;
+                if (isValidTelemetrySecretHex(effectiveState.telemetrySecret)) {
+                    const freshEntry = effectiveState.workspaceExports?.[scopeKey];
+                    if (freshEntry?.lastSucceededAt !== undefined && bucketDateFromTime(Date.parse(freshEntry.lastSucceededAt)) === bucketDate) {
+                        return { attempted: false, skipReason: 'already_succeeded_today' };
+                    }
+                }
+                const install = resolveInstallContext(homeDir());
+                const { facts } = readMilestoneFacts(workspaceDir);
+                const snapshot = buildProductTelemetrySnapshot({
+                    dailyTelemetryId: deriveDailyTelemetryId(secret, scopeKey, bucketDate),
+                    bucketDate,
+                    pdVersion: install.pdVersion,
+                    hostKind: install.hostKind,
+                    milestones: {
+                        initialized: facts.initialized,
+                        painObserved: facts.painObserved,
+                        principleObserved: facts.principleObserved,
+                        activationObserved: facts.activationObserved,
+                        presenceReceiptObserved: facts.presenceReceiptObserved,
+                        effectReceiptObserved: facts.effectReceiptObserved,
+                    },
+                    reliability: { initializationFailed: facts.initializationFailed },
+                });
+                const result = await exportSnapshot({
+                    snapshot,
+                    ...(deps.endpoint !== undefined ? { endpoint: deps.endpoint } : {}),
+                    ...(deps.fetchFn !== undefined ? { fetchFn: deps.fetchFn } : {}),
+                });
+                const priorEntry = effectiveState.workspaceExports?.[scopeKey];
+                const failedRecently = priorEntry?.lastAttemptedAt !== undefined && timestamp - Date.parse(priorEntry.lastAttemptedAt) < 24 * 60 * 60 * 1000;
+                const nextEntry = result.ok
+                    ? {
+                        lastAttemptedAt: new Date(timestamp).toISOString(),
+                        lastSucceededAt: new Date(timestamp).toISOString(),
+                    }
+                    : {
+                        lastAttemptedAt: new Date(timestamp).toISOString(),
+                        lastFailureCode: result.code,
+                        nextRetryAt: new Date(timestamp + nextRetryDelayMs(failedRecently)).toISOString(),
+                        dailyAttemptCount: priorAttempts + 1,
+                        attemptBucketDate: bucketDate,
+                    };
+                // Review round 4: merge under the machine-scope state-update lock —
+                // the OTHER workspaces' entries come from a fresh read inside the
+                // critical section, so concurrently-completing exports compose
+                // instead of dropping each other's bookkeeping (lost update). The
+                // network export above stayed concurrent; only this ms-scale file
+                // RMW is serialized. Every non-written outcome is logged (rc-9).
+                const merged = await mergeWorkspaceExportEntry({
+                    homeDir: homeDir(),
+                    secret,
+                    scopeKey,
+                    timestamp,
+                    nextEntry,
+                });
+                if (merged === 'skipped_contention') {
+                    logger.warn?.(`[PD:Telemetry] Export ${result.ok ? 'succeeded' : `failed (${result.code})`} but control state update was skipped after ${STATE_UPDATE_LOCK_TIMEOUT_MS / 1000}s of state-lock contention — this workspace may re-attempt today.`);
+                }
+                else if (merged === 'skipped_unreadable') {
+                    logger.warn?.(`[PD:Telemetry] Export ${result.ok ? 'succeeded' : `failed (${result.code})`} but control state could not be read/updated — ${getProductTelemetryStatePath(homeDir())}`);
+                }
+                else if (merged === 'skipped_identity_changed') {
+                    logger.info?.('[PD:Telemetry] Export finished after a consent/secret change; stale export bookkeeping was NOT written back.');
+                }
+                if (result.ok) {
+                    logger.info?.('[PD:Telemetry] Daily anonymous product telemetry snapshot exported.');
+                    return { attempted: true, ok: true, httpStatus: result.status };
+                }
+                logger.warn?.(`[PD:Telemetry] Export failed (${result.code}); next retry after ${nextEntry.nextRetryAt}. PD behavior is unaffected.`);
+                return { attempted: true, ok: false, failureCode: result.code };
+            }
+            finally {
+                releaseExportLock(lock.lockPath);
+            }
+        },
+    };
+}
+/**
+ * Fire-and-forget scheduling for normal-activity triggers. The timer is
+ * unref'd so it never keeps a host process alive, and every failure path is
+ * contained — telemetry can never block or crash PD startup or hooks.
+ */
+export function scheduleProductTelemetryExport(service, workspaceDir, scheduleLogger) {
+    const timer = setTimeout(() => {
+        void service
+            .maybeExportDaily(workspaceDir)
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            scheduleLogger?.warn?.(`[PD:Telemetry] Unexpected export error (PD unaffected): ${message}`);
+        });
+    }, 0);
+    timer.unref?.();
+}

package/host-runtime/dist/product-telemetry/workspace-scope.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Workspace scope resolution — Anonymous Product Telemetry v1
+ * (review remediation: measurement unit = workspace).
+ *
+ * Telemetry bookkeeping (dedup, retry, export lock) is keyed per workspace
+ * while consent and the telemetry secret stay machine-scope. The key is a
+ * keyed fingerprint of the canonical workspace path:
+ *
+ *   workspaceScopeId = HMAC(telemetrySecret, "workspace:" + canonicalPath)
+ *
+ * — opaque, locally stable, and carrying no path information without the
+ * secret (a plain path hash would be enumerable; this is not). It exists
+ * only in `~/.pd/product-telemetry.json` and lock filenames. The server
+ * never sees it.
+ *
+ * A workspace that is moved or renamed resolves to a new scope and is
+ * deliberately treated as a new telemetry workspace — no cross-path
+ * identity is created.
+ */
+/**
+ * Canonicalize a workspace directory for scope derivation.
+ *
+ * Invariants (tested): `D:\Code\PD`, `d:\code\pd\`, and any casing variant
+ * on Windows resolve to ONE canonical form, so equivalent spellings never
+ * produce two telemetry units. On POSIX (case-sensitive filesystems) case
+ * is preserved. realpath collapses symlinks and Windows 8.3 short names;
+ * when realpath is unavailable (permissions, vanished dir) the resolved
+ * path is used as-is — a degraded key, never a thrown error.
+ */
+export declare function canonicalizeWorkspacePath(workspaceDir: string): string;
+/** Compute the local workspace scope key (hex16) for one secret + workspace. */
+export declare function workspaceScopeIdFor(telemetrySecretHex: string, workspaceDir: string): string;
+/**
+ * Per-workspace export lock path. The filename embeds ONLY the opaque hex
+ * scope key — never the workspace path — so one workspace's in-flight
+ * export never blocks another's (review remediation P1-1).
+ */
+export declare function workspaceExportLockPath(stateFilePath: string, workspaceScopeId: string): string;

package/host-runtime/dist/product-telemetry/workspace-scope.js

@@ -0,0 +1,64 @@
+/**
+ * Workspace scope resolution — Anonymous Product Telemetry v1
+ * (review remediation: measurement unit = workspace).
+ *
+ * Telemetry bookkeeping (dedup, retry, export lock) is keyed per workspace
+ * while consent and the telemetry secret stay machine-scope. The key is a
+ * keyed fingerprint of the canonical workspace path:
+ *
+ *   workspaceScopeId = HMAC(telemetrySecret, "workspace:" + canonicalPath)
+ *
+ * — opaque, locally stable, and carrying no path information without the
+ * secret (a plain path hash would be enumerable; this is not). It exists
+ * only in `~/.pd/product-telemetry.json` and lock filenames. The server
+ * never sees it.
+ *
+ * A workspace that is moved or renamed resolves to a new scope and is
+ * deliberately treated as a new telemetry workspace — no cross-path
+ * identity is created.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { deriveWorkspaceScopeId } from '@principles/core/runtime-v2';
+/**
+ * Canonicalize a workspace directory for scope derivation.
+ *
+ * Invariants (tested): `D:\Code\PD`, `d:\code\pd\`, and any casing variant
+ * on Windows resolve to ONE canonical form, so equivalent spellings never
+ * produce two telemetry units. On POSIX (case-sensitive filesystems) case
+ * is preserved. realpath collapses symlinks and Windows 8.3 short names;
+ * when realpath is unavailable (permissions, vanished dir) the resolved
+ * path is used as-is — a degraded key, never a thrown error.
+ */
+export function canonicalizeWorkspacePath(workspaceDir) {
+    let resolved = path.resolve(workspaceDir);
+    try {
+        resolved = fs.realpathSync(resolved);
+    }
+    catch {
+        // Non-throwing by contract (telemetry must never break PD); the resolved
+        // path is still a usable local key.
+    }
+    let canonical = resolved.split(path.sep).join('/');
+    if (process.platform === 'win32') {
+        // Windows filesystems are case-insensitive: normalize away casing drift
+        // (drive letter included) so D:\Code\PD == d:\code\pd.
+        canonical = canonical.toLowerCase();
+    }
+    if (canonical.length > 1 && canonical.endsWith('/')) {
+        canonical = canonical.slice(0, -1);
+    }
+    return canonical;
+}
+/** Compute the local workspace scope key (hex16) for one secret + workspace. */
+export function workspaceScopeIdFor(telemetrySecretHex, workspaceDir) {
+    return deriveWorkspaceScopeId(telemetrySecretHex, canonicalizeWorkspacePath(workspaceDir));
+}
+/**
+ * Per-workspace export lock path. The filename embeds ONLY the opaque hex
+ * scope key — never the workspace path — so one workspace's in-flight
+ * export never blocks another's (review remediation P1-1).
+ */
+export function workspaceExportLockPath(stateFilePath, workspaceScopeId) {
+    return `${stateFilePath}.export-lock.${workspaceScopeId}`;
+}

package/host-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/host-runtime",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared host-neutral orchestration for Principles Disciple MVP-Core hook paths.",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,16 +22,21 @@
   },
   "dependencies": {
     "@principles/core": "file:../core",
+    "@principles/install-layout": "file:../install-layout",
     "better-sqlite3": "^13.0.3",
     "js-yaml": "^5.2.0"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
+    "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^26.1.2",
     "@types/js-yaml": "^4.0.9",
     "typescript": "^7.0.2",
     "vite": "^8.0.16",
     "vitest": "^4.1.10"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/csuzngjh/principles.git"
+  },
   "license": "MIT"
 }