@senad-d/observme 0.1.0

package/docs/configuration.md

@@ -0,0 +1,38 @@
+# ObservMe configuration
+
+ObservMe creates a project-local starter config automatically during trusted Pi session-start lifecycles.
+
+## Automatic project config
+
+When Pi emits `session_start` in a trusted project, ObservMe creates `observme.yaml` under Pi's exported project config directory:
+
+```text
+<CONFIG_DIR_NAME>/observme.yaml
+```
+
+The standard Pi distribution currently resolves this to `.pi/observme.yaml`. ObservMe resolves the absolute target under the trusted project root and serializes the complete existence-check/create/write window through Pi's file-mutation queue. Pi emits `session_start` for startup, `/reload`, new-session, resume, and fork flows. ObservMe intentionally runs the same idempotent bootstrap for each trusted flow so session replacement and reloads converge on the same project-local config state. The file is created only when it is missing; concurrent starts create it at most once, existing project config is never overwritten, and no repeat notification is shown. Bootstrap is skipped when the project is untrusted or Pi does not provide a project `ctx.cwd`. The generated file is privacy-preserving: raw prompt, response, thinking, tool, bash, and file-path capture starts disabled, redaction starts enabled, and unsafe capture starts disabled.
+
+## What to edit
+
+Edit the project config file (`.pi/observme.yaml` in the standard distribution) where you run Pi:
+
+- `otlp.endpoint` and `otlp.signalEndpoints` — your OpenTelemetry Collector URLs.
+- `resource.attributes` — service name, project name, tenant, and deployment environment labels.
+- `capture` — whether prompts, responses, thinking, tool data, bash data, and file paths are exported. For local debugging, set only the specific fields you need to `true`.
+- `privacy` — redaction, unsafe-capture acknowledgement, insecure transport, hash salt env var, and path handling. Keep `redactionEnabled: true`; set `allowUnsafeCapture: true` only when you intentionally accept unredacted sensitive-content export from this trusted project. Live telemetry and `/obs backfill` use the same policy: disabled capture omits content, enabled redaction redacts then truncates, redaction failures drop content, and `redactionEnabled: false` with `allowUnsafeCapture: true` exports raw truncated content.
+- `query.grafana` — Grafana URL, datasource UIDs, TLS, and IPv4 transport settings for `/obs` query commands.
+- `query.links.traceUrlTemplate` — the Grafana Explore trace-link template used by `/obs trace` and `/obs link`.
+
+Keep credentials out of YAML. Reference environment variables such as `OBSERVME_OTLP_TOKEN`, `OBSERVME_GRAFANA_TOKEN`, `OBSERVME_GRAFANA_PASSWORD`, and `OBSERVME_HASH_SALT`, then set those values in the shell or a trusted project `.env` file. When any content capture flag is enabled with `privacy.redactionEnabled: true`, `OBSERVME_HASH_SALT` must be set before the event occurs; otherwise content capture fails closed and emits `redaction.failed` diagnostics instead of conversation rows.
+
+## Precedence
+
+Configuration is merged in this order:
+
+```text
+defaults → global ~/.pi/agent/observme.yaml → trusted project .pi/observme.yaml → trusted project .env → system environment variables → runtime options
+```
+
+Use `~/.pi/agent/observme.yaml` for standard-distribution global defaults that should apply across projects. Use `<CONFIG_DIR_NAME>/observme.yaml` for per-project setup. Because `.env` and system environment variables have higher precedence than YAML, remove or update stale `OBSERVME_REDACTION_ENABLED`, `OBSERVME_ALLOW_UNSAFE_CAPTURE`, and `OBSERVME_CAPTURE_*` overrides when YAML privacy settings appear to be ignored.
+
+Invalid or unsafe merged configuration falls back to safe defaults. `/obs status`, structured `config.rejected` telemetry, and Pi UI notifications when available report only bounded source and issue codes/counts; rejected values, paths, headers, regular expressions, and credentials are never rendered. Project `.env` remains a configuration layer only and cannot establish parent-agent lineage.

package/docs/review-validation.md

