--- status: active system: platform created: 2026-08-23 updated: 2026-09-05 owners: - kandev --- # Expected runtime log severity Requirements ## Overview Expected runtime conditions and forwarded child logs can use the wrong severity. This behavior obscures actionable errors and makes diagnostic bundles harder to triage. ## Requirements ### REQ-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001: Expected runtime log severity **Intent:** Normal review and first-launch timing conditions currently look like backend failures in the logs. This obscures actionable errors and makes diagnostic bundles harder to triage. #### Acceptance criteria - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.1:** A `workspace.file.get` request for a path that is absent from the current checkout returns the existing `not_found` WebSocket error code and records a debug entry. It does not record an error entry. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.2:** A `workspace.file.get` failure that is not a missing-file condition keeps the existing `internal_error` response and error-level log entry. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.3:** When initial worktree materialization runs before its task environment exists, the typed `ErrEnvironmentNotResolved` condition records a debug entry. The physical worktree remains available and the existing launch transaction still owns persistence of its record. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.4:** Other worktree persistence failures keep their existing return, cleanup, and logging behavior. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.5:** **GIVEN** an active session and an absent current-checkout path, **WHEN** `workspace.file.get` requests that path, **THEN** the response has the `not_found` error code and exactly one debug-level missing-file entry is emitted. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.6:** **GIVEN** an active session and a dependency failure unrelated to a missing file, **WHEN** `workspace.file.get` requests a path, **THEN** the response has the `internal_error` error code and an error-level entry is emitted. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.7:** **GIVEN** a physical worktree has been materialized before its task environment row exists, **WHEN** worktree persistence receives `ErrEnvironmentNotResolved`, **THEN** the call succeeds, emits a debug-level deferred-persistence entry, and does not remove the physical worktree. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.8:** **GIVEN** worktree persistence receives any other store error, **WHEN** the manager handles it, **THEN** the existing error and cleanup behavior remains unchanged. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.9:** The launcher shall preserve a recognized child log level from Zap console records and Go `slog` text records. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.10:** The launcher shall record unrecognized child stderr at warning level so that unstructured panics and tracebacks remain visible. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.11:** A missing task environment referenced by a session shall use the existing task fallback without a warning entry. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.12:** A task-environment lookup error that is not a typed not-found condition shall retain its warning entry. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.13:** **GIVEN** a child emits a recognized `INFO` record, **WHEN** the launcher forwards stderr, **THEN** the parent records the line at info level. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.14:** **GIVEN** a child emits unstructured stderr, **WHEN** the launcher forwards the line, **THEN** the parent records it at warning level. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.15:** **GIVEN** a session references a missing task environment, **WHEN** workspace information is loaded, **THEN** the task fallback succeeds without a warning entry. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.16:** **GIVEN** a task-environment lookup returns another error, **WHEN** workspace information is loaded, **THEN** the existing fallback and warning behavior remains unchanged. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.17:** **GIVEN** an open page detects a changed backend `boot_id`, **WHEN** its recovery report is accepted, **THEN** the backend records one info-level reload entry. It records no `frontend error toast` error entry. - **AC-PLATFORM-EXPECTED-RUNTIME-LOG-SEVERITY-001.18:** **GIVEN** Sonner or the legacy toast provider displays an error toast, **WHEN** its report is accepted, **THEN** the backend records one `frontend error toast` error entry. ## Migrated source detail ## Why Normal review and first-launch timing conditions currently look like backend failures in the logs. This obscures actionable errors and makes diagnostic bundles harder to triage. ## What - A `workspace.file.get` request for a path that is absent from the current checkout returns the existing `not_found` WebSocket error code and records a debug entry. It does not record an error entry. - A `workspace.file.get` failure that is not a missing-file condition keeps the existing `internal_error` response and error-level log entry. - When initial worktree materialization runs before its task environment exists, the typed `ErrEnvironmentNotResolved` condition records a debug entry. The physical worktree remains available and the existing launch transaction still owns persistence of its record. - Other worktree persistence failures keep their existing return, cleanup, and logging behavior. - Forwarded child stderr keeps recognized Zap and Go `slog` levels. Unknown stderr stays at warning level. - A missing session task environment uses the existing task fallback without a warning. Other lookup errors keep their warning. ## API surface The existing `workspace.file.get` WebSocket action keeps its request and response shapes. Only the response classification for a missing current file is made explicit as `not_found`; no new action or payload field is added. The agentctl file-content endpoint carries this classification with HTTP 404 and a typed client sentinel. Other file-content failures keep their existing error status and message path. ## Failure modes - Missing files are expected during deleted-file review and stale diff requests. They are handled as not-found results and are not promoted to application failures. - Permission, transport, malformed-response, and other non-missing failures remain internal errors and continue to be logged at error level. - A worktree store that reports `ErrEnvironmentNotResolved` is a normal launch ordering condition. The manager skips that persistence attempt and does not remove the newly created physical worktree. - Any other worktree store failure remains an actual persistence failure and follows the current cleanup and retry boundary. - The launcher accepts only anchored child log formats. Unrecognized stderr remains visible at warning level. - A typed missing task environment is an expected stale-reference condition. The task fallback remains authoritative for workspace information. - Other task-environment lookup errors can indicate a storage problem and remain warnings. - A changed backend generation is an expected lifecycle condition. Its browser report remains diagnostic evidence, but it is not an error-toast report. - Actual error toasts keep their error-level records. ## Persistence guarantees This repair changes log severity and missing-file classification only. The agentctl file-content transport now distinguishes missing files with HTTP 404; it does not change task-environment ownership, worktree creation, launch persistence, or cleanup behavior across backend restarts. ## Scenarios - **GIVEN** an active session and an absent current-checkout path, **WHEN** `workspace.file.get` requests that path, **THEN** the response has the `not_found` error code and exactly one debug-level missing-file entry is emitted. - **GIVEN** an active session and a dependency failure unrelated to a missing file, **WHEN** `workspace.file.get` requests a path, **THEN** the response has the `internal_error` error code and an error-level entry is emitted. - **GIVEN** a physical worktree has been materialized before its task environment row exists, **WHEN** worktree persistence receives `ErrEnvironmentNotResolved`, **THEN** the call succeeds, emits a debug-level deferred-persistence entry, and does not remove the physical worktree. - **GIVEN** worktree persistence receives any other store error, **WHEN** the manager handles it, **THEN** the existing error and cleanup behavior remains unchanged. - **GIVEN** a child emits a recognized `INFO` record, **WHEN** the launcher forwards stderr, **THEN** the parent records the line at info level. - **GIVEN** a child emits unstructured stderr, **WHEN** the launcher forwards the line, **THEN** the parent records it at warning level. - **GIVEN** a session references a missing task environment, **WHEN** workspace information is loaded, **THEN** the task fallback succeeds without a warning entry. - **GIVEN** a task-environment lookup returns another error, **WHEN** workspace information is loaded, **THEN** the existing fallback and warning behavior remains unchanged. - **GIVEN** an open page detects a changed backend `boot_id`, **WHEN** its recovery report is accepted, **THEN** one info entry records the event and no `frontend error toast` error entry is emitted. - **GIVEN** an actual error toast is displayed, **WHEN** its report is accepted, **THEN** the existing `frontend error toast` error entry remains unchanged. ## Out of scope - Changing frontend diff rendering or review-file status behavior. - Changing worktree ownership, task-environment transactions, cleanup policy, or startup reconciliation. - Reclassifying integration failures, raw ACP frames, host-utility idle repair, network disconnects, or authentication warnings. - Changing backend-restart detection, the reload-required state, or the reload alert.