Make agent containers discoverable and publish telemetry snapshot examples #239

Parent

Agent-side change from the map Agent fleet dashboard: map; the consolidated list is in the resolution of Define the dashboard project. The snapshot shape is decided in Define the telemetry snapshot contract and the command mechanics in Decide the agentctl telemetry command. Terms: Telemetry snapshot and Figure basis in CONTEXT.md; ADR 0006.

What to build

Every container built from the agent image becomes discoverable by a dashboard without operator configuration, and the repository publishes the telemetry snapshot contract (schema v1) with synthetic example snapshots. A dashboard can then build and test against the contract before the agent serves telemetry.

Acceptance criteria

• The image carries the label io.github.lbacik.simple-coding-agent.role="agent" (set in the image, not in compose), visible with docker inspect on any container built from it.
• Repository documentation describes telemetry snapshot schema v1 as decided: top-level fields, the figure object (value + basis, with basis one of measured, estimated, configured, sdk_assumed, unavailable; unavailable always has value: null and may carry reason), "missing field = unavailable" vs "null section = not applicable", the versioning rules (integer major; additive changes do not bump), the stable fields, the 256 KiB cap with trimming and truncated, and the agentctl telemetry --json outputs (bare snapshot on success; {"ok": false, "error": {"code", "message"}} on stdout with codes agent_unreachable, unsupported_operation, snapshot_failed and their exit codes).
• Synthetic example snapshots, each a valid JSON file, cover: an idle agent with no attempt but a last finished attempt; an attempt in progress with a partly estimated budget and running subagents; soft threshold crossed with handoff in progress; a recovery hold with its next action; a truncated snapshot. Example error replies cover each of the three error codes.
• Examples are synthetic: no data captured from live instances (the dashboard repository is public and copies them).
• A test parses every example and checks the stable fields (schema_version, generated_at, identity.repository, identity.agent_version) and that every figure object has value: null exactly when its basis is unavailable.
• Operator onboarding docs mention the discovery label.

Blocked by

• None (can start immediately)