# Task 4 Report: Terminal agent-job status guard

## Status

Implemented Phase 1 Task 4. `updateStatus` now treats terminal Convex job state as authoritative and ignores later worker status writes instead of resurrecting a completed or cancelled job.

## Implementation

- Added a shared terminal-status set and predicate for `failed`, `cancelled`, `timed_out`, and `draft_pr_opened`.
- Reused the predicate in the existing terminal-job helper.
- Added an early successful no-op in `updateStatus` after worker claim validation.
- Added coverage proving cancelled jobs remain cancelled and running jobs still accept `checks_running`.

## Files

- `packages/backend/convex/agentJobs.ts`
- `packages/backend/tests/unit/update-status.test.ts`

## TDD Evidence

### RED

Command:

```sh
cd packages/backend && bun run test:unit -- update-status
```

Result: exit 1. One of two tests failed. The cancelled-job case received `{ success: true }` instead of `{ success: true, ignored: true }`, while the non-terminal transition test passed. This demonstrated that `updateStatus` had no terminal-state guard.

### GREEN

Command:

```sh
cd packages/backend && bun run test:unit -- update-status
```

Result: exit 0. One test file passed; both tests passed.

## Verification

Commands:

```sh
cd packages/backend && bun run test:unit
cd packages/backend && bun run lint
cd packages/backend && bun run typecheck
```

Results: all exited 0. The backend unit suite passed 2 files and 16 tests; ESLint and `tsc --noEmit` emitted no diagnostics.

## Codegen Environment

`bun codegen:convex` was attempted and exited 1 before tests because neither `CONVEX_SELF_HOSTED_URL` plus `CONVEX_SELF_HOSTED_ADMIN_KEY` nor `CONVEX_DEPLOYMENT` is available. To run `convex-test` without modifying generated files, the worktree temporarily used the existing generated snapshot from the primary checkout via a symlink. The symlink was removed before staging and committing.

## Self-review

- Confirmed claim ownership is still validated before terminal writes are ignored.
- Confirmed all four specified terminal statuses share the guard.
- Confirmed non-terminal worker transitions retain their prior behavior.
- Confirmed no generated Convex files were edited or committed.

## Concerns

Full root-level validation remains unavailable without a configured Convex codegen environment. Focused and package-level backend checks pass against the existing generated snapshot.