Carlos Florêncio
92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
---
|
|
spec: docs/specs/platform/requirements/expected-runtime-log-severity.md
|
|
created: 2026-08-23
|
|
status: implemented
|
|
---
|
|
|
|
# Implementation Plan: Expected runtime log severity
|
|
|
|
## Overview
|
|
|
|
Classify two confirmed normal conditions at their correct severity. First,
|
|
workspace file reads will expose missing current-checkout paths as `NotFound`
|
|
and debug evidence. Second, initial worktree persistence that races task
|
|
environment creation will remain successful but emit debug evidence instead of
|
|
a warning. Non-missing file failures and non-environment worktree failures keep
|
|
their existing behavior.
|
|
|
|
## Backend
|
|
|
|
### Workspace file content classification
|
|
|
|
- Preserve the server-side `fs.ErrNotExist` distinction in
|
|
`apps/backend/internal/agentctl/server/process/workspace_files.go` and carry
|
|
it across the agentctl HTTP boundary as HTTP 404.
|
|
- Map that status to a typed client sentinel, then have
|
|
`apps/backend/internal/agent/handlers/workspace_file_handlers.go` use the
|
|
sentinel in `wsGetFileContent` to log the expected condition at debug level
|
|
and return `ws.ErrorCodeNotFound`.
|
|
- Leave non-missing errors on the current error-level and
|
|
`ws.ErrorCodeInternalError` path.
|
|
- Add focused coverage for the server status, client sentinel, handler logs,
|
|
and genuine stat-failure path.
|
|
|
|
### Initial worktree persistence severity
|
|
|
|
- Update `apps/backend/internal/worktree/manager_state.go` so only the
|
|
`ErrEnvironmentNotResolved` branch uses debug severity. Keep the message
|
|
fields and return behavior stable.
|
|
- Add observer-backed coverage in
|
|
`apps/backend/internal/worktree/manager_state_test.go` for the typed
|
|
environment-not-resolved branch and verify that unrelated store errors still
|
|
follow the current error path.
|
|
|
|
## Tests
|
|
|
|
- **What:** Missing current-checkout file returns `not_found` and emits debug,
|
|
while a non-missing dependency failure remains `internal_error` and error.
|
|
**File:** `apps/backend/internal/agent/handlers/workspace_file_handlers_test.go`.
|
|
**How:** Use the real `agentctl.Client` against an `httptest.Server` and a
|
|
zap observer logger attached to the handler.
|
|
- **What:** Initial worktree persistence is debug-only and remains successful;
|
|
other store errors remain failures.
|
|
**File:** `apps/backend/internal/worktree/manager_state_test.go`.
|
|
**How:** Call the real `Manager.persistWorktree` with a focused fake store
|
|
returning typed errors and an observer logger. Do not create a Git worktree.
|
|
|
|
## Verification Results
|
|
|
|
- `cd apps/backend && go test ./internal/agent/handlers -run
|
|
'TestWorkspaceFileHandlers(Missing|NonMissing).*' -count=1` passed after the
|
|
workspace-file change and final formatting.
|
|
- `cd apps/backend && go test ./internal/worktree -run
|
|
'TestPersistWorktree_(EnvironmentNotResolved|OtherStoreError)' -count=1`
|
|
passed after the worktree change and final formatting.
|
|
- `cd apps/backend && go test ./internal/agent/handlers ./internal/worktree
|
|
-count=1` passed: both packages green.
|
|
- PR fixup RED: the client and process tests initially failed to compile
|
|
without the new `ErrFileNotFound` sentinels; the API rejection test reported
|
|
a missing file as 400; and the handler regression classified a 400 response
|
|
containing a legacy `file not found` message as `NOT_FOUND`.
|
|
- PR fixup GREEN:
|
|
`cd apps/backend && go test ./internal/agent/runtime/agentctl -run
|
|
'TestRequestFileContent_(Surfaces|DoesNot).*' -count=1` passed;
|
|
`cd apps/backend && go test ./internal/agentctl/server/process -run
|
|
TestReadFileContent_PermissionErrorIsNotMissing -count=1` passed;
|
|
`cd apps/backend && go test ./internal/agentctl/server/api -run
|
|
TestHandleFileContent_Rejections -count=1` passed; and
|
|
`cd apps/backend && go test ./internal/agent/handlers -run
|
|
'TestWorkspaceFileHandlers(Missing|NonMissing).*' -count=1` passed.
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
Execute sequentially in the primary session. The tasks touch disjoint backend
|
|
packages, but no delegation is authorized by this plan.
|
|
|
|
- [x] [task-01-workspace-file-severity](task-01-workspace-file-severity.md)
|
|
- [x] [task-02-worktree-initialization-severity](task-02-worktree-initialization-severity.md)
|
|
|
|
## Open Questions
|
|
|
|
None.
|