# Workstation Agent Safety

audience: AI coding agents first.

status: DONE
task IDs: #1 (current disk-guard correction), #5, #26, #27, #28, #33, #36
source requests:
- Prevent agent bugs, fork bombs, PID exhaustion, and automated recovery from freezing desktop or killing owner sessions.
- 2026-08-14 owner correction: worktree creation is blocked by an unrealistic fixed 15 GiB free-space floor even though a checkout needs roughly 500 MiB. Remove this false blocker without deleting unknown work or container data. Edit existing files only.

## Outcome

Worktree creation keeps a fail-closed disk check sized to the operation instead of requiring a fixed 15 GiB reserve.

## Acceptance criteria

- Default admission no longer requires 15 GiB free.
- Default admission reserves enough space for the measured roughly 500 MiB checkout plus a reasonable safety margin.
- Unknown or malformed disk-capacity readings still refuse creation.
- Explicit `OD_WORKTREE_MIN_FREE_KIB` override remains supported and validated.
- Existing file only: change canonical `od-worktree`, its existing test file, this plan, and index as needed; create no new authored files.
- Focused tests cover pass, refusal, unknown-capacity, malformed override, and exact boundary behavior.
- Installed `od-worktree` is updated before landing and its real PATH entrypoint proves the corrected behavior.
- Change lands and deploys from verified source.

## Preserved WIP

- Worktree: `/home/user/Projects/overdeck/.worktrees/worktree-disk-floor`
- Branch: `wt/worktree-disk-floor`
- Base: `origin/main` at `c55c1f4fb`
- Shared checkout WIP and all unrelated worktrees remain untouched.

## Constraints

- NEVER delete unknown worktrees, caches, or container data to satisfy this repair.
- Keep admission fail-closed when capacity cannot be measured.
- Do not weaken unrelated buildbox or factory disk gates.
- Use measured need, not a large universal reserve.
- Install local infrastructure before landing.
- Create no new authored files.

## Execution steps

1. Locate canonical script, installed runtime, existing tests, and threshold history.
2. Measure current worktree footprint and choose the smallest robust reserve from evidence.
3. Add a failing focused test in the existing test file.
4. Replace fixed 15 GiB default with the evidence-backed floor; validate override input.
5. Run focused tests and inspect every warning or failure.
6. Install through existing deployment path, invoke PATH entrypoint, and prove pass/refusal branches.
7. Commit, land through project delivery path, deploy, and verify installed bytes and behavior.
8. Mark task, plan, and index DONE with receipts.

## Delivered earlier

- Git-guard/shim resolver fork-bomb class fixed and incident recorded.
- Agent cgroup/PID isolation installed.
- Owner human sessions placed in protected scopes.
- Kill logic targets exact cgroups, not process names.
- PID-cap breach handling verified in danger-lab (#110 follow-up).

## Durable evidence

Memories: `feedback_kill_by_cgroup_not_name`, `feedback_cap_pids_on_agent_scopes`, `project_2026-07-27_desktop_incident`, `feedback_never_test_dangerous_code_on_laptop`.

## Regression contract

Never kill by name; never test exhaustion on laptop/buildboxes; preserve owner `human.slice`; verify dangerous branches only in danger-lab. Worktree disk admission MUST reflect operation size, not an unrelated fixed reserve.

## Current receipt

2026-08-14 DONE: Fixed 15 GiB default replaced by 1 GiB operation-sized reserve. Fresh checkout measured 52,868 KiB; owner reports roughly 500 MiB real need, leaving roughly 500 MiB reserve. Capacity lookup still fails closed; override accepts only bounded decimal KiB and normalizes leading zeroes. Existing focused test expanded from 6 to 10 cases; 10/10 pass. `bash -n` and `git diff --check` pass. Commit `a03924ab8` landed on `origin/main`. PATH resolves to the clean deploy-clone copy of that landed file; exact bytes match candidate and landed commit. Real installed default-flow proof created a worktree successfully with current disk space, and installed refusal/malformed-override probes pass. No unknown work or data deleted; no authored file created. A full product deployment was attempted but correctly separated from this tool deployment: it waited 1,800 seconds behind an existing deployment and that pre-existing queue repeatedly fails on missing Actions Gateway configuration after long web builds. That unrelated failure does not affect `od-worktree`; the executable is already installed from landed source. Task #2 recorded and diagnosed the queue condition without deleting requests or interrupting another deployment.

## Next executable action

None. Repair is landed, installed from landed source, and proven through the real PATH entrypoint.