@senad-d/observme 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -21,6 +21,11 @@
 
 ### Changed
 
+- Raised the release-tested Pi and exact compatibility CI target to 0.81.1 while retaining 0.80.5 as the earliest validated target.
+- Made the 0.1.5 hardening patch self-contained with explicit review units, all imported production modules included, and unrelated specification history preserved.
+- Established a typed Pi event registration contract, removed non-event legacy registrations, pinned the release-tested Pi API for validation, and added capability-based pre-registration diagnostics.
+- Centralized embedded-credential Grafana URL diagnostics so configuration validation, readiness checks, URL construction, and transports share one safe failure class and operator guidance.
+- Documented credential-free Grafana base URLs and the fail-closed canonical project-file boundary across configuration, security, query, and troubleshooting guidance.
 - Completed production active-agent lease documentation, raw-query migration guidance, GitHub Actions/self-hosted clock and cleanup runbooks, missing/expired-lease troubleshooting, Collector restart semantics, and sanitized release-validation evidence.
 - Reframed the Collector's five-minute Prometheus `metric_expiration` as exporter-wide stale-series/cardinality cleanup, longer than the default active-agent lease and independent of leased liveness.
 - Migrated active-agent dashboard totals, bounded breakdowns, aggregate topology inputs, and stuck-high alerts to leased activity, with raw/expired-claim diagnostics and a deployment-tunable stale-claim alert.
@@ -38,6 +43,36 @@
 
 ### Fixed
 
+- Removed Pi version gating from extension startup entirely; tested versions are evidence only, essential ExtensionAPI capabilities are checked before registration, and optional APIs remain feature-detected.
+- Made missing project-path component reversal explicit.
+- Applied one control-safe 64-row/8,192-character policy to every `/obs` notification and capped query result counts at configuration and runtime boundaries.
+- Coupled canonical project config, `.env`, and starter-config I/O to identity-verified file handles so concurrent symlink and ancestor swaps fail closed without exposing external paths.
+- Rejected credentials embedded in Grafana base URLs during config validation, query readiness, and transport preflight without exposing their values.
+- Rejected active and retained child-agent identifier collisions before creating integration spans, tree state, metrics, or propagation envelopes.
+- Retained ownership of timed-out OpenTelemetry shutdowns, observed late settlement safely, and deferred session replacement until prior exporter cleanup completes.
+- Replaced custom-redaction regex heuristics with bounded structural validation that rejects nested, ambiguous-alternative, and overlapping sequential repetition while preserving safe disjoint quantified alternatives.
+- Used concise word-character syntax for single-brace unresolved trace-link placeholders.
+- Used concise word-character syntax for dollar-brace unresolved trace-link placeholders.
+- Used concise word-character syntax for double-brace unresolved trace-link placeholders.
+- Split unresolved trace-link placeholder validation into simple per-syntax patterns while preserving rejection behavior.
+- Documented why best-effort Grafana stream cancellation failures are intentionally ignored.
+- Removed redundant explicit `undefined` support from the optional lifecycle model context property.
+- Simplified lifecycle recovery header selection by replacing a nested conditional expression with explicit branches.
+- Removed redundant awaiting of Pi's synchronous lifecycle status update.
+- Replaced deprecated proxy tracer construction with an isolated always-off provider for disabled and shutdown trace states.
+- Validated OTLP endpoints as secret-free absolute HTTP(S) URLs and constructed signal exporter paths with deterministic URL pathname semantics.
+- Implemented opt-in, versioned, active-branch correlation persistence with bounded validation and idempotent reload recovery, and removed unsupported automatic replay configuration and synthetic duplicate startup telemetry.
+- Bound live telemetry, query commands, and backfill correlation to Pi's typed session manager, preserved identity across reload, adopted replacement-session identity, and refreshed active metadata on session rename.
+- Bounded and sanitized backend-derived `/obs cost`, `/obs tools`, and `/obs agents` labels, rows, and notification output with visible Unicode-safe truncation.
+- Unified `/obs session`, `/obs trace`, and `/obs link` on one validated trace-link builder with canonical placeholders, structured Grafana fallback URLs, and bounded configuration diagnostics.
+- Made multi-signal OpenTelemetry startup transactional with bounded rollback, a terminal failed controller state, sanitized Pi diagnostics, and clean later-session recovery.
+- Preserved malformed environment and file configuration as bounded rejection diagnostics, with source-specific `/obs status` reporting and strict trusted `.env` parsing.
+- Enforced coherent terminal subagent transitions across the integration API, agent tree, spans, events, metrics, runtime state, waits, and joins.
+- Enforced production acknowledgement for Grafana and OTLP certificate-verification bypasses, wired retained OTLP TLS behavior into every exporter, and exposed effective transport security in `/obs status` and `/obs health`.
+- Kept live-session and backfill OpenTelemetry providers scoped to ObservMe instead of replacing process-global providers.
+- Redacted complete supported PEM private-key blocks, including malformed/truncated input, across live and backfilled content capture.
+- Bounded all Grafana health and datasource response bodies before JSON parsing across default, custom Node, and injected fetch transports.
+- Enforced top-level ObservMe disablement across lifecycle startup, runtime state, integration availability, and all OpenTelemetry signal factories.
 - Restored clean npm dependency resolution by pinning TypeScript to the latest release supported by `typescript-eslint`.
 - Integrated active-agent lease activation and deactivation with clean shutdown, duplicate/reload replacement, resume, and failed-start cleanup so final flushes cannot renew stale activity.
 - Fixed session, workflow, agent, turn, LLM, tool, Bash, histogram, active-span, failure/recovery, and session-count telemetry accuracy.

package/README.md