@@ -0,0 +1,115 @@
+# Review validation
+
+Use this checklist when closing the 2026-07-09 Pi extension review tasks. It records validation for the current checkout only; generated review specs are planning artifacts and do not by themselves mark the extension ready to ship or complete any review task.
+
+## Current review passes
+
+Execute the active review pass backlogs in order. The current checkout contains no active `-2` review variants; treat any restored `-2` files as historical snapshots unless a later review explicitly designates them as the active backlog.
+
+1. First pass — active security, runtime, and high-risk correctness backlog; completed.
+2. Second pass — active maintainability, validation, packaging, and test-gap backlog; completed.
+3. Final pass — active lifecycle, async-failure, output-bound, runtime-compatibility, and closure-evidence backlog; continue from the first unchecked task until the file is complete.
+
+## Final review validation commands
+
+Run and record the current output from these commands instead of copying stale counts from earlier review snapshots:
+
+```bash
+npm run typecheck
+npm run typecheck:test
+npm run lint:eslint
+npm run format:check
+npm audit --audit-level=moderate
+npm audit --omit=dev --audit-level=moderate
+npm run test
+npm run check:pack
+npm run check
+npm run smoke:pi-runtime
+```
+
+Notes:
+
+- `npm run typecheck` validates source TypeScript from `tsconfig.json`.
+- `npm run typecheck:test` validates `test/**/*.ts` through `tsconfig.test.json` so TypeScript fixtures cannot drift from source APIs.
+- `npm run lint:eslint` and `npm run format:check` validate repository linting and formatting without changing files.
+- `npm audit --audit-level=moderate` verifies the full dependency tree for moderate-or-higher vulnerabilities.
+- `npm audit --omit=dev --audit-level=moderate` verifies production dependency exposure for the review; do not treat it as a publish approval.
+- `npm run test` prints the authoritative current test count for the checkout being reviewed.
+- `npm run check:pack` validates package contents without publishing.
+- `npm run check` validates script syntax for the package-content, coverage, smoke, and Grafana validation helpers without executing generated-output or networked flows.
+- `npm run smoke:pi-lifecycle` runs handler lifecycle code with an explicit offline config: traces, metrics, logs, and query integration are disabled, and endpoint fields are loopback-only.
+- `npm run smoke:pi-runtime` runs a credential-free Pi RPC lifecycle smoke that covers extension reload through a smoke command that calls `ctx.reload()` (the same flow as `/reload`), RPC `new_session` replacement, post-replacement `/obs status` and `/obs session` routing, and sanitized current Pi event shapes for model/thinking changes, agent turns, built-in tool lifecycle events, and `message_end` with local deterministic backends only.
+- `user_bash` is the remaining manual event-shape path: current Pi emits it from interactive `!`/`!!` handling, while RPC `bash`/`prompt` commands do not emit it. The automated smoke verifies the installed Pi `UserBashEvent` type contract (`command`, `excludeFromContext`, `cwd`, and no completed-result fields). Manual recipe when a TUI is available: launch Pi with a temporary recorder extension that logs only `typeof command`, `typeof cwd`, `excludeFromContext`, and completed-result field presence; run `!!printf observme-user-bash-shape`; confirm the shape remains pre-execution and contains no raw command/output in recorded evidence.
+- `npm run test:coverage` is the remaining generated-output validation command. It writes `coverage/node-test-coverage.txt` and SonarQube-readable `coverage/lcov.info` for the default non-Docker test suite; `coverage/` is git-ignored, and `rm -rf coverage` is the cleanup command after review if the artifacts are not needed. Docker integration coverage is opt-in with `OBSERVME_INCLUDE_INTEGRATION_COVERAGE=1`.
+- `npm run validate` remains the broader release-oriented validation entry point, but the review checklist records explicit commands so failures can be attributed to source, test, lint, package, smoke, or audit stages.
+
+## Deferred integration and Pi lifecycle verification checklist
+
+Use this checklist when a review, release candidate, or local operator needs coverage beyond the default static suite. Record only pass/fail summaries, sanitized ids, and cleanup notes; never paste credentials, prompts, raw command text from interactive Pi, or backend secret values.
+
+| Command | Normal CI safe? | Prerequisites | External access and credentials | Side effects, artifacts, and cleanup | Verification scope |
+| --- | --- | --- | --- | --- | --- |
+| `npm run smoke:discover` | Yes | Dependencies installed; source files present. | None. Imports the declared local Pi extension entry only. | No tracked writes. | Package-level Pi extension declaration and default export discoverability. |
+| `npm run smoke:handlers` | Yes | Dependencies installed. | None. Uses the local Pi API harness. | No tracked writes. | Registers the extension and executes one command plus the first agent-facing tool when present. |
+| `npm run smoke:pi-lifecycle` | Yes | Dependencies installed. | None. Uses explicit loopback-only, telemetry-disabled config. | No tracked writes. | Registers `session_start`/`session_shutdown` and confirms lifecycle status cleanup without Collector, Grafana, or credentials. |
+| `npm run smoke:pi-runtime` | Yes when the `pi` CLI is installed in the test image | A working local `pi` executable, dependencies installed, and permission to spawn a local child process. | No credentials. It deletes inherited `OBSERVME_*` values and uses a deterministic loopback backend. | Creates a temporary project and extension files under the OS temp directory, then removes them; local loopback server only. | Real Pi RPC extension load, `/obs` discovery/routing, reload/new-session replacement, and credential-free event-shape smoke coverage. |
+| `npm run smoke:packaged` | Usually release/local only | `npm` available and package dependencies resolvable for a temporary install. | May need npm registry/cache access to install package dependencies; no project credentials. | Runs `npm pack`, creates a temporary project under the OS temp directory, installs the tarball with `--ignore-scripts --no-audit --no-fund --package-lock=false`, and removes the temp directory. | Packaged install layout and declared Pi extension files in the installed package. |
+| `npm run test:integration:collector` | No | Docker daemon available; Collector image `OBSERVME_COLLECTOR_IMAGE` or `otel/opentelemetry-collector-contrib:0.104.0` pullable or cached. | Docker image pull may require network; no Grafana/model credentials. | Starts a temporary Collector container with loopback-published ports and stops it in test cleanup. | OTLP export to Collector debug pipeline for representative traces, metrics, and logs. |
+| `npm run test:integration:grafana-stack` | No | Docker Compose available; `observability-stack/docker-compose.yml` and test overlay available; required Grafana/Tempo/Loki/Prometheus images pullable or cached. | Docker image pull may require network; no external Grafana credentials. Test-created local Grafana admin secret is synthetic. | Creates isolated Docker Compose project/networks/containers. May create `observability-stack/secrets/grafana_admin_password` when missing and removes the test-created file during cleanup; also creates temporary command-project files under the OS temp directory. If interrupted, run `docker compose` with the printed project name or remove stale `observme-grafana-it-*` resources. | Live local stack ingestion, datasource queries, `/obs` query commands, and dashboard provisioning imports. |
+| `npm run validate:grafana-obs` | No | Running Pi session with ObservMe loaded, reachable Collector/Grafana stack, and recent telemetry. See `docs/validation-flow.md`. | Requires Grafana read credentials from environment variables (`OBSERVME_GRAFANA_TOKEN` or username/password), datasource UIDs, and `OBSERVME_VALIDATION_SESSION_ID`; may access the configured Grafana URL. | Read-only against the configured stack; no file writes expected. Keep terminal output sanitized and omit secrets. | Operator-facing validation that Grafana has ObservMe data and representative `/obs` commands work against the same stack. |
+
+## Final-pass live/package smoke record — 2026-07-09
+
+This record was produced for the final-pass task "Run and record bounded live Pi/package smoke validation before release." The checkout was dirty with active review-remediation changes, so release candidates should rerun the passing non-service commands from a clean worktree before tagging. No credentials were printed or required for the commands below.
+
+| Command | Result | Evidence and notes |
+| --- | --- | --- |
+| `npm run smoke:discover` | Pass | Discovered 1 declared Pi extension entry file. |
+| `npm run smoke:handlers` | Pass | Registered the extension and executed root `/obs`; no agent-facing tools are registered. |
+| `npm run smoke:pi-lifecycle` | Pass | Executed `session_start` and `session_shutdown` with offline telemetry disabled. |
+| `npm run smoke:pi-runtime` | Pass | Real Pi RPC process discovered `/obs`, covered reload and new-session lifecycle replacement, and executed status/session/health/bounded query commands with deterministic local backends. |
+| `npm run smoke:packaged` | Pass | Packed and installed `@senad-d/observme@0.1.0` into a temporary project, then verified the installed Pi extension entries. |
+| `npm run check:pack` | Pass | Package dry-run contained 100 expected files and excluded local state/secrets. |
+| `npm run test:integration:collector` | Pass | Docker-backed local Collector debug pipeline received representative traces, metrics, and logs without default content capture. |
+| `npm run test:integration:grafana-stack` | Fail/blocker | Docker and Docker Compose were available, stack cleanup left no `observme-grafana-it-*` containers or networks, but the test timed out waiting for `Tempo LLM content attributes`: Tempo returned the trace payload without satisfying `hasTempoLlmContentPayload()` for `pi.llm.prompt.redacted`, `pi.llm.response.redacted`, `pi.llm.thinking.redacted`, and marker assertions. Next action: inspect the live-stack Tempo attribute ingestion/query shape around `waitForTempoLlmContent()` in `test/integration/grafana-stack.test.mjs` before release. |
+| `npm run validate:grafana-obs` | Blocked/not run | Requires an operator-controlled running Pi session with ObservMe loaded, reachable Grafana/Collector stack, Grafana read credentials via environment variables, and `OBSERVME_VALIDATION_SESSION_ID`; do not run until those prerequisites are available and evidence can stay sanitized. |
+
+Post-run cleanup check: `docker ps --filter name=observme-grafana-it --format '{{.Names}}'` and `docker network ls --filter name=observme-grafana-it --format '{{.Name}}'` returned no resources.
+
+## Review-closure evidence categories
+
+- **Read-only/check-only** — commands that inspect, type-check, lint, audit, run tests, dry-run packaging, or smoke local deterministic fixtures without publishing or writing tracked files.
+- **Generated-output** — commands that write ignored artifacts, such as `npm run test:coverage` writing `coverage/node-test-coverage.txt` and `coverage/lcov.info`; record the paths and clean them with `rm -rf coverage` if the artifacts are not needed.
+- **Docker/integration** — commands that require Docker or the local observability stack, such as `npm run test:integration:collector`, `npm run test:integration:grafana-stack`, and `npm run validate:grafana-obs`.
+- **Credential/manual** — checks that require a TUI, model provider credentials, Grafana credentials, or other operator-controlled state; keep recorded evidence sanitized and never paste secrets, prompts, commands, or raw outputs.
+
+## Post-remediation verification matrix
+
+Use this matrix before checking a review task complete. The focused command must directly exercise the task-specific behavior; high-priority tasks must not be closed with broad `npm run test` evidence alone.
+
+| Pass | Task | Priority | Evidence category | Required focused evidence |
+| --- | --- | --- | --- | --- |
+| First | Apply tenant-salted hashing consistently to telemetry, redaction, and subagent command fingerprints | High | Read-only/check-only | `node --test test/privacy-hash-truncate.test.mjs test/redact.test.mjs test/handler-internals.test.ts test/subagent-spawn.test.mjs test/obs-backfill-command.test.mjs`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| First | Enforce production-safe transport for all OTLP signal endpoints and Grafana query credentials | High | Read-only/check-only | `node --test test/config-validation.test.mjs test/grafana-query-client.test.mjs test/obs-health-command.test.mjs`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| First | Correct `user_bash` handling so pre-execution Pi events are not recorded as completed bash executions | High | Read-only/check-only plus credential/manual for interactive bash shape | `node --test test/pi-handlers.test.mjs test/event-mapping.test.ts`; `npm run smoke:pi-runtime`; if reviewing the interactive `user_bash` path, follow the sanitized TUI recipe above and record only shape metadata. |
+| First | Clear stale ObservMe and W3C context values before propagating subagent environments | Medium | Read-only/check-only | `node --test test/agent-lineage.test.ts test/subagent-spawn.test.mjs test/event-mapping.test.ts`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| First | Sanitize health, bootstrap, and transport diagnostics before showing them in Pi UI | Medium | Read-only/check-only | `node --test test/obs-health-command.test.mjs test/grafana-query-client.test.mjs test/project-config-bootstrap.test.mjs test/otel-sdk.test.mjs test/obs-status-command.test.mjs test/obs-command-diagnostics.test.mjs test/sensitive-query-input.test.mjs`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| Second | Centralize live and backfill content-capture policy | Medium | Read-only/check-only | `node --test test/content-capture-policy.test.mjs test/handler-internals.test.ts test/obs-backfill-command.test.mjs test/config-validation.test.mjs`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| Second | Consolidate sensitive query and diagnostic input validation patterns | Low | Read-only/check-only | `node --test test/sensitive-query-input.test.mjs test/prometheus-query-client.test.mjs test/loki-query-client.test.mjs test/tempo-query-client.test.mjs test/grafana-query-client.test.mjs test/obs-trace-link-command.test.mjs test/obs-command-diagnostics.test.mjs`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| Second | Repair validation script and README command drift | Medium | Read-only/check-only | `node --test test/package-contents-check.test.mjs`; `npm run check`; `npm run typecheck`; `npm run lint:eslint`; `npm run test`. |
+| Second | Make smoke and coverage validation deterministic, offline, and review-safe | Medium | Read-only/check-only plus generated-output for coverage | `node --test test/validation-scripts.test.mjs`; `npm run check`; `npm run smoke:handlers`; `npm run smoke:pi-lifecycle`; `npm run smoke:pi-runtime`; run `npm run test:coverage` only when generated coverage output is acceptable and record cleanup. |
+| Second | Align npm package contents with README-promised assets and examples | Medium | Read-only/check-only | `node --test test/package-contents-check.test.mjs`; `npm run check:pack`; `npm run smoke:packaged`; `npm run test`. |
+| Second | Add targeted edge-case tests for synthetic event fallback paths | Low | Read-only/check-only | `node --test test/pi-handlers.test.mjs test/event-mapping.test.ts`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| Final | Serialize session lifecycle start, shutdown, reload, and replacement state transitions | High | Read-only/check-only | `node --test test/pi-handlers.test.mjs test/obs-session-command.test.mjs test/obs-status-command.test.mjs test/obs-agents-command.test.mjs`; `npm run smoke:pi-runtime`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| Final | Make `/obs backfill` timeout and cancellation stop underlying exporter work | Medium | Read-only/check-only | `node --test test/obs-backfill-command.test.mjs`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| Final | Bound `/obs agents` rendered child output for large agent trees | Medium | Read-only/check-only | `node --test test/obs-agents-command.test.mjs`; then `npm run typecheck`, `npm run typecheck:test`, `npm run lint:eslint`, `npm run test`. |
+| Final | Add real Pi runtime event-shape compatibility smoke coverage | Medium | Read-only/check-only plus credential/manual for interactive bash shape | `npm run smoke:pi-runtime`; `node --test test/pi-handlers.test.mjs test/event-mapping.test.ts`; if Pi still cannot emit interactive `user_bash` through RPC, record the documented sanitized TUI recipe as the blocker/manual evidence. |
+| Final | Create a post-remediation verification matrix for review-task closure | Low | Read-only/check-only | `npm run format:check`; focused documentation consistency check: every row in this matrix names a validation command or blocker, and the categories above classify read-only, generated-output, Docker/integration, and credential/manual evidence. |
+
+## Supplemental release-oriented checks
+
+The matrix above is the minimum closure evidence for the review tasks. Run these broader checks before release or when touching the corresponding surface:
+
+- **Docker/integration:** `npm run test:integration:collector`, `npm run test:integration:grafana-stack`, and `npm run validate:grafana-obs` when Docker and the local observability stack are available.
+- **Generated-output:** `npm run test:coverage` when coverage evidence is needed; record `coverage/node-test-coverage.txt` and `coverage/lcov.info`, then remove `coverage/` afterward unless the artifacts are intentionally retained.
+- **Credential/manual:** model-provider, Grafana credential, and interactive Pi TUI checks must use sanitized shape/status evidence only.

