feat(opencode): publish structured native-driver diagnostics

[schickling-assistant]

Problem

Managed OpenCode native delivery can fail at version, API, SSE/seed, submission, or read-back boundaries. st2 currently exposes many failures only on stderr, so Fractal/Doctor cannot explain why native delivery or exact observation is unavailable, and telemetry cannot measure recovery.

Goal

Publish one typed current driver diagnostic with stable bounded vocabulary, stage-local recovery, roster/Doctor exposure, and privacy/cardinality-safe telemetry—without changing OpenCode delivery/retry/archive behavior or introducing launcher vocabulary.

Design

Durable per-agent record:

{
  "schema":"st2.driver-diagnostic.v1",
  "driver":"opencode",
  "stage":"versionGate|apiGate|sse|seed|delivery|readBack",
  "reason":"<closed enum>",
  "source":"<closed enum>",
  "support":"supported|unsupported|unknown",
  "observedAt":1787830000000,
  "recovery":"clearsOnStageRecovery"
}

• additive fields tolerated; malformed/unknown/future-skew records become visible indeterminate
• same tuple deduplicates
• recovery clears only its stage, revealing the next earliest failure; final recovery removes the file
• roster adds driverDiagnostic; Doctor emits actionable advisory
• telemetry span/event + driver_diagnostic_transitions_total uses only bounded stage/reason/source/support/outcome axes
• raw version and correlation IDs are span/log-only; no identities, paths, prompts, message bodies, filenames, or IDs in metric labels/span.label

Verification

• Diagnostic core/wire/cardinality: 5 tests green.
• OpenCode fake-server suite: 25 tests green.
• Roster: 4 tests green.
• Doctor structured agreement/recovery: green.
• nix build .#default --no-link: green (/nix/store/nmk0d7lcyqfg992qybq36vnb4kn4apsx-st2-0.1.0).
• Strict VRS reports only existing baseline malformed records; no new diagnostic artifact errors.

Complexity

One generic typed diagnostic core plus OpenCode boundary adapters. The generic reader/telemetry does not branch on Axe or launcher identity. Delivery state machine is unchanged.

Concerns

The current reason vocabulary is intentionally closed. New provider failure classes must extend schema/tests deliberately rather than leak error strings. Raw producer version remains roster/drawer data but is excluded from metric labels.

References

• Dependency for schickling/dotfiles#2090
• Decisions q10/q11/q12 in downstream decision tree

Posted on behalf of @schickling

field	value
agent_identity	unknown
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	OMP
agent_tool_version	18.0.3
agent_runtime	OMP 18.0.3
tooling_profile	dotfiles@e4789b0