@senad-d/observme 0.1.3 → 0.1.5

package/dashboards/observme-trace-journey.json

@@ -144,7 +144,7 @@
         "type": "prometheus",
         "uid": "prometheus"
       },
-      "description": "Current ObservMe agent runtimes from the active-agent gauge. Zero can mean healthy idle or an absent gauge; check Export Health before treating an unexpected zero as healthy.",
+      "description": "Canonical leased-active fleet total; Prometheus summary values are aggregate and are not filtered to the selected workflow. Clean shutdown reaches zero after export/scrape propagation; after a crash, SIGKILL, cancelled job, or runner loss, the leased total converges to zero within the default 60-second lease plus one Prometheus scrape even if raw claims stay cached. Zero can also mean healthy idle or a failed-closed lease, so check Export Health. /obs agents is current-process child state, not fleet liveness.",
       "fieldConfig": {
         "defaults": {
           "color": {
@@ -195,7 +195,7 @@
             "uid": "prometheus"
           },
           "editorMode": "code",
-          "expr": "(sum(observme_active_agents) or vector(0))",
+          "expr": "sum(max by (observme_instance_id) ((observme_active_agents > 0) and on (observme_instance_id) ((observme_agent_lease_expires_unixtime_seconds > time()) and (observme_agent_lease_expires_unixtime_seconds <= time() + 305)))) or vector(0)",
           "instant": true,
           "range": false,
           "refId": "A"
@@ -1005,7 +1005,7 @@
         "type": "prometheus",
         "uid": "prometheus"
       },
-      "description": "Shape of the agent tree over time without using workflow or agent IDs as metric labels. Constant reference lines mirror the depth=5 and fan-out=20 alert thresholds.",
+      "description": "Aggregate fleet shape over time, not per-workflow truth: the leased-active role series is canonical current activity, while tree histograms summarize all matching telemetry without workflow or agent IDs as metric labels. Clean shutdown removes leased activity after export/scrape propagation; after an ungraceful exit, leased activity converges to zero within the default 60-second lease plus one Prometheus scrape while raw claims may remain cached. /obs agents is local current-process child state. Constant lines mirror the depth=5 and fan-out=20 alert thresholds.",
       "fieldConfig": {
         "defaults": {
           "color": {
@@ -1083,7 +1083,7 @@
             "uid": "prometheus"
           },
           "editorMode": "code",
-          "expr": "sum(observme_active_agents) by (agent_role)",
+          "expr": "sum by (agent_role) (max by (observme_instance_id, agent_role) ((observme_active_agents > 0) and on (observme_instance_id) ((observme_agent_lease_expires_unixtime_seconds > time()) and (observme_agent_lease_expires_unixtime_seconds <= time() + 305)))) or on() vector(0)",
           "legendFormat": "active {{agent_role}}",
           "range": true,
           "refId": "A"

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
@@ -647,27 +648,35 @@ histogram_quantile(0.95, sum(rate(observme_subagent_spawn_duration_ms_bucket[$__
 
 ```text
 observme_active_agents
+observme_agent_lease_expires_unixtime_seconds
 observme_agent_tree_depth
 observme_agent_tree_width
 observme_agent_fanout_count
 ```
 
-Expected labels:
-
-```text
-agent_role
-subagent_depth
-```
+The active claim and lease carry the bounded `agent_role` and `environment` dimensions plus generated resource-instance identity normalized by the Collector to `observme_instance_id`. They do not currently carry `subagent_depth`; never derive a replacement depth label from workflow, session, logical-agent, trace, span, or job-run IDs. The tree histograms retain their documented bounded tree dimensions.
 
 Dashboard examples:
 
 ```promql
-sum(observme_active_agents) by (agent_role, subagent_depth)
+sum by (agent_role) (
+  max by (observme_instance_id, agent_role) (
+    (observme_active_agents > 0)
+    and on (observme_instance_id)
+    (
+      (observme_agent_lease_expires_unixtime_seconds > time())
+      and
+      (observme_agent_lease_expires_unixtime_seconds <= time() + 305)
+    )
+  )
+) or on() vector(0)
 histogram_quantile(0.95, sum(rate(observme_agent_tree_depth_bucket[$__rate_interval])) by (subagent_depth, le))
 histogram_quantile(0.95, sum(rate(observme_agent_tree_width_bucket[$__rate_interval])) by (subagent_depth, le))
 histogram_quantile(0.95, sum(rate(observme_agent_fanout_count_bucket[$__rate_interval])) by (subagent_depth, le))
 ```
 
+Use the canonical total, role, environment, diagnostics, and migration guidance in [`reference/09-dashboards-alerts-slos.md` §1.3](reference/09-dashboards-alerts-slos.md#13-active-agent-leased-state-contract); raw active-claim sums are not current-liveness queries after ungraceful termination.
+
 ### Lineage health metrics
 
 ```text
@@ -825,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,8 +1,14 @@
 # ObservMe Compatibility Matrix
 
-Last updated: 2026-07-07
+Last updated: 2026-07-14
 
-This matrix records the ObservMe runtime and observability-stack versions that have been exercised or pinned for the current release line. A row marked **validated** has been covered by a named local or CI validation command. A row marked **pinned, pending integration** is present in the reference configuration but must be promoted to validated after the integration tests in tasks 48-50 exercise it.
+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 0.1.x supports `@earendil-works/pi-coding-agent` `>=0.80.5 <0.81.0`. The Pi-mandated core package peers remain in `peerDependencies` with `"*"`, while release development dependencies are pinned exactly to 0.80.6 and CI installs both the 0.80.5 minimum and the 0.80.6 release-resolved target explicitly. Extension startup checks Pi's exported `VERSION` and required APIs before registering any handler or command.
+
+The 0.80.5 minimum is evidence-based: its exported extension contract includes `session_info_changed`, which ObservMe requires for live rename metadata; 0.80.2 does not. 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.
 
 ## Validation record
 
@@ -12,12 +18,23 @@ This matrix records the ObservMe runtime and observability-stack versions that h
 | 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 (configured 2026-07-14) | GitHub Actions `ubuntu-latest`, Node.js 22.19.0; exact Pi 0.80.5 and 0.80.6 matrix targets | Exact Pi install, version assertion, then `npm run validate:pi-compatibility` | Compile-time event fixtures, compatibility diagnostics, package install, handler/lifecycle smoke, and a real Pi RPC runtime are exercised separately at the declared minimum and release-resolved 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, compatibility diagnostics, packaged install, handler/lifecycle smoke, and real Pi RPC runtime at the declared minimum. |
+| 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 release-resolved version. |
+| 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. |
+| 2026-07-14 | Local Docker 29.5.2, Collector Contrib 0.104.0, Prometheus 2.53.1 | `npm run test:integration:active-agent-lease` | Passed clean shutdown, `SIGTERM`, and cancellation-oriented `SIGKILL`; the raw claim remained cached while leased activity converged without Collector restart. Labeled containers and the network were absent after cleanup. |
+| 2026-07-14 | Local Docker 29.5.2 with the pinned Grafana stack | `npm run test:integration:grafana-stack` | Unrelated pre-existing broad-stack blocker remains: this run timed out with an empty Prometheus total-token vector. That token path does not validate active-agent leases. Cleanup removed all integration containers and networks; focused lease evidence is unaffected. |
+| 2026-07-14 | npm package dry run for `@senad-d/observme` 0.1.3 | `npm run pack:dry-run` | Passed with 124 files; metric source, dashboards, alerts, examples, target docs, and `skills/observme-docs/SKILL.md` were present. |
+
+Active-agent lease interpretation additionally requires producer and Prometheus wall clocks to remain within 5 seconds. GitHub-hosted runners satisfy this expectation. Self-hosted runners are supported only with reliable NTP or equivalent synchronization; clock health must be monitored separately from the ObservMe version matrix.
 
 ## Runtime and library matrix
 
 | 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 | Supported: `@earendil-works/pi-coding-agent` >=0.80.5 <0.81.0; release-resolved `@earendil-works/pi-coding-agent` 0.80.6 and `@earendil-works/pi-ai` 0.80.6 | `package.json` `observmeCompatibility`, exact dev dependencies, `package-lock.json`, `.github/workflows/ci.yml` | Validated locally at minimum and release-resolved versions; exact CI matrix configured | `npm run validate:pi-compatibility` typechecks exported event contracts, tests pre-registration diagnostics, installs the package, runs handler/lifecycle smoke, and launches the real Pi RPC runtime. |
 | 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`. |
 
@@ -33,7 +50,7 @@ This matrix records the ObservMe runtime and observability-stack versions that h
 
 ## 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,15 @@ 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.
 
 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.
 
@@ -45,3 +48,5 @@ Invalid or unsafe merged configuration falls back to safe defaults. `/obs status
 - [Example configurations](../examples/README.md)
 - [Security, privacy, and redaction](reference/06-security-privacy-redaction.md)
 - [Grafana and `/obs` validation flow](validation-flow.md)
+- [Canonical active-agent queries and raw-query migration](reference/09-dashboards-alerts-slos.md#131-canonical-active-agent-promql)
+- [Active-lease deployment and troubleshooting runbook](reference/11-deployment-runbooks.md)

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

@@ -503,9 +503,46 @@ observme_handler_duration_ms
 
 ```text
 observme_active_spans
-observme_active_agents
+observme_active_agents                              # compatibility lifecycle claim
+observme_agent_lease_expires_unixtime_seconds      # asynchronous gauge, unit s
 ```
 
+#### 12.4.1 Active-agent lease and clock contract
+
+This section is the single source of truth for active-agent lease constants and semantics. Runtime configuration, metric metadata, PromQL, dashboards, alerts, examples, and tests must reference these values rather than define different local windows.
+
+| Contract item | Required value |
+|---|---|
+| Lease metric | `observme_agent_lease_expires_unixtime_seconds` |
+| OTel instrument and unit | Asynchronous gauge, unit `s` |
+| Observation value | `(wallClockUnixMillis + metrics.activeAgentLeaseDurationMillis) / 1000`; fractional Unix seconds are valid |
+| Configuration | `metrics.activeAgentLeaseDurationMillis`; `OBSERVME_ACTIVE_AGENT_LEASE_DURATION_MS` is its environment override |
+| Default lease | `60000` ms (60 seconds) |
+| Inclusive duration bounds | `10000` ms through `300000` ms (10 seconds through 5 minutes) |
+| Export relationship | Lease duration must be at least `(2 * metrics.exportIntervalMillis) + 5000` ms |
+| Supported wall-clock skew | Producer and Prometheus clocks must differ by no more than 5 seconds |
+| Future-timestamp horizon | A lease later than `time() + 305` seconds is pathological and must not count active |
+
+`observme_active_agents` remains the clean lifecycle claim. An agent is operationally active only when its claim is positive and the matching lease is finite, later than Prometheus `time()`, and no later than the future-timestamp horizon. Missing, expired, malformed, non-finite, or pathologically future leases fail closed. Lease renewal occurs once per SDK metric collection while the session is active, including otherwise idle sessions; it does not depend on turns, tool calls, or a background heartbeat timer.
+
+On clean shutdown, deactivate the lease before the final metric force-flush and record the matching `observme_active_agents` decrement. This makes the leased result zero after normal export/scrape propagation without waiting for expiry. If shutdown telemetry cannot run, the last exported lease is allowed to expire. With synchronized clocks, an ungraceful exit converges to zero within the configured lease plus one Prometheus scrape/evaluation interval. Across the full supported positive-skew budget, the measurable worst-case bound is the configured lease plus 5 seconds plus one scrape/evaluation interval; for the defaults and a 15-second scrape interval, that is at most 80 seconds.
+
+The only per-runtime Prometheus join and deduplication key is the Collector-normalized `observme_instance_id` resource label. ObservMe generates its UUID independently for each telemetry session and never derives it from prompts, responses, content, paths, commands, GitHub run IDs, sessions, workflows, or logical agents. `service.instance.id` may carry the same resource value for OTel interoperability, but active-agent PromQL joins on `observme_instance_id` and deduplicates repeated exporter/scrape representations with `max by (observme_instance_id)`. The lease observation itself may carry only existing bounded metric labels; the instance identity comes from resource-to-metric conversion and must not become a dashboard variable or legend.
+
+Lifecycle and failure behavior is fixed as follows:
+
+| Condition | Required leased-active behavior |
+|---|---|
+| Clean exit | Deactivate before final flush; the active claim becomes zero without waiting for lease expiry. |
+| `SIGTERM` | Use the clean path when Pi delivers shutdown; otherwise use the same expiry behavior as an abrupt exit. |
+| Crash, `SIGKILL`, cancelled GitHub job, or runner/power loss | No cleanup is required for correctness; the last lease expires within the documented convergence bound. |
+| Duplicate session start, reload, or resume | Deactivate and flush the replaced session before activating its replacement. If replacement cleanup is interrupted, the old instance lease expires independently. |
+| Startup failure or partial runtime construction | Never leave an activated observable callback; dispose any registered callback. |
+| Collector or OTLP outage | Cached positive claims stop counting when their last delivered leases expire. A still-running producer becomes active again after export recovers and a fresh lease arrives. Backend unavailability itself remains an unknown/no-query state. |
+| Clock skew or clock movement | A producer clock ahead can delay expiry and one behind can fail closed early. Clocks outside the supported skew are unsupported; non-finite observations are omitted and values beyond the future horizon do not count. GitHub-hosted runners satisfy the synchronized-clock expectation; self-hosted runners must use reliable time synchronization. |
+
+A renewable lease is a bounded liveness signal, not proof that the operating-system process is reachable at the exact query instant. `observme_active_agents` remains emitted with its existing name and clean-lifecycle behavior for compatibility, so the change is additive under the semantic-convention versioning policy and does not require a major convention-version increment. Consumers that need crash-safe live counts must migrate from raw active-claim sums to the leased definition.
+
 ### 12.5 Lifecycle recording points
 
 - Record `observme_tool_result_size_chars` once from the finalized `tool_execution_end` result, using the same bounded tool labels as tool-call metrics.
@@ -665,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/05-otel-pipeline-and-collector.md

@@ -47,6 +47,7 @@ metrics:
   enabled: true
   exportIntervalMillis: 15000
   exportTimeoutMillis: 3000
+  activeAgentLeaseDurationMillis: 60000
 
 logs:
   enabled: true
@@ -58,6 +59,8 @@ logs:
 
 The OpenTelemetry JS OTLP HTTP exporters default to signal-specific paths such as `http://localhost:4318/v1/traces`, `http://localhost:4318/v1/metrics`, and `/v1/logs`. Treat `otlp.endpoint` as a base endpoint in ObservMe config, but pass signal-specific URLs to SDK exporters that require an explicit `url`.
 
+The default active-agent lease is 60 seconds and renews on each 15-second metric collection. Supported lease values are 10 seconds through 5 minutes and must be at least twice the export interval plus 5 seconds. Keep the producer and Prometheus clocks within 5 seconds; otherwise a lease may fail closed early or remain valid longer than intended. The exact contract is frozen in [`04-telemetry-semantic-conventions.md` §12.4.1](04-telemetry-semantic-conventions.md#1241-active-agent-lease-and-clock-contract).
+
 ## 4. Trace Context and Workflow/Agent-Lineage Propagation
 
 When ObservMe launches or wraps a subagent process, the parent runtime should propagate both standard trace context and ObservMe-specific lineage:
@@ -118,10 +121,10 @@ service:
 
 ## 6. Production Collector for Grafana Stack
 
-This configuration routes traces to Tempo, logs to Loki, and metrics to a Prometheus-compatible remote write endpoint such as Mimir. Use a Collector distribution that contains every configured component. The minimal debug example works with the core Collector, while `prometheusremotewrite`, `probabilistic_sampler`, and `tail_sampling` are commonly deployed from the Collector Contrib distribution or a vendor distribution such as Grafana Alloy.
+This configuration routes traces to Tempo, logs to Loki, and metrics to a Prometheus scrape endpoint. Use a Collector distribution that contains every configured component. The minimal debug example works with the core Collector, while `prometheus`, `prometheusremotewrite`, `probabilistic_sampler`, and `tail_sampling` are commonly deployed from the Collector Contrib distribution or a vendor distribution such as Grafana Alloy.
 
 ```yaml
-# Production-oriented Collector reference for Tempo, Loki, and Mimir.
+# Production-oriented Collector reference for Tempo, Loki, and Prometheus.
 # Verify that your Collector distribution contains every configured component,
 # replace backend endpoints/security for your deployment, and never add raw
 # content or high-cardinality execution identifiers to metric labels.
@@ -220,14 +223,14 @@ exporters:
     retry_on_failure:
       enabled: true
 
-  prometheusremotewrite/mimir:
-    endpoint: http://mimir:9009/api/v1/push
+  prometheus:
+    endpoint: 0.0.0.0:8889
+    # Exporter-wide stale-series/cardinality cleanup for gauges, counters, and
+    # histograms. Five minutes exceeds ObservMe's default one-minute active-agent
+    # lease; lease-aware PromQL, not expiration, determines liveness.
+    metric_expiration: 5m
     resource_to_telemetry_conversion:
       enabled: true
-    sending_queue:
-      enabled: true
-    retry_on_failure:
-      enabled: true
 
   debug:
     verbosity: basic
@@ -243,7 +246,7 @@ service:
     metrics:
       receivers: [otlp]
       processors: [memory_limiter, resource/observme, resource/drop_high_cardinality_metric_attrs, batch]
-      exporters: [prometheusremotewrite/mimir]
+      exporters: [prometheus]
 
     logs:
       receivers: [otlp]
@@ -251,9 +254,19 @@ service:
       exporters: [otlphttp/loki]
 ```
 
+### 6.1 Prometheus exporter expiration policy
+
+The shipped local and production scrape-exporter examples set `metric_expiration: 5m`. This exporter-level setting applies uniformly to every Prometheus-exported gauge, counter, and histogram; it cannot be scoped only to active-agent metrics. Its only purpose is stale-series and cardinality cleanup: it bounds the Collector memory used by abandoned metric streams and eventually lets Prometheus mark an expired series stale after the exporter stops exposing it. Lease-aware PromQL remains the active-agent correctness mechanism, even while the Collector still exposes a cached positive `observme_active_agents` value.
+
+Five minutes comfortably exceeds the default 60-second active-agent lease and 15-second SDK metric export interval. If either interval is customized, keep `metric_expiration` longer than the lease and allow enough additional time for expected export delays and scrape gaps. A shorter value cleans abandoned streams sooner but can evict gauges, counters, and histograms during a temporary producer outage; a longer value consumes Collector memory and preserves abandoned cardinality for longer. It must never be shortened merely to make active-agent totals converge.
+
+Apply a Collector configuration change through the deployment's supported reload mechanism or restart the Collector. A restart clears the Prometheus exporter's in-memory series cache, but neither reload nor restart deletes samples already stored in Prometheus; historical samples remain subject to Prometheus retention and deletion policy. Restart is never required merely to make an expired active-agent lease stop counting. `metric_expiration` belongs only to the metrics scrape exporter, so traces and logs are unaffected. Remote-write deployments do not use this scrape-exporter cache setting and must apply their backend's series-retention policy, while continuing to use the same lease-aware active-agent queries.
+
+When migrating, deploy a version that emits `observme_agent_lease_expires_unixtime_seconds`, verify the Collector preserves the generated `observme_instance_id`, then replace every current-activity raw sum in dashboards, recording rules, and alerts with the canonical queries in [`09-dashboards-alerts-slos.md` §1.3.1](09-dashboards-alerts-slos.md#131-canonical-active-agent-promql). Keep raw and expired claims only as clearly labeled diagnostics. Missing leases intentionally fail closed, so do not switch a mixed-version fleet until the lease metric is visible for the producers that should count.
+
 The Collector attribute processor is defense in depth for log attributes only. It must not be the only redaction layer, and it does not sanitize arbitrary log bodies; ObservMe must redact or drop sensitive content before export. The traces pipeline intentionally keeps `pi.llm.prompt.redacted`, `pi.llm.response.redacted`, and `pi.llm.thinking.redacted` so Tempo can display redacted content after explicit capture is enabled. Old telemetry that an earlier Collector dropped cannot be recovered; generate new LLM events after updating the Collector.
 
-Keep high-cardinality lineage attributes on traces/logs, but remove them from the metrics pipeline unless the organization explicitly accepts the cardinality. The bundled local Loki pipeline promotes `pi.agent.id` and `pi.agent.run.id` as log labels so the LLM Conversations dashboard can filter captured chat content by agent and run. Prometheus resource-to-telemetry conversion is safe only after the metrics pipeline drops `pi.workflow.id`, `pi.agent.id`, `pi.session.id`, trace IDs, and spawn IDs; the remaining generated `service.instance.id`/`observme.instance.id` labels keep concurrent ObservMe metric streams distinct so session counters can be summed accurately.
+Keep high-cardinality lineage attributes on traces/logs, but remove them from the metrics pipeline unless the organization explicitly accepts the cardinality. The bundled local Loki pipeline promotes `pi.agent.id` and `pi.agent.run.id` as log labels so the LLM Conversations dashboard can filter captured chat content by agent and run. Prometheus resource-to-telemetry conversion is safe only after the metrics pipeline drops `pi.workflow.id`, `pi.agent.id`, `pi.session.id`, trace IDs, and spawn IDs. Preserve the generated `service.instance.id`/`observme.instance.id` resource identity in the metrics pipeline so lease-aware queries can join and deduplicate concurrent ObservMe metric streams without exposing workflow, session, logical-agent, trace, span, or job-run identifiers as labels.
 
 ## 7. Direct-to-Backend Development Mode
 

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.