Files
kandev/docs/plans/backend-failure-containment/task-03-surface-runtime-failure.md
T
2026-08-24 11:09:03 +00:00

115 lines
4.8 KiB
Markdown

---
id: "03-surface-runtime-failure"
title: "Surface runtime failure and recovery"
status: done
wave: 2
depends_on: ["02-publish-agent-runtime-availability"]
plan: "plan.md"
spec: "../../specs/platform/requirements/agent-runtime-availability.md"
---
# Task 03: Surface runtime failure and recovery
## Intent
Hydrate the backend-owned runtime snapshot and show a persistent, accessible
shell-level explanation with the supported Kandev restart path.
## Acceptance
- Zustand hydrates and replaces the full `agentRuntime` snapshot from boot and
`system.agent_runtime.status_changed` without modifying domain data.
- One non-dismissible `role="alert"` renders for unavailable state on every
authenticated route, including when the App status bar feature is disabled.
- Copy explains the local runtime impact, saved-data safety, and required full
restart without exposing raw diagnostics.
- Supported supervisors show a working **Restart Kandev** action and existing
restart progress flow; unsupported or failed capability lookup shows localized
manual guidance.
- Restart request errors leave the alert mounted and readable.
- A new available snapshot removes the alert; browser connection changes alone
do not.
- All new user-visible copy is localized in every shipped locale.
## TDD sequence
1. Add store/hydration and system-event handler tests for unavailable, available,
and unrelated reconnect updates; confirm RED before the state contract exists.
2. Add alert/provider tests with the App status bar disabled, retained route
children, supported capability, unsupported capability, restart error, and
recovery; confirm RED before rendering.
3. Implement the type, store state/action, handler, alert, provider placement,
capability selection, restart flow reuse, and translations.
4. Rerun focused tests, typecheck, and i18n checks before refactoring.
## Files likely touched
- `apps/web/lib/types/agent-runtime.ts`
- `apps/web/lib/state/default-state.ts`
- `apps/web/lib/state/store.ts`
- `apps/web/lib/state/store-overrides.ts`
- `apps/web/lib/ws/handlers/system-events.ts`
- `apps/web/lib/ws/handlers/system-events.test.ts`
- `apps/web/components/app-status-bar/agent-runtime-unavailable-alert.tsx`
- `apps/web/components/app-status-bar/agent-runtime-unavailable-alert.test.tsx`
- `apps/web/components/app-status-bar/app-status-surface-provider.tsx`
- `apps/web/components/app-status-bar/app-status-surface-provider.test.tsx`
- `apps/web/src/locales/en/system.json`
- `apps/web/src/locales/pt-pt/system.json`
- `apps/web/src/locales/zh-cn/system.json`
## Dependencies
Task 02's final boot and WebSocket contract.
## Parallelism
`sequential` — this task consumes the backend contract and owns the shared shell
surface used by Task 04.
## Mobile parity
The nearest shell exemplar is the in-flow App status surface, while the nearest
error exemplar is the existing SPA/session recovery alert. Phone composition
stacks copy and action, keeps the action at least 44 px, remains inside the
route/status column, and adds no fixed or bottom surface. Unit tests assert
responsive classes and semantics; Task 04 verifies real viewport geometry.
## Verification
- `cd apps && pnpm --filter @kandev/web test -- --run lib/state lib/ws/handlers/system-events.test.ts components/app-status-bar`
- `cd apps/web && pnpm run typecheck`
- `cd apps/web && pnpm run i18n:check && pnpm run i18n:ratchet`
## Inputs
- Task 02 public snapshot and action.
- Existing `useRestartCapability`, `useKandevRestart`, and
`RestartProgressDialog` behavior.
- App status surface shell geometry and mobile UI language reference.
## Output contract
Record focused unit, typecheck, and i18n results plus the final localized copy
keys and any deliberate change to alert placement.
## Results
Implemented the backend-shaped `agentRuntime` snapshot in the web store,
hydrated it from boot state, and replaced it on the global runtime WebSocket
event without clearing domain state. Added the in-flow localized alert outside
the App status bar feature gate, reusing the existing capability and restart
progress hooks. Supported supervisors expose `Restart Kandev`; capability
lookup failures render manual guidance, and restart errors leave the alert
mounted until an available snapshot arrives.
Focused validation passed:
- `pnpm --filter @kandev/web test -- --run lib/state/store.test.ts lib/ws/handlers/system-events.test.ts components/app-status-bar/agent-runtime-unavailable-alert.test.tsx components/app-status-bar/app-status-surface-provider.test.tsx` — 21 tests passed.
- `pnpm run typecheck` — passed.
- `pnpm run i18n:check && pnpm run i18n:ratchet` — passed; pseudo catalog regenerated and synced.
The alert uses localized English, Portuguese, Chinese, and pseudo-locale
entries, remains in normal shell flow on phone layouts, and keeps its restart
action at the required 44 px minimum.