Concepts

Five ideas cover how AWOS works: jobs, workspaces, verification, review branches, and blocked jobs.

Job

A job is one ticket: a goal, a repository and a budget. awos submit puts it in a local queue, and the worker started with awos serve --worker runs jobs one at a time.

• The queue is a database on disk under ~/.awos/host/ (set AWOS_HOST_DIR to move it). Jobs survive restarts of the worker and of your machine.
• A job moves through queued, running, and then done, failed, cancelled or blocked.
• If a job runs out of turns but made progress, the worker may give it one continuation before marking it failed.

Workspace

Each job works in a throwaway git worktree created at your repository's current commit. Your checkout, your uncommitted changes and your branches are left alone while the job runs. When the job ends, its changes are turned into a branch and the workspace is no longer needed.

Verification

A job is not "done" just because the agent says so. Three checks run before handoff:

• Acceptance tests. Before changing any code, AWOS writes a few tests from your goal and keeps only the ones that fail on the starting code, so they prove the change does what you asked. The job has to make them pass. This is on by default; set AWOS_ACCEPTANCE=0 to turn it off.
• Your tests. If the workspace has a pytest suite (files named test_*.py or *_test.py), the worker runs it itself after the agent finishes and records the pass and fail counts in the report. This is the worker's own evidence, not the agent's claim.
• Goal check. A separate model pass reads the original goal and what changed, looks for every place the goal applies, and tries the goal's behaviour on a throwaway copy of the workspace: the stated inputs, error cases and boundaries. Anything missing comes back as follow-up work before the job finishes.

Existing tests rarely cover a new multi-part goal, which is why the goal check stays on even when a repository has tests.

Review branch

When a job finishes, its diff becomes a local branch named awos/<id>, created from the job's base commit. The branch is built with git plumbing and a temporary index, so your HEAD, index and working tree are not modified.

• Environment files, private keys, the .awos/ folder, bytecode and test caches are never included.
• A secret scan runs on the diff. If it finds a credential, the branch is blocked and the report says why, without repeating the secret.
• Nothing is pushed. AWOS has no network git operation in its handoff.

The job's report.md sits next to it under ~/.awos/host/jobs/<id>/: the goal, test results, cost, time and warnings.

Blocked jobs

If a model key is wrong, revoked or out of credit, the job is parked as blocked instead of failing and burning retries. You get one notification with the action to take, and awos status --digest lists it.

• Once the key checks out again, the worker re-queues credential-blocked jobs on its own.
• To retry one right away, run awos unblock <id>.
• A network outage is not a block: the worker backs off and retries.