package/docs/validation-flow.md

@@ -0,0 +1,117 @@
+# ObservMe Grafana + `/obs` validation flow
+
+Use this secret-safe flow when Grafana shows ObservMe data but `/obs` commands appear broken. It classifies the failure as ingestion, labels, Grafana auth/query access, local TLS/DNS, Pi command registration, or session state.
+
+## Preconditions
+
+- The local stack is already running, for example `docker compose -f observability-stack/docker-compose.yml up -d`.
+- The Pi session is active with ObservMe loaded from this checkout or the package under test.
+- Grafana read access is provided through environment variables. Do not put tokens or passwords on the command line and do not source `.env` in captured logs.
+
+```bash
+export OBSERVME_GRAFANA_URL=https://observability.local
+export OBSERVME_GRAFANA_TOKEN=<service-account-token>
+# Or, for local-only Basic auth:
+# export OBSERVME_GRAFANA_USERNAME=admin
+# export OBSERVME_GRAFANA_PASSWORD=<local-password>
+
+export OBSERVME_GRAFANA_TEMPO_DATASOURCE_UID=tempo
+export OBSERVME_GRAFANA_LOKI_DATASOURCE_UID=loki
+export OBSERVME_GRAFANA_PROMETHEUS_DATASOURCE_UID=prometheus
+export OBSERVME_GRAFANA_TLS_INSECURE_SKIP_VERIFY=true
+export OBSERVME_GRAFANA_PREFER_IPV4=true
+export OBSERVME_OTLP_ENDPOINT=http://127.0.0.1:4318
+```
+
+## 1. Verify the active Pi command state
+
+Inside the active Pi session, run:
+
+```text
+/obs status
+/obs health
+/obs session
+/obs logs
+/obs trace
+```
+
+Expected output:
+
+- `/obs status` shows `ObservMe: enabled`, the intended Grafana URL, and `Grafana query readiness: ready`.
+- `/obs health` shows `Collector: reachable`, `Grafana: reachable`, and Tempo/Loki/Metrics datasource checks as `ok`.
+- `/obs session` shows a concrete session id instead of `unknown`.
+- `/obs logs` shows session logs or a clear label/export failure hint.
+- `/obs trace` returns a Grafana trace link. During an active session, child spans can appear before the root `pi.session` span; the root is exported after `session_shutdown`.
+
+Copy the generated ids into your shell for the automated backend checks:
+
+```bash
+export OBSERVME_VALIDATION_SESSION_ID=<session-id-from-/obs-session>
+# Optional but useful when /obs trace already returned a trace id:
+export OBSERVME_VALIDATION_TRACE_ID=<32-hex-trace-id>
+```
+
+## 2. Run the local lifecycle flow test
+
+Before using a live backend, the unit-level lifecycle flow can be reproduced without credentials:
+
+```bash
+node --test --test-name-pattern "deterministic active-session command flow" test/pi-handlers.test.mjs
+```
+
+This starts a fake ObservMe session, emits representative LLM, tool, bash, and subagent telemetry, checks active `/obs session` and `/obs trace` output, then runs `session_shutdown` and verifies root-span export state, bounded flush/shutdown calls, exporter-status messaging, and secret-safe output.
+
+## 3. Run the deterministic validation script
+
+```bash
+npm run validate:grafana-obs
+```
+
+The script is read-only. It never reads `.env` or secret files, never prints token/password values, and does not mutate the running stack. It checks:
+
+- Grafana API and datasource health with configured auth.
+- One Prometheus ObservMe metric through the Grafana datasource proxy.
+- One Loki query using normalized `service_name` and `pi_session_id` labels.
+- One Tempo search by safe generated `pi.session.id`.
+- Representative `/obs` command handlers: status, health, session, logs, and trace.
+
+A passing run ends with:
+
+```text
+Result: PASS — Grafana has data and representative /obs commands work with the configured stack.
+```
+
+## 4. Verify the Export Health dashboard
+
+Use this after representative telemetry has been emitted by the active local Pi session.
+
+1. Open Grafana and select the `ObservMe Export Health` dashboard.
+2. Confirm the healthy quiet state:
+   - `Observed event liveness` or `Session lifecycle` shows recent activity for the selected range.
+   - Telemetry drops, redaction failures, export failures, and handler error pressure render `0` when no failure series exists.
+   - Active spans is zero or low after the session settles.
+   - Failure log tables may be empty; empty means no matching failure logs in the selected range.
+3. In a throwaway trusted local project, induce one safe failure mode at a time, then refresh the dashboard:
+   - queue/span pressure should increment `observme_telemetry_dropped_total` and show `telemetry.dropped` rows;
+   - redaction exceptions should increment `observme_redaction_failures_total` and show `redaction.failed` rows;
+   - Collector/export failures should increment `observme_export_errors_total` and show `export.failed` rows.
+4. Re-run `/obs status` and `/obs health` after each scenario. They should remain available, secret-safe, and pointed at the same local OTLP/Grafana configuration.
+
+For deterministic, secret-safe signal-contract coverage without mutating the live stack, run:
+
+```bash
+node --test test/dashboards.test.mjs test/exporter-failure.test.ts test/chaos-failure.test.mjs test/pi-handlers.test.mjs
+```
+
+## Failure signatures
+
+| Failed step | Likely class | Next check |
+| --- | --- | --- |
+| Grafana auth configuration | Missing query credentials | Export `OBSERVME_GRAFANA_TOKEN` or `OBSERVME_GRAFANA_USERNAME`/`OBSERVME_GRAFANA_PASSWORD`. |
+| Grafana and datasource health | Grafana auth/query, local TLS/DNS, or datasource UID | Run `/obs health`; verify `observability.local`, TLS skip-verify for local dev, and datasource UIDs. |
+| Prometheus metric ingestion | Collector metrics export or Prometheus scrape | Check Collector health, Prometheus targets, and `observme_*` metric names. |
+| Loki log labels | Label mismatch or log export | Compare live Loki labels with `service_name`, `pi_session_id`, `event_name`, and `/obs logs` selectors. |
+| Tempo trace search | Trace export, datasource UID, or active root-span timing | Wait for export, run `/obs trace`, and remember the root `pi.session` appears after shutdown. |
+| `/obs command path` | Pi command state, session state, or command query mismatch | Re-run the Pi commands in step 1; then run `npm run smoke:pi-runtime` to isolate real Pi command registration. |
+
+Release validation should not be considered complete while any step fails.

