Carlos Florêncio
81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
---
|
|
status: building
|
|
created: 2026-08-23
|
|
owner: kandev
|
|
---
|
|
|
|
# Expected runtime log severity
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## Out of scope
|
|
|
|
- Changing frontend diff rendering or review-file status behavior.
|
|
- Changing worktree ownership, task-environment transactions, cleanup policy,
|
|
or startup reconciliation.
|
|
- Reclassifying unrelated integration, ACP, or startup warnings.
|