fix: resolve issues #43, #46, #48, #49

[AbirAbbas]

Summary

Addresses four open issues in a single PR:

• fix: /workspaces directory must be pre-created in Dockerfile with write permissions #46 — Pre-create /workspaces in Dockerfile with 777 permissions so named volume mounts work on fresh deployments (was: [Errno 30] Read-only file system)
• Fatal API errors (credit exhaustion, invalid key) silently retry instead of aborting the build #49 — Add FatalHarnessError for non-retryable API errors (credit exhaustion, invalid key, disabled account). Prevents silent retry loops across all 3 retry layers; surfaces real error message instead of misleading "failed to produce a valid PRD"
• Agents in parallel builds appear to be getting cross-contaminated #43 — Scope workspace paths by build_id (/workspaces/<repo>-<build_id>) so parallel builds get fully isolated git state, artifacts, and worktrees
• docs: add cross-server installation guide covering known deployment gotchas #48 — Add docs/deployment.md covering prerequisites, quick-start, known issues, scaling, and troubleshooting

Files changed

File	Change
Dockerfile	Add mkdir -p /workspaces && chmod 777 (#46)
swe_af/execution/fatal_error.py	New — FatalHarnessError, check_fatal_harness_error(), is_fatal_error() (#49)
swe_af/reasoners/pipeline.py	Add fatal error checks at 4 harness call sites (#49)
swe_af/reasoners/execution_agents.py	Add fatal error checks at 16 call sites + re-raise in 17 except blocks (#49)
swe_af/execution/coding_loop.py	Re-raise FatalHarnessError in 4 except blocks (#49)
swe_af/execution/dag_executor.py	Re-raise FatalHarnessError in 5 except blocks (#49)
swe_af/execution/envelope.py	Raise FatalHarnessError for fatal envelope errors (#49)
swe_af/app.py	Generate build_id before clone, scope workspace path (#43)
docs/deployment.md	New — deployment guide (#48)

New tests (59 total, 0 regressions)

Test file	Count	Coverage
tests/test_dockerfile.py	3	Dockerfile structure validation
tests/test_fatal_error.py	40	Pattern matching, exception propagation, envelope integration
tests/test_build_isolation.py	5	Workspace path isolation, build_id ordering
tests/test_deployment_docs.py	11	Doc structure, section completeness

Test plan

• pytest tests/test_dockerfile.py — 3 passed
• pytest tests/test_fatal_error.py — 40 passed
• pytest tests/test_build_isolation.py — 5 passed
• pytest tests/test_deployment_docs.py — 11 passed
• Full suite: 769 passed, 0 new failures (12 pre-existing)
• Docker build + container write test
• Manual end-to-end verification of each fix

Closes #43, closes #46, closes #48, closes #49

🤖 Generated with Claude Code