package/examples/collector.yaml

@@ -0,0 +1,123 @@
+extensions:
+  health_check:
+    endpoint: 0.0.0.0:13133
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 1024
+    spike_limit_mib: 256
+
+  batch:
+    timeout: 2s
+    send_batch_size: 1024
+    send_batch_max_size: 2048
+
+  resource/observme:
+    attributes:
+      - key: telemetry.source
+        value: observme
+        action: upsert
+      - key: service.name
+        value: observme-pi-extension
+        action: insert
+      - key: service.namespace
+        value: pi
+        action: upsert
+
+  resource/drop_high_cardinality_metric_attrs:
+    attributes:
+      - key: pi.workflow.id
+        action: delete
+      - key: pi.workflow.root_agent_id
+        action: delete
+      - key: pi.agent.id
+        action: delete
+      - key: pi.agent.parent_id
+        action: delete
+      - key: pi.agent.root_id
+        action: delete
+      - key: pi.agent.run.id
+        action: delete
+      - key: pi.agent.spawn.id
+        action: delete
+      - key: pi.agent.spawn.tool_call_id
+        action: delete
+      - key: pi.agent.child.id
+        action: delete
+      - key: pi.session.id
+        action: delete
+
+  # Drops accidental content attributes from logs. Intentional LLM content capture
+  # is emitted as already-redacted log bodies and opt-in span attributes.
+  attributes/drop_content_attributes:
+    actions:
+      - key: gen_ai.input.messages
+        action: delete
+      - key: gen_ai.output.messages
+        action: delete
+      - key: pi.llm.prompt.redacted
+        action: delete
+      - key: pi.llm.response.redacted
+        action: delete
+      - key: pi.llm.thinking.redacted
+        action: delete
+      - key: pi.tool.arguments.redacted
+        action: delete
+      - key: pi.tool.result.redacted
+        action: delete
+
+exporters:
+  otlp/tempo:
+    endpoint: tempo:4317
+    tls:
+      insecure: true
+    sending_queue:
+      enabled: true
+    retry_on_failure:
+      enabled: true
+
+  otlphttp/loki:
+    endpoint: http://loki:3100/otlp
+    sending_queue:
+      enabled: true
+    retry_on_failure:
+      enabled: true
+
+  prometheusremotewrite/mimir:
+    endpoint: http://mimir:9009/api/v1/push
+    resource_to_telemetry_conversion:
+      enabled: true
+    sending_queue:
+      enabled: true
+    retry_on_failure:
+      enabled: true
+
+  debug:
+    verbosity: basic
+
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, resource/observme, batch]
+      exporters: [otlp/tempo]
+
+    metrics:
+      receivers: [otlp]
+      processors: [memory_limiter, resource/observme, resource/drop_high_cardinality_metric_attrs, batch]
+      exporters: [prometheusremotewrite/mimir]
+
+    logs:
+      receivers: [otlp]
+      processors: [memory_limiter, resource/observme, attributes/drop_content_attributes, batch]
+      exporters: [otlphttp/loki]

