Files

T

Carlos Florêncio 832734bb67 docs: migrate legacy specs and add product context (#2964 )

2026-08-24 11:09:03 +00:00

4.1 KiB

Raw Blame History

spec, created, status

spec	created	status
docs/specs/platform/requirements/expected-runtime-log-severity.md	2026-08-23	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.

Open Questions

None.

4.1 KiB Raw Blame History