@@ -162,12 +162,28 @@ const started = observme?.startSubagent({
 });
 
 if (started?.ok) {
-  await launchChildPi({ env: started.env });
-  observme.completeSubagent(started.spawnId, { childStatus: "active" });
+  let child;
+  try {
+    child = await launchChildPi({ env: started.env });
+  } catch (error) {
+    observme.failSubagent(started.spawnId, {
+      childAgentId: started.childAgentId,
+      errorClass: error instanceof Error ? error.name : "launcher_error",
+    });
+  }
+
+  if (child) {
+    const result = await waitForChildPi(child);
+    observme.completeSubagent(started.spawnId, {
+      childAgentId: started.childAgentId,
+      childStatus: result.status,
+      outcome: result.status,
+    });
+  }
 }
 ```
 
-The discovery helper fails open when the event bus or a provider is malformed. API methods also reject unsafe/oversized requests and duplicate active lifecycle IDs without replacing existing telemetry state. Handle every discriminated failure result locally and keep orchestration functional.
+The discovery helper fails open when the event bus or a provider is malformed. API methods also reject unsafe/oversized requests, duplicate active lifecycle IDs, and active or retained child-placeholder collisions without replacing existing telemetry state. Handle every discriminated failure result locally and keep orchestration functional.
 
 Use [`docs/extension-integration.md`](docs/extension-integration.md) for the complete lifecycle, validation limits, and failure contract. The shipped [`examples/integrations/subagent-runner.ts`](examples/integrations/subagent-runner.ts) wraps a generic child transport, while [`docs/agent-subagent-observability-requirements.md`](docs/agent-subagent-observability-requirements.md) covers the larger orchestration design.
 
@@ -268,7 +284,7 @@ All operational logs use short event bodies plus structured attributes. Correlat
 | Configuration, session, and workflow | `config.rejected`<br>`session.started`<br>`session.shutdown`<br>`session.duplicate_start`<br>`workflow.started`<br>`workflow.completed`<br>`workflow.failed` | Configuration diagnostics and top-level lifecycle/outcome events. |
 | Reserved session events | `session.named`<br>`session.error` | Public event names reserved for compatibility; current live handlers do not emit them. |
 | Agent run | `agent.run.started`<br>`agent.run.completed`<br>`agent.run.failed` | Agent-run lifecycle and outcome. |
-| Subagent lineage | `agent.spawn.started`<br>`agent.spawn.completed`<br>`agent.spawn.failed`<br>`agent.wait.started`<br>`agent.wait.completed`<br>`agent.join.started`<br>`agent.join.completed`<br>`agent.orphaned`<br>`trace_context.propagation_failed` | Parent/child lifecycle, lineage gaps, propagation failures, and join outcomes. |
+| Subagent lineage | `agent.spawn.started`<br>`agent.spawn.completed`<br>`agent.spawn.failed`<br>`agent.spawn.cancelled`<br>`agent.wait.started`<br>`agent.wait.completed`<br>`agent.join.started`<br>`agent.join.completed`<br>`agent.orphaned`<br>`trace_context.propagation_failed` | Parent/child lifecycle, lineage gaps, propagation failures, and join outcomes. |
 | Turn | `turn.started`<br>`turn.completed` | Turn lifecycle with run/turn correlation. |
 | LLM lifecycle | `llm.request.started`<br>`llm.request.completed`<br>`llm.request.failed` | Content-free provider request lifecycle, usage, cost, stop reason, and bounded errors. |
 | LLM content | `llm.prompt.captured`<br>`llm.response.captured`<br>`llm.thinking.captured` | Emitted only when the corresponding prompt, response, or thinking capture flag is enabled and redaction succeeds. |
@@ -287,7 +303,7 @@ ObservMe supports layered configuration with this precedence:
 defaults → global ~/.pi/agent/observme.yaml → trusted project config → trusted project .env → system environment variables → runtime options
 ```
 
-Factory-safe loading uses defaults/global/system-environment/runtime options only. Session-scoped loading can add trusted project config and a project-local `.env` when Pi marks the project trusted. `/obs status` reports the effective config source, whether project-local config was loaded, skipped because the project is untrusted, or missing, plus bounded rejection issue codes, the configured Grafana URL, and query-readiness status without rendering tokens or passwords. In untrusted projects, ObservMe does not read project-local config or `.env` files and uses safe defaults/global/system-environment layers instead. Invalid or unsafe configuration emits a bounded `config.rejected` diagnostic and falls back safely without exposing rejected values.
+Factory-safe loading uses defaults/global/system-environment/runtime options only. Session-scoped loading can add trusted project config and a project-local `.env` when Pi marks the project trusted. These project files must remain inside the stable canonical project root: in-root symlinks are supported, while out-of-root, dangling, replaced, or unverifiable paths fail closed through identity-verified file I/O. `/obs status` reports the effective config source, whether project-local config was loaded, skipped because the project is untrusted, missing, or rejected, plus bounded rejection issue codes, effective OTLP/Grafana transport security, the configured Grafana URL, and query-readiness status without rendering tokens, passwords, canonical targets, or external paths. In untrusted projects, ObservMe does not read project-local config or `.env` files and uses safe defaults/global/system-environment layers instead. Invalid or unsafe configuration emits a bounded `config.rejected` diagnostic and falls back safely without exposing rejected values.
 
 Cross-process agent lineage has a separate boundary: only the Pi process environment available to the shipped extension, or explicit runtime options for controlled embedders, is eligible for parent provenance. Project-local `.env` values configure ObservMe but cannot establish lineage. A child accepts only a complete validated workflow/parent/root/depth/spawn envelope and valid W3C context; malformed or stale envelopes fail open to a root/orphan fallback with sanitized telemetry.
 
@@ -317,7 +333,7 @@ To show failed-tool output such as GuardMe denial messages in the Tools dashboar
 
 Metadata such as token counts, duration, status, model/provider, tool name, and agent role/depth is captured by default. High-cardinality identifiers (session IDs, workflow IDs, agent IDs, trace/span IDs, entry IDs) are allowed on spans/logs for drill-down but are blocked from Prometheus metric labels.
 
-Grafana-backed query commands use the Grafana HTTP API, so browser login cookies are irrelevant. Configure either a Grafana service-account token (`OBSERVME_GRAFANA_TOKEN`) or local Basic auth (`OBSERVME_GRAFANA_USERNAME`/`OBSERVME_GRAFANA_PASSWORD`); token auth takes precedence and secrets are never rendered in command errors. You can supply these values as system environment variables before starting Pi, or copy the `.env.example` shipped with ObservMe to `.env` in a trusted project; system environment variables override `.env` values.
+Grafana-backed query commands use the Grafana HTTP API, so browser login cookies are irrelevant. Keep `query.grafana.url` credential-free; a base URL containing a username or password is rejected before network I/O with a bounded diagnostic that does not render the URL or credentials. Configure either a Grafana service-account token (`OBSERVME_GRAFANA_TOKEN`) or local Basic auth (`OBSERVME_GRAFANA_USERNAME`/`OBSERVME_GRAFANA_PASSWORD`); token auth takes precedence and secrets are never rendered in command errors. You can supply these values as system environment variables before starting Pi, or copy the `.env.example` shipped with ObservMe to `.env` in a trusted project; system environment variables override `.env` values.
 
 ### Supported local-stack query profile
 
