# Autonomous Runtime Continuity Note

This file is a compaction guard only. Repository and Runtime state remain authoritative. If this note conflicts with runtime state, chunk files, registries, or user messages after this file was written, use the newer authoritative state.

## Current Operating Mode

- Main role: Orchestrator coordinates the package; Developer/QA/other roles execute through registered work context.
- Autopilot/autonomous mode is the expected default: continue through the active backlog until all chunks are done unless a chunk-specific stop condition, user stop condition, or unresolved safety/authority boundary is reached.
- Manual "ready for review" naming is a mode-sensitive checkpoint, not an automatic stop in autonomous mode.
- Approval requests are not needed in autonomous mode unless a protected close/commit boundary requires them, but completion, summary, approval-state, and commit notifications remain mandatory where the Runtime process requires notifications.
- Do not start a new chunk after the user has explicitly said to stop after close/commit.

## Work Registration And Visibility

- There must be one Runtime work-registration model only. Do not create a second work store.
- Meaningful work must be registered through existing Runtime work sessions/steps/history/journal/projection APIs.
- Read-only commands such as `find`/inspection do not need denial, but they must still register or heartbeat enough work context to answer "who is working and where in orchestration are we?"
- Direct hosted/unified `exec_command` may not invoke project-local Codex hooks in the current runner. This is a known gap to document and test, not to hide.
- Project hook bridge must be verified directly:
  - `.codex/hooks.json` parses.
  - `PreToolUse` with a read-only `find` payload invokes `ai/commands/codex-hook.mjs --codex-stdin PreToolUse`.
  - It reaches the existing Runtime codex-hook adapter and registers/heartbeats visible Codex diagnosis work.
  - `PermissionRequest` returns deterministic allow/deny JSON.
  - Unsupported hosted/unified-exec gaps remain recorded in CFD/work-registration policy.
- Work-status browser proof must cover parent Orchestrator/Developer work, per-tool Codex/read-only work, validation wrapper work, QA work, and restart/recovery wrapper work. Active work must remain visible while active or fail with an explicit registration/projection violation.

## Connection/Recovery State Requirements

- Keep independent domains separate:
  - socket transport
  - backend GraphQL/API health
  - frontend dev-server reachability
  - Runtime API/service health
  - stale snapshot/cursor state
  - auth/session state
  - Runtime work session visibility
- Socket.IO is invalidation-only. Socket reconnect may accelerate checks but cannot by itself clear backend/frontend/runtime service failures.
- Domain recovery must be verified by the domain-specific probe:
  - backend restored by backend/GraphQL health query success
  - frontend restored by frontend reachability check
  - Runtime restored by Runtime API/health path
  - socket restored only clears socket degraded state
- Root-cause display precedence:
  - planned restart beats generic socket/service-unavailable noise until verified recovery or timeout
  - service failure beats generic unavailable
  - frontend+backend simultaneous outage has explicit combined display
  - one service returning while another remains failed displays the remaining single failure
  - recovery complete clears only the matching active root cause
  - repeated recovery evidence is idempotent
  - stale snapshots must not overwrite newer message/toast data
  - socket-only recovery cannot clear backend/frontend/runtime failure
- Planned restart/recovery states hold the known root cause for the expected window; generic downstream socket loss is suppressed until timeout or verified recovery.
- Recovery/restored toast should be state-tied and clear after stable verified recovery, currently expected around 3 seconds. It must not stick indefinitely or mask later failures.
- Toast details should render one line per field, no duplicate label/value rows:
  - `Service: runtime_api...`
  - `Summary: ...`
  - `Event: ...`
  - `Request: ...`
- Toast titles should use Title Case.

## Required Test Shape For Current Chunk 000274

- First prove frontend state mechanism in isolation.
- Then run combined backend-to-frontend browser proof end to end.
- The clean browser run must include:
  - planned restart
  - unplanned frontend/backend/runtime/service failure/recovery where supported
  - socket loss/reconnect handling
  - frontend/backend dual-failure display and clearing
  - recovery toast clearing
  - Runtime work status visibility at the same time
  - hard reload pickup when services are available
- If a run fails, fix the current failure and rerun until there is one complete clean pass from start to finish.
- Mocked/frontend-only state tests are acceptable before full round trip to prove the state machine and toast behavior.

## QA/Research Gate Expectations

- For state machines, reconnect, recovery, scheduling, queues, retries/backoff, circuit breakers, validation runners, watchdogs, journal consumers, auth/session/device registration, UI live-state coordination, and notification/toast root-cause state, do a short research/design checkpoint before implementation.
- Fast-learn/fast-fail should not default to narrowing. If future chunks depend on the mechanism, research and decide whether closing the whole gap now is straightforward and bounded.
- Stop only when research cannot determine a clear path forward because viable solutions are absent or success is ambiguous, or when the change requires an unbounded architecture rewrite.
- QA must run before offering close/commit except for explicit, documented exceptions.
- QA for stateful/live UI/service chunks cannot pass with summary validation only. It needs required evidence from the QA Test Requirement Resolver.

## Known CFDs / Carry-Forward Topics

- Work visibility gaps: hosted direct commands may not invoke hooks; short hook pulses disappear while the turn persists; log/event sidecar may be needed if official hooks cannot cover `unified_exec`.
- Activation gap: backlog-to-active mover still uses guarded legacy shell facade while executor transition does not allow Backlog -> Active.
- Compaction/autopilot gap: compaction must not lose autonomous continuation command.
- Active step semantics and obsolete schema/wiring need review.
- Web console sometimes pastes commands multiple times.
- QA extension should cover planned and randomized end-to-end testing, frontend mocked state-machine proof before full-system proof, and one clean end-to-end run.