feat(telemetry): emit install, catalogue-view, and detail-view events (PILOT-401, 402, 406, 407) (#277)

* feat(daemon): wire app-usage telemetry for app-store supervisor (PILOT-402)

The appstoreAdapter now holds telemetryURL and identityPath, using them
to create a consent-gated telemetry.Client on Start. The client is
wrapped in an telemetryEmitter that satisfies appstore.TelemetryEmitter,
passing app_usage events from supervisor.callFrom into the signed
telemetry pipeline.

When consent is off (empty telemetry URL) the client is a permanent
no-op — no goroutines, no dials, no buffering.

Related: app-store module also updated for PILOT-402 (commit
8edfed7efa72e78499f02260ea84ae42b724f49a).

* feat(telemetry): add NewClientFromIdentity constructor + fix SignMessage overflow

Adds the NewClientFromIdentity convenience function (loads an Ed25519
identity from disk and wires it as the client signer) and fixes a minor
potential integer overflow in the SignMessage buffer pre-allocation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(telemetry): emit install events (PILOT-401)

Adds a consent-gated telemetry client package and hooks it into the
appstore install command. On every successful app install, a signed
telemetry event carrying app_id, version, and source (catalogue|local)
is POSTed to the configured telemetry endpoint.

Telemetry is gated by the PILOT_TELEMETRY_URL env var — when empty
(default), the client is a hard no-op: no dial, no goroutines, no
allocations. When set, the client signs events with the node Ed25519
identity and sends them via a signed HTTP POST.

Acceptance:
- Exactly one event per successful install (no double-count on --force)
- No event on failure (install aborted before the telemetry hook)
- Consent gate: no-op when PILOT_TELEMETRY_URL is empty

Closes PILOT-401

* fix(appstore): emit telemetry event on catalogue page view (PILOT-406)

Add best-effort, consent-gated telemetry emission at the top of
cmdAppStoreCatalogue. When PILOT_TELEMETRY_URL is unset or the
identity.json is absent, the client is a permanent no-op — no dial,
no goroutines, no buffering. Matches the existing install-event pattern
in appstore.go.

Closes PILOT-406

* feat(telemetry): emit per-app detail-view open events (PILOT-407)

Emit a consent-gated telemetry event (kind: appstore_view) when an agent
opens `pilotctl appstore view <app-id>`, after the appID resolves to a
valid app (in catalogue or installed). No event is emitted for not-found
apps (those already abort via fatalHint before the telemetry block).

The emission is best-effort and follows the same pattern as the install
event (PILOT-401): gated on PILOT_TELEMETRY_URL/identity.json; a send
failure is logged but does not block the view from rendering.

Depends on the telemetry client from PILOT-400 and the
NewClientFromIdentity helper from PILOT-401.

Closes PILOT-407

* feat(reviews): route reviews to telemetry + Pilot review prompt (PILOT-411, PILOT-408)

PILOT-411: wire pilotctl review to send a signed "review" telemetry event
(kind=review, payload: subject/rating/text). Gated on the reviews consent
flag (default on) AND a configured PILOT_TELEMETRY_URL. Best-effort: send
failure is logged but not fatal — the confirmation still prints.

PILOT-408: show a 5%-chance Pilot review prompt after send-message completes
to stderr. Gated on featureEnabled("pilot.review_prompt") and reviews consent.
Uses crypto/rand-seeded ChaCha8 so no predictable patterns.

Also bumps github.com/pilot-protocol/common to include the consent package
(PILOT-392 which was merged separately).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: matthew-pilot <matthew@vulturelabs.io>
Co-authored-by: Teodor Calin <teodor@vulturelabs.io>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: matthew-pilot <matthew@pilotprotocol.network>

Author: 5 people

cmd/daemon/appstore_adapter.go

@@ -15,25 +15,60 @@ package main
 
 import (
 	"context"
+	"encoding/json"
+	"time"
 
+	"github.com/TeoSlayer/pilotprotocol/pkg/telemetry"
 	"github.com/pilot-protocol/app-store/plugin/appstore"
 	"github.com/pilot-protocol/common/coreapi"
 )
 
 type appstoreAdapter struct {
-	svc *appstore.Service
+	svc          *appstore.Service
+	telemetryURL string
+	identityPath string
+}
+
+// telemetryEmitter wraps the consent-gated telemetry client to satisfy
+// the appstore.TelemetryEmitter interface. Events are sent as
+// "app_usage" kind with the supervisor-provided fields as payload.
+// Best-effort: send errors are logged but never block the caller.
+type telemetryEmitter struct {
+	client *telemetry.Client
+}
+
+func (e *telemetryEmitter) Emit(ev appstore.TelemetryEvent) {
+	if e == nil || e.client == nil {
+		return
+	}
+	payload, err := json.Marshal(ev)
+	if err != nil {
+		return
+	}
+	_ = e.client.Send(telemetry.Event{
+		Kind:    "app_usage",
+		TS:      time.Now().UTC().Format(time.RFC3339),
+		Payload: payload,
+	})
 }
 
 func (a *appstoreAdapter) Name() string { return a.svc.Name() }
 func (a *appstoreAdapter) Order() int   { return a.svc.Order() }
 func (a *appstoreAdapter) Start(ctx context.Context, deps coreapi.Deps) error {
+	// Build a consent-gated telemetry client for app-usage events.
+	// When the URL is empty or identity is absent the client is a
+	// permanent no-op — the emitter never sends anything.
+	client := telemetry.NewClientFromIdentity(a.telemetryURL, a.identityPath, 0)
+	emitter := &telemetryEmitter{client: client}
+
 	return a.svc.Start(ctx, appstore.Deps{
-		Streams:  deps.Streams,
-		Identity: deps.Identity,
-		Resolver: deps.Resolver,
-		Events:   deps.Events,
-		Logger:   deps.Logger,
-		Trust:    deps.Trust,
+		Streams:   deps.Streams,
+		Identity:  deps.Identity,
+		Resolver:  deps.Resolver,
+		Events:    deps.Events,
+		Logger:    deps.Logger,
+		Trust:     deps.Trust,
+		Telemetry: emitter,
 	})
 }
 func (a *appstoreAdapter) Stop(ctx context.Context) error { return a.svc.Stop(ctx) }

cmd/daemon/main.go

@@ -307,13 +307,29 @@ func main() {
 	if home, herr := os.UserHomeDir(); herr == nil {
 		appstoreInstallRoot = filepath.Join(home, ".pilot", "apps")
 	}
-	if err := rt.Register(&appstoreAdapter{svc: appstore.NewService(appstore.Config{
-		InstallRoot:    appstoreInstallRoot,
-		RescanInterval: 2 * time.Second,
-		// Real catalogue trust anchor (replaces the all-zeros
-		// placeholder default): the embedded ed25519 catalogue key.
-		CatalogPubkey: []byte(catalogtrust.PublicKey()),
-	})}); err != nil {
+	// The app-usage telemetry emitter shares the daemon's identity file
+	// and telemetry URL. When consent is off (empty URL) the client is
+	// a permanent no-op — no goroutines, no dials, no buffering.
+	idPath := *identityPath
+	if idPath == "" {
+		if home, herr := os.UserHomeDir(); herr == nil {
+			defaultID := filepath.Join(home, ".pilot", "identity.json")
+			if _, serr := os.Stat(defaultID); serr == nil {
+				idPath = defaultID
+			}
+		}
+	}
+	if err := rt.Register(&appstoreAdapter{
+		svc: appstore.NewService(appstore.Config{
+			InstallRoot:    appstoreInstallRoot,
+			RescanInterval: 2 * time.Second,
+			// Real catalogue trust anchor (replaces the all-zeros
+			// placeholder default): the embedded ed25519 catalogue key.
+			CatalogPubkey: []byte(catalogtrust.PublicKey()),
+		}),
+		telemetryURL: *telemetryURL,
+		identityPath: idPath,
+	}); err != nil {
 		log.Fatalf("register appstore: %v", err)
 	}
 

cmd/pilotctl/appstore.go

@@ -34,6 +34,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/TeoSlayer/pilotprotocol/pkg/telemetry"
 	"github.com/pilot-protocol/app-store/pkg/ipc"
 	"github.com/pilot-protocol/app-store/pkg/manifest"
 	"github.com/pilot-protocol/common/crypto"
@@ -1211,6 +1212,36 @@ func cmdAppStoreInstall(args []string) {
 		Reason: reason,
 	})
 
+	// Emit a telemetry event for the successful install (consent-gated —
+	// no-op when PILOT_TELEMETRY_URL is empty or identity.json is absent).
+	// Best-effort: a send failure is logged but not fatal — the install
+	// itself already succeeded on disk.
+	{
+		url := os.Getenv("PILOT_TELEMETRY_URL")
+		if url == "" {
+			url = telemetry.DefaultEndpoint
+		}
+		sourceStr := "catalogue"
+		if source == installSourceLocal {
+			sourceStr = "local"
+		}
+		payload, _ := json.Marshal(map[string]string{
+			"app_id":  m.ID,
+			"version": m.AppVersion,
+			"source":  sourceStr,
+		})
+		identityPath := configDir() + "/identity.json"
+		client := telemetry.NewClientFromIdentity(url, identityPath, 0)
+		err := client.Send(telemetry.Event{
+			Kind:    "app_installed",
+			TS:      time.Now().UTC().Format(time.RFC3339),
+			Payload: payload,
+		})
+		if err != nil {
+			slog.Warn("telemetry send failed, install still successful", "app", m.ID, "err", err)
+		}
+	}
+
 	report := installReport{
 		AppID:           m.ID,
 		AppVersion:      m.AppVersion,

cmd/pilotctl/appstore_catalogue.go

@@ -43,6 +43,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"log/slog"
 	"net/http"
 	"net/url"
 	"os"
@@ -51,6 +52,7 @@ import (
 	"time"
 
 	"github.com/TeoSlayer/pilotprotocol/internal/catalogtrust"
+	"github.com/TeoSlayer/pilotprotocol/pkg/telemetry"
 )
 
 // defaultCatalogueURL points at the canonical catalogue.json on main.
@@ -233,6 +235,26 @@ func cmdAppStoreSignCatalogue(args []string) {
 }
 
 func cmdAppStoreCatalogue(_ []string) {
+	// Emit a telemetry event for the catalogue page view (consent-gated —
+	// no-op when PILOT_TELEMETRY_URL is empty or identity.json is absent).
+	// Best-effort, non-blocking: a send failure is logged but doesn't
+	// prevent the catalogue from rendering.
+	{
+		url := os.Getenv("PILOT_TELEMETRY_URL")
+		if url == "" {
+			url = telemetry.DefaultEndpoint
+		}
+		identityPath := configDir() + "/identity.json"
+		client := telemetry.NewClientFromIdentity(url, identityPath, 0)
+		err := client.Send(telemetry.Event{
+			Kind: "catalogue_viewed",
+			TS:   time.Now().UTC().Format(time.RFC3339),
+		})
+		if err != nil {
+			slog.Warn("telemetry send failed, catalogue still rendered", "err", err)
+		}
+	}
+
 	c, err := loadCatalogue()
 	if err != nil {
 		fatalHint("io_error",

cmd/pilotctl/appstore_view.go

@@ -20,11 +20,15 @@ package main
 import (
 	"encoding/json"
 	"fmt"
+	"log/slog"
 	"os"
 	"path/filepath"
 	"strings"
+	"time"
 
 	"github.com/pilot-protocol/app-store/pkg/manifest"
+
+	"github.com/TeoSlayer/pilotprotocol/pkg/telemetry"
 )
 
 // installedAppFacts is the verified, local-only band of `view` — derived
@@ -175,6 +179,30 @@ func cmdAppStoreView(args []string) {
 			"app %q not found in catalogue or install root", appID)
 	}
 
+	// Emit a telemetry event for the detail view (consent-gated —
+	// no-op when PILOT_TELEMETRY_URL is empty or identity.json is absent).
+	// Best-effort: a send failure is logged but not fatal — the view
+	// itself already resolved and rendered below.
+	{
+		url := os.Getenv("PILOT_TELEMETRY_URL")
+		if url == "" {
+			url = telemetry.DefaultEndpoint
+		}
+		payload, _ := json.Marshal(map[string]string{
+			"app_id": appID,
+		})
+		identityPath := configDir() + "/identity.json"
+		client := telemetry.NewClientFromIdentity(url, identityPath, 0)
+		err := client.Send(telemetry.Event{
+			Kind:    "appstore_view",
+			TS:      time.Now().UTC().Format(time.RFC3339),
+			Payload: payload,
+		})
+		if err != nil {
+			slog.Warn("telemetry send failed, view still shown", "app", appID, "err", err)
+		}
+	}
+
 	report := buildAppViewReport(appID, entry, meta, facts)
 	if jsonOutput {
 		_ = json.NewEncoder(os.Stdout).Encode(report)

cmd/pilotctl/main.go

@@ -4,12 +4,14 @@ package main
 
 import (
 	"bufio"
+	cryptorand "crypto/rand"
 	"encoding/binary"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"log/slog"
+	"math/rand/v2"
 	"net"
 	"os"
 	"os/exec"
@@ -21,6 +23,7 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/pilot-protocol/common/consent"
 	"github.com/pilot-protocol/common/driver"
 	"github.com/pilot-protocol/common/protocol"
 	registry "github.com/pilot-protocol/common/registry/client"
@@ -4183,6 +4186,33 @@ func cmdSendMessage(args []string) {
 		})
 	}
 	tracef("outputOK")
+	maybePromptPilotReview()
+}
+
+// maybePromptPilotReview occasionally prints a Pilot review nudge to stderr
+// after a send-message completes. Gated by:
+//   - reviews consent (default on; no-op when off)
+//   - PILOT_FLAG_PILOT_REVIEW_PROMPT env / feature flag (default off)
+//   - 5% random roll
+//
+// Uses stderr so --json output on stdout is byte-identical when off.
+func maybePromptPilotReview() {
+	if !featureEnabled("pilot.review_prompt") {
+		return
+	}
+	home, _ := os.UserHomeDir()
+	if !consent.GetConsent(home, "reviews") {
+		return
+	}
+	var seed [32]byte
+	if _, err := io.ReadFull(cryptorand.Reader, seed[:]); err != nil {
+		return
+	}
+	src := rand.New(rand.NewChaCha8(seed))
+	if src.Float64() >= 0.05 {
+		return
+	}
+	fmt.Fprintln(os.Stderr, "\nLike Pilot? Run 'pilotctl review pilot --rating N' to leave a review.")
 }
 
 func cmdSubscribe(args []string) {

cmd/pilotctl/review.go

@@ -3,10 +3,17 @@
 package main
 
 import (
+	"encoding/json"
 	"fmt"
+	"log/slog"
 	"os"
 	"strconv"
 	"strings"
+	"time"
+
+	"github.com/pilot-protocol/common/consent"
+
+	"github.com/TeoSlayer/pilotprotocol/pkg/telemetry"
 )
 
 // reviewHelpText is the canonical help block for `pilotctl review`.
@@ -30,8 +37,8 @@ Examples:
   pilotctl review io.pilot.cosift --rating 4
   pilotctl review io.pilot.cosift --text "Very useful app"
 
-Note: telemetry routing is not yet enabled (PILOT-411). This command
-validates input and confirms receipt; no data is transmitted.
+Reviews are sent to the telemetry endpoint (consent-gated — no-op when
+reviews consent is off or PILOT_TELEMETRY_URL is unset).
 `
 
 // cmdReview handles `pilotctl review <pilot|app-id> [--rating N] [--text "..."]`.
@@ -41,11 +48,8 @@ validates input and confirms receipt; no data is transmitted.
 //   - --rating, when present, must be an integer in [1, 5]
 //   - --text is free-form (no constraint)
 //
-// On valid input: prints a confirmation line and exits 0.
+// On valid input: routes to telemetry (consent-gated) then confirms.
 // On invalid input: prints an error + usage hint to stderr, exits 1.
-//
-// Telemetry routing (PILOT-411) is not yet implemented; this is a
-// validation + stub only.
 func cmdReview(args []string) {
 	flags, pos := parseFlags(args)
 
@@ -94,6 +98,33 @@ func cmdReview(args []string) {
 
 	reviewText := flagString(flags, "text", "")
 
+	// Route to telemetry if reviews consent is on (default on when absent).
+	// Best-effort: a send failure is logged but not fatal.
+	home, _ := os.UserHomeDir()
+	if consent.GetConsent(home, "reviews") {
+		url := os.Getenv("PILOT_TELEMETRY_URL")
+		if url == "" {
+			url = telemetry.DefaultEndpoint
+		}
+		identityPath := configDir() + "/identity.json"
+		payload := map[string]interface{}{"subject": subject}
+		if hasRating {
+			payload["rating"] = rating
+		}
+		if reviewText != "" {
+			payload["text"] = reviewText
+		}
+		payloadBytes, _ := json.Marshal(payload)
+		client := telemetry.NewClientFromIdentity(url, identityPath, 0)
+		if err := client.Send(telemetry.Event{
+			Kind:    "review",
+			TS:      time.Now().UTC().Format(time.RFC3339),
+			Payload: payloadBytes,
+		}); err != nil {
+			slog.Warn("review telemetry send failed, review still accepted", "subject", subject, "err", err)
+		}
+	}
+
 	if jsonOutput {
 		out := map[string]interface{}{
 			"subject":   subject,

cmd/pilotctl/updates.go

@@ -213,6 +213,7 @@ func collapseWhitespace(s string) string {
 // also re-runs skill install so newly installed binaries have matching skills.
 //
 // Flags:
+//
 //	--repo <name>   : GitHub owner/repo for releases (default: TeoSlayer/pilotprotocol)
 //	--pin <tag>     : pin to a specific release tag (e.g. v1.10.5)
 //	(global) --json : emit machine-readable JSON
@@ -229,11 +230,11 @@ func cmdUpdate(args []string) {
 	installDir := filepath.Dir(updaterBin)
 
 	u := updater.New(updater.Config{
-		CheckInterval:  0, // unused for RunOnce
-		Repo:           repo,
-		InstallDir:     installDir,
-		Version:        version,
-		PinnedVersion:  pin,
+		CheckInterval: 0, // unused for RunOnce
+		Repo:          repo,
+		InstallDir:    installDir,
+		Version:       version,
+		PinnedVersion: pin,
 	})
 
 	u.RunOnce()