kandev/docs/plans/executor-model-mismatch-fallback/task-02-persist-model-warning.md

id, title, status, wave, depends_on, plan, spec

id	title	status	wave	depends_on	plan	spec
02-persist-model-warning	Persist model-selection warnings	done	2	01-executor-model-decision	plan.md	../../specs/agents/requirements/no-silent-model-fallback.md

Task 02: Persist model-selection warnings

Acceptance

• Every default or explicit fallback emits structured requested, effective, agent, executor, and reason data.
• The orchestrator persists one warning status message for each session-start decision, and reload hydration returns it.
• Event replay or message failure does not create duplicates or stop the task launch.

TDD scenarios

1. RED: Add lifecycle event tests for explicit fallback, provider default, unknown effective model, and unsupported selection.
2. RED: Add orchestrator tests for status metadata, idempotency, replay, and persistence errors.
3. RED: Add gateway tests for the provider-neutral live event and old-event compatibility.
4. GREEN: Generalize the lifecycle event and persist the semantic warning message.
5. REFACTOR: Keep the event payload, stored metadata, and WebSocket payload on one shared shape.

Verification

• cd apps/backend && go test -tags fts5 -run 'Test.*ModelSelectionWarning|Test.*ModelFallback' ./internal/agent/runtime/lifecycle ./internal/orchestrator ./internal/gateway/websocket
• cd apps/backend && go test -tags fts5 ./internal/orchestrator ./internal/gateway/websocket
• git diff --check

Files likely touched

• apps/backend/internal/agentctl/types/streams/agent.go
• apps/backend/internal/agent/runtime/lifecycle/event_types.go
• apps/backend/internal/agent/runtime/lifecycle/events.go
• apps/backend/internal/agent/runtime/lifecycle/session.go
• apps/backend/internal/events/types.go
• apps/backend/internal/orchestrator/event_handlers_streaming.go
• apps/backend/internal/orchestrator/event_handlers_streaming_test.go
• apps/backend/internal/orchestrator/service.go
• apps/backend/internal/gateway/websocket/session_notifications.go
• apps/backend/internal/gateway/websocket/session_notifications_test.go
• apps/backend/pkg/websocket/actions.go

Dependencies

• Task 01 supplies the typed model decision.

Parallelism

Sequential after Task 01. This task defines the persisted and live warning contracts.

Inputs

• The typed decision from Task 01.
• The current session_model_fallback event.
• The existing CreateSessionMessage warning path.
• The existing task message repository and hydration flow.

Output contract

Report the event shape, message metadata, idempotency method, RED evidence, GREEN evidence, and test results.

Risks

• The lifecycle event can arrive before the session identity is linked.
• A blank turn ID must use the existing session-status message convention.
• Compatibility consumers can still depend on session.model_fallback.

Results

Implemented structured warning events, idempotent best-effort persistence, provider-neutral WebSocket notification, and durable metadata hydration. The orchestrator and gateway suites passed with 2,270 tests; the combined backend targeted suite passed with 7,299 tests.