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.

9.9 KiB Raw Blame History