package/examples/observme.yaml

@@ -0,0 +1,131 @@
+observme:
+  enabled: true
+  environment: development
+  tenant: local-dev
+  replayOnStart: false
+
+  otlp:
+    endpoint: http://localhost:4318
+    protocol: http/protobuf
+    timeoutMs: 3000
+    headers: {}
+    tls:
+      enabled: false
+      insecureSkipVerify: false
+    signalEndpoints:
+      traces: http://localhost:4318/v1/traces
+      metrics: http://localhost:4318/v1/metrics
+      logs: http://localhost:4318/v1/logs
+
+  resource:
+    attributes:
+      service.name: observme-pi-extension
+      observme.tenant.id: local-dev
+      pi.project.name: local-project
+      deployment.environment.name: development
+
+  workflow:
+    idEnv: OBSERVME_WORKFLOW_ID
+    enabled: true
+    maxDepthWarning: 5
+    maxFanoutWarning: 20
+
+  agent:
+    idEnv: OBSERVME_AGENT_ID
+    parentIdEnv: OBSERVME_PARENT_AGENT_ID
+    rootIdEnv: OBSERVME_ROOT_AGENT_ID
+    parentSessionIdEnv: OBSERVME_PARENT_SESSION_ID
+    parentTraceIdEnv: OBSERVME_PARENT_TRACE_ID
+    parentSpanIdEnv: OBSERVME_PARENT_SPAN_ID
+    depthEnv: OBSERVME_AGENT_DEPTH
+    spawnIdEnv: OBSERVME_SPAWN_ID
+    propagateTraceContext: true
+    propagateToSubagents: true
+    capabilityEnv: OBSERVME_AGENT_CAPABILITY
+    writeCorrelationEntry: false
+
+  traces:
+    enabled: true
+    sampleRatio: 1.0
+    batch:
+      maxQueueSize: 2048
+      maxExportBatchSize: 512
+      scheduledDelayMillis: 1000
+      exportTimeoutMillis: 3000
+
+  metrics:
+    enabled: true
+    exportIntervalMillis: 15000
+    exportTimeoutMillis: 3000
+
+  logs:
+    enabled: true
+    batch:
+      maxQueueSize: 2048
+      maxExportBatchSize: 512
+      scheduledDelayMillis: 1000
+
+  capture:
+    prompts: false
+    responses: false
+    thinking: false
+    toolArguments: false
+    toolResults: false
+    bashCommands: false
+    bashOutput: false
+    filePaths: false
+
+  privacy:
+    redactionEnabled: true
+    allowUnsafeCapture: false
+    allowInsecureTransport: true
+    tenantSaltEnv: OBSERVME_HASH_SALT
+    pathMode: hash
+    customRedactionPatterns: []
+
+  limits:
+    maxPromptChars: 12000
+    maxResponseChars: 12000
+    maxToolArgumentChars: 8000
+    maxToolResultChars: 16000
+    maxBashOutputChars: 16000
+    maxLogBodyChars: 32000
+    maxActiveAgentRuns: 16
+    maxActiveTurns: 128
+    maxActiveToolCalls: 1024
+    maxActiveLlmRequests: 128
+    maxActiveSubagentSpawns: 128
+    maxActiveAgentWaits: 128
+    maxActiveAgentJoins: 128
+
+  query:
+    enabled: true
+    timeoutMs: 5000
+    maxLogs: 50
+    maxTraces: 20
+    maxMetricSeries: 20
+    maxAgents: 20
+    links:
+      # Uses the supported bundled-stack Grafana Explore fallback.
+      traceUrlTemplate: https://observability.local/explore?left=...
+    grafana:
+      # Supported local command path: Grafana behind nginx HTTPS.
+      url: https://observability.local
+      # Preferred: set a Grafana service-account token in this env var.
+      token: ${OBSERVME_GRAFANA_TOKEN}
+      # Local fallback: set OBSERVME_GRAFANA_PASSWORD from observability-stack/secrets/grafana_admin_password.
+      username: "admin"
+      password: ${OBSERVME_GRAFANA_PASSWORD}
+      datasourceUids:
+        tempo: tempo
+        loki: loki
+        prometheus: prometheus
+      tls:
+        # Local self-signed certificate only; keep false for production CAs.
+        insecureSkipVerify: true
+      transport:
+        # Avoid observability.local resolving to an unreachable IPv6 loopback first.
+        preferIPv4: true
+
+  shutdown:
+    flushTimeoutMs: 3000

package/img/icon.svg

@@ -0,0 +1,47 @@
+<svg width="256" height="256" viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Nazar amulet icon">
+  <defs>
+    <radialGradient id="outerBlue" cx="50%" cy="38%" r="65%">
+      <stop offset="0%" stop-color="#35B7FF"/>
+      <stop offset="55%" stop-color="#1592E6"/>
+      <stop offset="100%" stop-color="#0067B1"/>
+    </radialGradient>
+
+    <radialGradient id="innerBlue" cx="50%" cy="42%" r="62%">
+      <stop offset="0%" stop-color="#2AA7FF"/>
+      <stop offset="70%" stop-color="#0074D9"/>
+      <stop offset="100%" stop-color="#0059B3"/>
+    </radialGradient>
+
+    <filter id="softShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="7" flood-color="#003B6D" flood-opacity="0.35"/>
+    </filter>
+  </defs>
+
+  <!-- Outer amulet -->
+  <circle cx="128" cy="128" r="112" fill="url(#outerBlue)" filter="url(#softShadow)"/>
+
+  <!-- Dark rim -->
+  <circle cx="128" cy="128" r="101" fill="none" stroke="#004F9E" stroke-width="13"/>
+
+  <!-- White ring -->
+  <circle cx="128" cy="128" r="73" fill="#F7FBFF"/>
+
+  <!-- Blue iris ring -->
+  <circle cx="128" cy="128" r="49" fill="url(#innerBlue)"/>
+
+  <!-- Dark pupil -->
+  <circle cx="128" cy="128" r="25" fill="#061A3D"/>
+
+  <!-- Small glossy reflection -->
+  <ellipse cx="95" cy="72" rx="27" ry="15" fill="#FFFFFF" opacity="0.35" transform="rotate(-25 95 72)"/>
+
+  <!-- Inner highlight -->
+  <circle cx="116" cy="116" r="8" fill="#FFFFFF" opacity="0.28"/>
+
+  <!-- Subtle bottom shading -->
+  <path
+    d="M39 151C52 205 89 232 128 232C177 232 216 198 226 151C205 182 168 201 128 201C88 201 51 182 39 151Z"
+    fill="#004D91"
+    opacity="0.18"
+  />
+</svg>