@@ -343,7 +359,7 @@ query:
       preferIPv4: true
 ```
 
-Create a Grafana service-account token in Grafana (Administration → Users and access → Service accounts → Add service account/token; Viewer is enough for read-only datasource queries) and export it as `OBSERVME_GRAFANA_TOKEN`, or for local-only Basic auth read the generated admin password from the repository-only local stack's secrets directory. If you prefer a project-local env file, run `cp .env.example .env`, fill either `OBSERVME_GRAFANA_TOKEN` or `OBSERVME_GRAFANA_PASSWORD`, then restart Pi from that project. The local Collector and Loki profile uses `service.name=observme-pi-extension`; Loki queries use normalized labels such as `service_name`, `pi_session_id`, `pi_agent_id`, `pi_agent_run_id`, `event_name`, and `event_category`. If data is visible in Grafana but `/obs` commands fail, run `/obs health` and check extension env loading, Grafana auth, datasource UIDs, TLS, and DNS details.
+Create a Grafana service-account token in Grafana (Administration → Users and access → Service accounts → Add service account/token; Viewer is enough for read-only datasource queries) and export it as `OBSERVME_GRAFANA_TOKEN`, or for local-only Basic auth read the generated admin password from the repository-only local stack's secrets directory. Certificate verification stays enabled for HTTPS by default. Production rejects OTLP or Grafana certificate-verification bypass unless `privacy.allowInsecureTransport: true` explicitly acknowledges the risk; `otlp.tls.enabled` is not a supported setting because each endpoint URL scheme selects HTTP or HTTPS. If you prefer a project-local env file, run `cp .env.example .env`, fill either `OBSERVME_GRAFANA_TOKEN` or `OBSERVME_GRAFANA_PASSWORD`, then restart Pi from that project. The local Collector and Loki profile uses `service.name=observme-pi-extension`; Loki queries use normalized labels such as `service_name`, `pi_session_id`, `pi_agent_id`, `pi_agent_run_id`, `event_name`, and `event_category`. If data is visible in Grafana but `/obs` commands fail, run `/obs health` and check extension env loading, Grafana auth, datasource UIDs, TLS, and DNS details.
 
 ### Show LLM chat content in Grafana
 
@@ -368,7 +384,7 @@ Full configuration schema: `docs/reference/12-configuration-reference.md`. Full
 - ObservMe does not execute shell commands itself; it only observes tool/bash execution events emitted by Pi.
 - ObservMe never blocks Pi agent execution when the observability backend is degraded or unreachable.
 - ObservMe starts exporters only for a trusted session and shuts them down with bounded timeouts.
-- ObservMe does not continuously tail the full Pi session file; startup recovery reads only minimal session/correlation state, and historical replay requires an explicit `/obs backfill` command.
+- ObservMe does not continuously tail the full Pi session file. Optional correlation persistence uses one bounded `observme.correlation` custom entry on the active Pi branch, never LLM context; historical replay is never automatic and requires an explicit, confirmed `/obs backfill` command.
 - Optional content capture is disabled by default and must pass through the redaction pipeline before export when enabled.
 - `/obs` query commands are read-only and are not imported by telemetry-emission code paths.
 - Invalid or unsafe configuration falls back to safe defaults with bounded `config.rejected`, `/obs status`, and available Pi UI diagnostics; rejected values are never rendered. Intentionally unsafe capture emits a visible warning.

package/docs/agent-subagent-observability-requirements.md

@@ -565,6 +565,7 @@ agent.run.failed
 agent.spawn.started
 agent.spawn.completed
 agent.spawn.failed
+agent.spawn.cancelled
 agent.wait.started
 agent.wait.completed
 agent.join.started
@@ -833,9 +834,9 @@ Minimum adapter behavior:
 1. Request the API with `requestObservMeIntegration(pi)`.
 2. Before spawning child Pi, call `startSubagent` with spawn type/reason and safe command metadata.
 3. Pass the returned `env` into `child_process.spawn`.
-4. On launcher success, call `completeSubagent` with child status `active`.
-5. On launcher error/abort/failure, call `failSubagent` or complete with cancelled status.
-6. Around blocking waits, call `startWait` and `endWait`.
+4. On launcher error before the child runs, call `failSubagent`.
+5. Around blocking waits, call `startWait` and `endWait`.
+6. When the child reaches a terminal state, call `completeSubagent` once with matching `completed`, `failed`, or `cancelled` status/outcome fields.
 7. When child output is collected, call `startJoin` and `endJoin` with child status.
 8. Ensure the child command loads ObservMe as an extension/package.
 9. Ensure the child ObservMe runtime receives the complete propagated parent context.

package/docs/compatibility-matrix.md

@@ -1,9 +1,15 @@
 # ObservMe Compatibility Matrix
 
-Last updated: 2026-07-14
+Last updated: 2026-07-22
 
 This matrix records the ObservMe runtime and observability-stack versions exercised or pinned for the current release line. A component is marked **validated** only when the named command actually exercised it; configured CI targets remain distinct from completed local or workflow evidence.
 
+## Pi version policy
+
+ObservMe never uses Pi's reported version as a startup gate. The Pi-mandated core package peers remain in `peerDependencies` with `"*"`, while exact 0.80.5 and 0.81.1 targets record compatibility evidence in CI. Before registering anything, startup checks only the essential `ExtensionAPI` capabilities `on` and `registerCommand`. When those methods exist, ObservMe starts regardless of whether Pi's version is older, newer, prerelease, malformed, or unavailable. Optional APIs are feature-detected by the handlers that use them.
+
+Pi 0.80.5 is the earliest tested version, not a runtime minimum: its exported extension contract includes `session_info_changed`, which ObservMe uses for live rename metadata. Pi's current extension overloads do not include `bashExecution`, `model_change`, or `thinking_level_change`. `bashExecution` is an `AgentMessage` role observed through `message_end`, while model and thinking changes are session entry types represented at runtime by `model_select` and `thinking_level_select`; ObservMe no longer registers those three non-event names. Tested versions provide release evidence only and never define an accepted or rejected runtime range.
+
 ## Validation record
 
 | Date | Environment | Command | Coverage |
@@ -12,6 +18,11 @@ This matrix records the ObservMe runtime and observability-stack versions exerci
 | 2026-07-07 | Local Docker 29.5.2 with Collector Contrib 0.104.0 | `npm run test:integration:collector` | Starts a local debug-exporter Collector container, exports representative ObservMe traces/metrics/logs, and asserts default-disabled content capture is absent. |
 | 2026-07-07 | Local Docker 29.5.2 with the pinned Grafana stack | `npm run test:integration:grafana-stack` | Starts `observability-stack/` services, exports representative ObservMe telemetry, queries Tempo by trace ID and lineage attributes, queries Loki by session ID, queries Prometheus token totals, and validates Grafana dashboard provisioning imports. |
 | Continuous integration target | GitHub Actions `ubuntu-latest`, Node.js 22.19.0 | `npm ci --ignore-scripts` then `npm run validate` | CI target from `.github/workflows/ci.yml`; record the workflow run URL here after each release validation. |
+| Pi compatibility CI matrix (updated 2026-07-22) | GitHub Actions `ubuntu-latest`, Node.js 22.19.0; exact Pi 0.80.5 and 0.81.1 matrix targets | Exact Pi install, version assertion, then `npm run validate:pi-compatibility` | Compile-time event fixtures, capability diagnostics, package install, handler/lifecycle smoke, and a real Pi RPC runtime are exercised separately at the earliest-tested and release-tested versions. |
+| 2026-07-14 | Local Node.js v26.0.0, npm 11.12.1; exact `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` 0.80.5 | Exact version assertion then `npm run validate:pi-compatibility` | Passed typecheck, typed event contracts, capability diagnostics, packaged install, handler/lifecycle smoke, and real Pi RPC runtime at the earliest-tested version. |
+| 2026-07-14 | Local Node.js v26.0.0, npm 11.12.1; exact `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` 0.80.6 | Exact version assertion then `npm run validate:pi-compatibility` | Passed the same compatibility suite at the former release-tested version. |
+| 2026-07-22 | Local Node.js v26.0.0, npm 11.12.1; exact `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` 0.81.1 | Exact version assertion, typechecks, compatibility tests, packaged install, handler/lifecycle smoke, and real Pi RPC runtime | Passed the complete `npm run validate:pi-compatibility` suite at the current release-tested version. |
+| 2026-07-22 | Local Node.js v26.0.0, npm 11.12.1; exact Pi 0.81.1 development dependencies | `npm run validate` | Passed source/test typechecks, ESLint, formatting, 618 unit/contract tests, package-content checks, packaged-install smoke, handler smoke, Pi lifecycle smoke, and real Pi runtime smoke. |
 | Lease cancellation CI profile (configured 2026-07-14) | GitHub-hosted Linux `ubuntu-latest` (exact `ImageOS`/`ImageVersion` recorded in the Actions runner log); Node.js 22.19.0; Collector Contrib 0.104.0; Prometheus 2.53.1; Grafana 11.1.0 | `npm run test:active-agent-lease:contracts` then `npm run test:integration:active-agent-lease` | The bounded `lease-cancellation` job validates clean shutdown, `SIGTERM`, and cancellation-oriented `SIGKILL` convergence against the pinned Collector and Prometheus without secrets or a Grafana dependency. Grafana 11.1.0 is the recorded dashboard compatibility baseline validated separately by `npm run test:integration:grafana-stack`. `if: always()` cleanup is best effort; lease expiry is the asserted correctness mechanism. |
 | 2026-07-14 | Local Node.js v26.0.0, npm 11.12.1 | `npm run validate` | Passed 493 unit/contract tests plus typecheck, ESLint, formatting, script, package-content, packaged-install, handler, Pi lifecycle, and Pi runtime checks for the lease release candidate. |
 | 2026-07-14 | Local Docker 29.5.2, Compose 5.1.4, Collector Contrib 0.104.0 | `npm run test:integration:collector`; Compose config; pinned Collector `validate` | Passed representative OTLP export, Compose interpolation, and the shipped Collector config validation. |
@@ -25,7 +36,7 @@ Active-agent lease interpretation additionally requires producer and Prometheus
 
 | Component | Version tested or pinned | Source of truth | Status | Evidence and notes |
 | --- | --- | --- | --- | --- |
-| Pi package API | `@earendil-works/pi-coding-agent` 0.80.3, `@earendil-works/pi-ai` 0.80.3 | `package-lock.json` | Validated locally | `npm run validate` typechecks the Pi extension API imports and runs smoke harnesses against registered extension handlers. |
+| Pi package API | Runtime policy: required API capabilities only; version never gates startup. Earliest tested Pi: 0.80.5; release-tested `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai`: 0.81.1 | `package.json` `observmeCompatibility`, exact dev dependencies, `package-lock.json`, `.github/workflows/ci.yml` | Validated locally at earliest-tested 0.80.5 and release-tested 0.81.1; exact CI matrix configured | `npm run validate:pi-compatibility` typechecks exported event contracts, tests pre-registration capability diagnostics, installs the package, runs handler/lifecycle smoke, and launches the real Pi RPC runtime. Pi version values do not participate in startup acceptance. |
 | Node.js | Local: 26.0.0; CI target/minimum: 22.19.0 | `node --version`, `package.json` `engines.node`, `.github/workflows/ci.yml` | Validated locally for 26.0.0; CI target pinned at 22.19.0 | Local validation ran on 26.0.0. CI is configured to validate on 22.19.0, which is also the minimum supported Node.js version. |
 | OpenTelemetry JS package set | `@opentelemetry/api` 1.9.1; `@opentelemetry/api-logs` 0.220.0; OTLP proto exporters 0.220.0; `@opentelemetry/resources` 2.9.0; `@opentelemetry/sdk-logs` 0.220.0; `@opentelemetry/sdk-metrics` 2.9.0; `@opentelemetry/sdk-trace-base` 2.9.0; `@opentelemetry/sdk-trace-node` 2.9.0 | `package.json`, `package-lock.json` | Validated locally | `npm run validate` includes the OTEL lifecycle/exporter unit tests under `test/otel-*.test.mjs`. |
 
@@ -41,7 +52,7 @@ Active-agent lease interpretation additionally requires producer and Prometheus
 
 ## Update rules
 
-- Update this file whenever `package-lock.json`, `.github/workflows/ci.yml`, or `observability-stack/docker-compose.yml` changes a tracked version.
+- Update this file whenever `package.json` `observmeCompatibility`, `package-lock.json`, `.github/workflows/ci.yml`, or `observability-stack/docker-compose.yml` changes a tracked version.
 - Add a new validation-record row whenever a release candidate is validated locally, in CI, or against the Docker Compose stack.
 - Do not mark backend components as validated unless a command actually started or queried that component.
 - Keep workflow IDs, session IDs, agent IDs, trace IDs, and other high-cardinality values out of this document.

package/docs/configuration.md

@@ -18,12 +18,12 @@ The standard Pi distribution currently resolves this to `.pi/observme.yaml`. Obs
 
 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.
+- `otlp.endpoint` and `otlp.signalEndpoints` — absolute HTTP(S) OpenTelemetry Collector URLs. Base endpoints may include an intentional path; ObservMe appends one `/v1/{signal}` suffix with URL pathname semantics. Signal-specific endpoints must already end in the matching signal path. Keep credentials in `otlp.headers`; endpoint userinfo, unresolved placeholders, queries, and fragments are rejected.
 - `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`.
+- `query.links.traceUrlTemplate` — the canonical Grafana Explore trace-link template used by `/obs session`, `/obs trace`, and `/obs link`; use `{traceId}`, `{{traceId}}`, `${traceId}`, or `%TRACE_ID%`, or keep the generated `...` structured fallback.
 - `metrics.activeAgentLeaseDurationMillis` — how long the last exported active-agent lease remains valid. The default is `60000` ms, the supported range is `10000`–`300000` ms, and the value must be at least `(2 * metrics.exportIntervalMillis) + 5000` ms. `OBSERVME_ACTIVE_AGENT_LEASE_DURATION_MS` overrides YAML through the normal precedence rules.
 
 The shipped dashboards and alerts combine a positive `observme_active_agents` lifecycle claim with a current lease; raw active-claim sums are diagnostic only after an ungraceful exit. Clean shutdown reaches zero after normal export/scrape propagation. Crash, `SIGKILL`, forced GitHub Actions cancellation, or runner loss converges within the lease plus up to 5 seconds of supported clock skew and one Prometheus scrape/evaluation interval, without restarting the Collector. Keep producer and Prometheus clocks synchronized within 5 seconds; GitHub-hosted runners meet this expectation, while self-hosted runners require reliable NTP or an equivalent time service.

package/docs/extension-integration.md

@@ -58,9 +58,9 @@ Use this order for each child process:
 1. Request the ObservMe integration API.
 2. Call `startSubagent()` immediately before launching the child.
 3. Pass the returned `env` as the child process environment without logging it.
-4. Call `completeSubagent(..., { childStatus: "active" })` when the launcher successfully creates the child.
-5. Call `failSubagent()` when the launcher fails before the child is active.
-6. Call `startWait()`/`endWait()` around time spent waiting for child completion.
+4. Call `failSubagent()` only when the launcher fails before the child is running.
+5. Call `startWait()`/`endWait()` around time spent waiting for child completion.
+6. Call `completeSubagent()` once with the matching terminal `childStatus` and `outcome` (`completed`, `failed`, or `cancelled`).
 7. Call `startJoin()`/`endJoin()` when collecting the terminal child status or result.
 
 ```typescript
@@ -78,12 +78,9 @@ if (!started?.ok) {
   return;
 }
 
+let child;
 try {
-  await launchChildPi({ env: started.env });
-  observme.completeSubagent(started.spawnId, {
-    childAgentId: started.childAgentId,
-    childStatus: "active",
-  });
+  child = await launchChildPi({ env: started.env });
 } catch (error) {
   observme.failSubagent(started.spawnId, {
     childAgentId: started.childAgentId,
@@ -91,6 +88,13 @@ try {
   });
   throw error;
 }
+
+const result = await waitForChildPi(child);
+observme.completeSubagent(started.spawnId, {
+  childAgentId: started.childAgentId,
+  childStatus: result.status,
+  outcome: result.status,
+});
 ```
 
 Do not put raw tasks, prompts, command lines, environment values, child output, or private paths in `errorClass`, `spawnReason`, or other bounded fields.
@@ -101,7 +105,7 @@ Do not put raw tasks, prompts, command lines, environment values, child output,
 | --- | --- |
 | `getContext()` | Read the current workflow, root/parent/current agent, role, depth, session, and trace identifiers for local orchestration correlation. These are high-cardinality values and must not become metric labels. |
 | `startSubagent(options)` | Starts `pi.agent.spawn`, records spawn metrics/logs, creates bounded parent tree state, and returns a sanitized propagation environment. |
-| `completeSubagent(spawnId, options)` | Ends a successful launcher operation. Use child status `active` when the child is running; use `completed` only when launch and child completion are intentionally represented together. |
+| `completeSubagent(spawnId, options)` | Ends the active child lifecycle with one coherent `completed`, `failed`, or `cancelled` status/outcome pair. |
 | `failSubagent(spawnId, options)` | Ends a launcher failure and records bounded failure telemetry. |
 | `startWait(options)` / `endWait(id, options)` | Measures time the parent is blocked on a child or dependency. |
 | `startJoin(options)` / `endJoin(id, options)` | Measures result collection and records child failure propagation or confirmed parent recovery. |
@@ -111,16 +115,16 @@ Do not put raw tasks, prompts, command lines, environment values, child output,
 | Option | Values and meaning |
 | --- | --- |
 | `spawnId` | Optional caller-generated safe ID; omit to let ObservMe generate it. |
-| `childAgentId` | Optional bounded parent-side placeholder; this is not propagated as the child's real agent ID. |
+| `childAgentId` | Optional bounded parent-side placeholder; this is not propagated as the child's real agent ID and must remain unique while its active or terminal node is retained. |
 | `command` / `args` | Used only to create a salted command fingerprint when configured; raw values are not exported. Omit them if the launcher cannot safely provide them. |
 | `spawnType` | `command`, `tool`, `extension`, or `unknown`. |
 | `spawnReason` | `delegated_task`, `parallel_search`, `review`, `tool_wrapper`, or `unknown`. |
 | `toolCallId` | Optional high-cardinality trace/log correlation when a tool initiated the spawn. |
 | `env` | Base child environment. ObservMe removes stale lineage/W3C keys and returns the replacement environment. |
 
-Runtime callers are validated even when JavaScript bypasses the TypeScript types. Caller-provided lifecycle identifiers must match `[A-Za-z0-9._:-]{1,128}`. Commands and individual arguments are capped at 4096 characters, argument lists at 256 items, and environment objects at 4096 entries. Durations must be finite, non-negative milliseconds. Invalid or duplicate active operations return a failure without replacing an existing span.
+Runtime callers are validated even when JavaScript bypasses the TypeScript types. Caller-provided lifecycle identifiers must match `[A-Za-z0-9._:-]{1,128}`. Commands and individual arguments are capped at 4096 characters, argument lists at 256 items, and environment objects at 4096 entries. Durations must be finite, non-negative milliseconds. Invalid or duplicate active operations return a failure without replacing an existing span. Child placeholders, including generated placeholders, are collision-checked before span, tree, metric, or propagation state is created; do not reuse a terminal placeholder while its bounded tree node remains retained.
 
-Completion and wait/join methods use bounded child states (`starting`, `active`, `completed`, `failed`, `cancelled`, `orphaned`), join states (`waiting`, `completed`, `failed`, `cancelled`, `timeout`, `unknown`), and wait reasons (`dependency`, `rate_limit`, `child_running`, `unknown`). `failurePropagated=false` on a completed join confirms that the parent recovered from a failed child.
+Completion accepts only terminal child states (`completed`, `failed`, `cancelled`), and any supplied outcome must match. Wait/join methods use bounded child states (`starting`, `active`, `completed`, `failed`, `cancelled`, `orphaned`), join states (`waiting`, `completed`, `failed`, `cancelled`, `timeout`, `unknown`), and wait reasons (`dependency`, `rate_limit`, `child_running`, `unknown`). `failurePropagated=false` on a completed join confirms that the parent recovered from a failed child.
 
 All mutation methods return a discriminated result. Handle these reasons without crashing Pi:
 
@@ -129,7 +133,10 @@ All mutation methods return a discriminated result. Handle these reasons without
 | `session_unavailable` | ObservMe is loaded but no telemetry session is active. |
 | `invalid_request` | An identifier, enum, duration, command/argument field, or environment shape is invalid or oversized. |
 | `spawn_already_exists` / `wait_already_exists` / `join_already_exists` | The requested lifecycle identifier is already active. Generate a unique identifier or finish the active operation; do not overwrite it. |
+| `child_agent_already_exists` | The requested or generated child placeholder belongs to an active spawn or retained tree node. Generate a unique child identifier; do not reuse terminal placeholders. |
 | `spawn_not_found` / `wait_not_found` / `join_not_found` | The lifecycle handle is absent or has already ended. |
+| `child_agent_mismatch` | The supplied child ID does not match the child stored for the active spawn. |
+| `invalid_terminal_transition` | Terminal status/outcome fields contradict each other or would rewrite an existing terminal tree state. |
 | `operation_failed` | ObservMe could not safely complete the operation. |
 
 Do not retry a completed lifecycle handle blindly; repeated completion can otherwise hide an orchestration-state bug.
@@ -183,7 +190,7 @@ The integration API is transport-agnostic. A launcher can use a local subprocess
 
 - passes the returned environment unchanged to the child Pi process;
 - does not serialize the envelope or raw task into telemetry or captured logs;
-- reports launcher completion/failure separately from child completion;
+- reports launcher failure separately from child completion, failure, or cancellation;
 - records wait and join around the transport's actual blocking and result-collection boundaries;
 - guarantees the child loads a compatible ObservMe extension;
 - cleans up temporary files, pipes, sessions, containers, or remote resources deterministically.

package/docs/reference/03-pi-event-and-session-model.md

@@ -105,7 +105,7 @@ Optional telemetry:
 
 ### `custom` entry
 
-Extension state entry created through `pi.appendEntry()`. It does not participate in LLM context. ObservMe should append a custom entry only for explicitly enabled minimal correlation state; by default it should not append custom entries.
+Extension state entry created through `pi.appendEntry()`. It does not participate in LLM context. When `agent.writeCorrelationEntry` is explicitly enabled, ObservMe appends at most one `observme.correlation` entry per active branch after telemetry startup succeeds. The versioned data contains only bounded workflow/agent lineage identifiers and depth. Startup scans `ctx.sessionManager.getBranch()` from newest to oldest, restores the latest valid entry, ignores corrupt entries and entries on abandoned branches, and skips an idempotent reload write. By default ObservMe does not append custom entries.
 
 ### `custom_message` entry
 
@@ -244,12 +244,12 @@ The derived id must be scoped by session id and agent run id and must not be use
 
 On extension startup in an existing session:
 
-1. Read current session header if available.
+1. Read the current session header from `ctx.sessionManager` if available.
 2. Set `pi.session.id`, `pi.workflow.id`, `pi.agent.id`, and resource attributes.
-3. Reconstruct optional workflow/agent lineage only from trusted environment variables or an explicitly enabled minimal custom correlation entry.
-4. Do not replay old telemetry by default.
-5. Optionally support `replayOnStart: true` for backfill, but it must be off by default.
-6. If replay is enabled, mark spans/logs with `observme.replayed=true`.
+3. When `agent.writeCorrelationEntry` is enabled, reconstruct optional workflow/agent lineage only from the latest validated `observme.correlation` custom entry on `ctx.sessionManager.getBranch()`.
+4. Ignore malformed entries and entries outside the active branch without exporting their values or changing LLM context.
+5. After successful startup, append the minimal custom entry only when the active branch does not already contain the same validated correlation.
+6. Never replay historical telemetry automatically. Historical export requires the explicit, confirmed `/obs backfill` command, which marks each emitted record with `observme.replayed=true`.
 
 ## 11. Local Session Reading Rules
 

package/docs/reference/04-telemetry-semantic-conventions.md

@@ -702,6 +702,7 @@ agent.run.failed
 agent.spawn.started
 agent.spawn.completed
 agent.spawn.failed
+agent.spawn.cancelled
 agent.wait.started
 agent.wait.completed
 agent.join.started

package/docs/reference/06-security-privacy-redaction.md

@@ -105,7 +105,7 @@ GitHub token:                (gh[pousr]_[A-Za-z0-9_]{36,}|github_pat_[A-Za-z0-9_
 OpenAI-like key:             sk-[A-Za-z0-9_-]{20,}
 Anthropic-like key:          sk-ant-[A-Za-z0-9_-]{20,}
 Slack token:                 xox[baprs]-[A-Za-z0-9-]{10,}
-Private key block:           -----BEGIN [A-Z ]*PRIVATE KEY-----
+Private key block:           complete uppercase labels ending in PRIVATE KEY (including PKCS#8, encrypted, RSA, and EC)
 Password assignment:         (?i)(password|passwd|pwd)\s*[:=]\s*[^\s]+
 API key assignment:          (?i)(api[_-]?key|token|secret|client[_-]?secret)\s*[:=]\s*[^\s]+
 URL credentials:             [a-z][a-z0-9+.-]*://[^\s:/?#]+:[^\s@/]+@
@@ -113,6 +113,8 @@ URL credentials:             [a-z][a-z0-9+.-]*://[^\s:/?#]+:[^\s@/]+@
 
 These patterns are a minimum safety net, not a complete secret scanner. Keep them covered by tests and allow organizations to add custom regexes for proprietary credential formats.
 
+Private-key matching consumes a `PRIVATE KEY` label with an optional, bounded uppercase prefix, its body, and a same-label `END` marker with a 1,000,000-character body scan bound. This covers PKCS#8 (`PRIVATE KEY`), `ENCRYPTED PRIVATE KEY`, `RSA PRIVATE KEY`, `EC PRIVATE KEY`, and other uppercase private-key labels without accepting public-key labels. The shared input-size guard drops larger captured values before secret matching. If a supported private-key marker has no matching footer because it is missing, truncated, or mislabeled, redaction fails closed by replacing everything from that marker through the end of the captured value. `PUBLIC KEY` and `RSA PUBLIC KEY` blocks are not private-key matches.
+
 Matched values are replaced with:
 
 ```text
@@ -228,7 +230,7 @@ Example:
 
 The Collector cannot recover content dropped by an older configuration; generate new LLM events after updating the Collector and dashboards. Do not use raw chat text in Loki or Tempo query strings.
 
-## 11. Authentication
+## 11. Authentication and Credential-Free Endpoint URLs
 
 ObservMe supports OTLP headers:
 
@@ -238,7 +240,9 @@ otlp:
     Authorization: "Bearer ${OBSERVME_OTLP_TOKEN}"
 ```
 
-Secrets must be read from environment variables or secure runtime config, not hardcoded in extension source.
+Grafana base URLs must be absolute HTTP(S) URLs without embedded username or password components. Configure Grafana authentication only through `query.grafana.token` or the complete `query.grafana.username` and `query.grafana.password` pair. A credential-bearing base URL is rejected during configuration validation and query readiness, before either Grafana transport can perform network I/O. Diagnostics report only the safe `embedded_credentials` failure class and dedicated setting names; they do not render the rejected URL or credential values.
+
+Secrets must be read from environment variables or secure runtime config, not hardcoded in extension source or embedded in endpoint URLs.
 
 ## 12. TLS
 
@@ -246,12 +250,12 @@ Production default:
 
 ```yaml
 otlp:
+  endpoint: https://otel-collector.example.com:4318
   tls:
-    enabled: true
     insecureSkipVerify: false
 ```
 
-Development may use insecure local endpoints only when explicitly configured.
+The endpoint URL scheme selects TLS. The OTLP exporters explicitly keep certificate verification enabled unless `otlp.tls.insecureSkipVerify: true` is configured. Grafana query transport follows the same rule through `query.grafana.tls.insecureSkipVerify`. Production rejects either verification bypass, and any plain HTTP endpoint, unless `privacy.allowInsecureTransport: true` records the explicit insecure-transport acknowledgement. Development may use local HTTP or self-signed certificates, but the insecure setting remains visible in `/obs status` and `/obs health`.
 
 ## 13. Tenant Isolation
 
@@ -281,10 +285,13 @@ Do not log secrets while reporting security failures.
 
 ## 15. Safe Config Validation
 
+Trusted project config, project `.env`, and starter-config creation share one filesystem boundary. Their lexical paths and canonical targets must remain inside the stable canonical project root. Existing symlinks are supported only when they resolve to files or directories inside that root; out-of-root, dangling, replaced, or unverifiable paths fail closed. Reads and starter writes use identity-verified file handles and recheck containment so a concurrent file, ancestor, or root change cannot substitute an external target. A rejected project source is not loaded, starter creation does not overwrite an existing file, and diagnostics expose only a bounded failure class rather than canonical or external path details.
+
 Reject config if:
 
 - capture is enabled but redaction is disabled, unless `allowUnsafeCapture: true`
-- OTLP endpoint is plain HTTP in production, unless `allowInsecureTransport: true`
+- an OTLP or Grafana endpoint is plain HTTP in production, unless `allowInsecureTransport: true`
+- OTLP or Grafana certificate verification is bypassed in production, unless `allowInsecureTransport: true`
 - metric labels include forbidden high-cardinality fields such as workflow IDs, session IDs, or agent IDs
 - propagated workflow or agent lineage values are malformed, too long, or contain unsafe characters
 - queue sizes exceed configured memory limits

package/docs/reference/08-query-grafana-integration.md

@@ -43,9 +43,10 @@ query:
 
 Authentication and local transport behavior:
 
-- Prefer `query.grafana.token` for Grafana service-account or bearer tokens.
+- Keep `query.grafana.url` credential-free: it must be an absolute HTTP(S) base URL with no embedded username or password component.
+- Configure authentication only with `query.grafana.token` or the dedicated `query.grafana.username` and `query.grafana.password` settings. Prefer the token for Grafana service-account or bearer authentication.
 - If the token is blank or an unresolved environment placeholder, ObservMe may use `query.grafana.username` plus `query.grafana.password` as a local-development Basic auth fallback.
-- Query-backed commands fail fast before backend calls when Grafana auth is unresolved/missing/incomplete, `query.grafana.url` is invalid, or a required datasource UID is blank.
+- Query-backed commands fail fast before backend calls when Grafana auth is unresolved/missing/incomplete, `query.grafana.url` is invalid or contains credentials, or a required datasource UID is blank. Credential-bearing URLs report the safe `embedded_credentials` class without rendering the URL or credential values.
 - `401` and `403` responses are surfaced as Grafana authentication failures without printing token or password values.
 - Browser login cookies are irrelevant because `/obs` commands call the Grafana API directly from the Pi process.
 
@@ -71,7 +72,7 @@ query:
       preferIPv4: true
 ```
 
-For the bundled `observability-stack/`, the supported command path is nginx HTTPS at `https://observability.local`; the default stack does not publish Grafana on `localhost:3000`. Create a Grafana service-account token with Viewer access for read-only datasource queries and export it as `OBSERVME_GRAFANA_TOKEN`, or export/set `OBSERVME_GRAFANA_PASSWORD` from `observability-stack/secrets/grafana_admin_password` for local Basic auth. Extension environment values can come from system environment variables before Pi starts, or from a trusted project `.env` copied from `.env.example`; system variables override `.env`. The local self-signed certificate requires `query.grafana.tls.insecureSkipVerify=true`, and `query.grafana.transport.preferIPv4=true` avoids DNS stalls when `observability.local` resolves to IPv6 first. Provisioned datasource UIDs are `tempo`, `loki`, and `prometheus`; Loki selectors use normalized labels such as `service_name`, `pi_session_id`, `event_name`, and `event_category`.
+For the bundled `observability-stack/`, the supported command path is nginx HTTPS at `https://observability.local`; the default stack does not publish Grafana on `localhost:3000`. Create a Grafana service-account token with Viewer access for read-only datasource queries and export it as `OBSERVME_GRAFANA_TOKEN`, or export/set `OBSERVME_GRAFANA_PASSWORD` from `observability-stack/secrets/grafana_admin_password` for local Basic auth. Extension environment values can come from system environment variables before Pi starts, or from a trusted project `.env` copied from `.env.example`; system variables override `.env`. The local self-signed certificate requires `query.grafana.tls.insecureSkipVerify=true`, and `query.grafana.transport.preferIPv4=true` avoids DNS stalls when `observability.local` resolves to IPv6 first. Production configurations using the TLS bypass must also set `privacy.allowInsecureTransport=true` as an explicit acknowledgement; trusting the production CA remains preferred. Provisioned datasource UIDs are `tempo`, `loki`, and `prometheus`; Loki selectors use normalized labels such as `service_name`, `pi_session_id`, `event_name`, and `event_category`.
 
 ## 4. Commands
 
@@ -84,6 +85,9 @@ Output:
 ```text
 ObservMe: enabled
 OTLP endpoint: https://otel.example.com:4318
+OTLP transport security: TLS certificate verification enabled
+Grafana URL: https://grafana.example.com/
+Grafana transport security: TLS certificate verification enabled
 Traces: enabled
 Metrics: enabled
 Logs: enabled
@@ -97,6 +101,8 @@ Last export error: none
 Checks Collector and Grafana reachability, and reports Grafana query auth/config readiness before datasource calls.
 
 ```text
+Collector transport security: TLS certificate verification enabled
+Grafana transport security: TLS certificate verification enabled
 Collector: reachable
 Grafana: reachable
 Tempo datasource: ok
@@ -216,13 +222,22 @@ Only available if Loki receives `pi.session.id` as structured metadata or label.
 
 ## 5. Trace Links
 
-If trace id is available:
+`/obs session`, `/obs trace`, and `/obs link` use the same pure trace-link builder, so one effective config and trace ID always produce one canonical URL. Custom absolute HTTP(S) templates support these trace-ID placeholders:
 
-```text
-https://grafana.example.com/explore?schemaVersion=1&panes=...
+- `{traceId}`
+- `{{traceId}}` or `{{ traceId }}`
+- `${traceId}`
+- `%TRACE_ID%`
+
+The matching optional Tempo datasource placeholders are `{tempoDatasourceUid}`, `{{tempoDatasourceUid}}` (whitespace is allowed), `${tempoDatasourceUid}`, and `%TEMPO_DATASOURCE_UID%`. Trace IDs and datasource UIDs are URL-encoded before substitution.
+
+An empty template or a template containing `...` selects the structured Grafana Explore fallback. The fallback uses `query.grafana.url`, preserves any path prefix, and constructs the current `schemaVersion=1&panes=...` Tempo query with `query.grafana.datasourceUids.tempo`. This is the behavior used by the generated starter:
+
+```yaml
+traceUrlTemplate: https://observability.local/explore?left=...
 ```
 
-ObservMe should support configurable URL templates because Grafana URL encoding changes across versions and organizations.
+Unsupported placeholders, non-HTTP(S) URLs, credential-bearing URLs, and malformed or oversized templates produce one bounded actionable diagnostic; commands do not silently omit a link or apply different substitutions.
 
 ## 6. Grafana Query Abstraction
 
@@ -258,6 +273,14 @@ query:
   maxAgents: 20
 ```
 
+Each query result-count setting accepts integers from 1 through 100. Runtime query clients clamp programmatically supplied values to the same ceiling before adding a backend request limit or selecting parsed results.
+
+### Bounded command display
+
+Prometheus label keys and values used for `/obs` display are normalized before they enter command snapshots. Control and line-separator characters become spaces, repeated whitespace collapses, and each label is limited to 96 UTF-16 code units. Truncated labels retain a valid Unicode prefix and end with `…`.
+
+`/obs cost` renders at most 20 rows. `/obs tools` renders at most 20 call rows and 20 failure rows. Omitted rows are reported explicitly. `/obs agents` retains its 10-row recent-child display limit. Every final `/obs` notification is normalized to remove terminal controls other than intended line feeds and is limited to 64 rows and 8,192 UTF-16 code units. A notification that reaches either hard limit ends with `… output truncated`. These display bounds do not change backend queries, metric identity, or emitted telemetry.
+
 ## 8. Dependency Direction
 
 ObservMe telemetry emission must not depend on Grafana query availability.

package/docs/reference/11-deployment-runbooks.md

@@ -169,6 +169,27 @@ GitHub-hosted runners satisfy the supported clock expectation. A self-hosted run
 
 ## 5. Common Incidents
 
+### Grafana-Backed Commands Reject the Base URL
+
+If `/obs status`, `/obs health`, or a query-backed command reports `embedded_grafana_url_credentials` or `embedded_credentials`:
+
+1. Configure `query.grafana.url` as an absolute HTTP(S) base URL without an embedded username or password component.
+2. Put bearer authentication in `query.grafana.token`, or configure both `query.grafana.username` and `query.grafana.password`. Prefer environment-variable references rather than secret values in YAML.
+3. Restart Pi, then rerun `/obs status` and `/obs health`.
+
+ObservMe rejects this URL class before default-fetch or custom-transport network I/O. Diagnostics intentionally identify only the safe failure class and setting names, never the rejected URL or credentials.
+
+### Project Config or `.env` Is Rejected
+
+Project-local configuration is loaded only for a trusted project and only while its lexical and canonical paths remain inside the stable canonical project root.
+
+1. Confirm Pi marks the project trusted.
+2. Use a normal in-root config directory and `.env` file, or symlinks whose existing targets also remain inside the same project root.
+3. Replace out-of-root, dangling, or changing symlinks and retry the session start. Do not bypass the containment check.
+4. Review `/obs status` for `config_source_rejected`; bootstrap failures appear as a bounded warning.
+
+ObservMe fails closed if it cannot verify the root, target, or opened-file identity. A rejected project config or `.env` is not read, starter creation never overwrites an existing target, and diagnostics omit canonical and external path details. Other accepted configuration layers continue to apply.
+
 ### No Traces in Tempo
 
 Check: