Release orphan boxes hourly and report a missing secrets exchange (DRU-477)

[czpython]

Lands on main after #468 (DRU-480). Linear: DRU-477.

What changed

• release_orphan_boxes is a core task every hour, beside reap_deleted_files. SandboxIdentity.list_orphans() names the identities of boxes whose run ended: bound, inside their lease, not revoked. The task releases each box through Client.release, which revokes the identity first and swallows a Drukbox failure. Drukbox reaps a box at the end of its lease in any case; the task only ends it sooner.
• SandboxIdentity.revoke() keeps its first stamp.
• druks doctor gets check_secrets_exchange. It probes [sandbox].exchange_url at /healthz. With sandbox execution off it reports not configured. When the exchange is unreachable or answers a non-200, it names the service, the URL, and the fix. No box, no credential.
• Tests: the release and the doctor probe. A finished run's box goes and a live run's stays. A box past its lease is left to Drukbox. An identity without a box and a second tick do nothing. The probe is off, healthy, or unreachable.
• Docs: deployment.md, troubleshooting.md, concepts.md.

Where this differs from the ticket

• No reaper revokes identities. The issuer already denies an identity whose run ended or whose lease passed, so the records stay as they are. The one thing a tick buys is the box of a run that died without its cleanup, released before its 150-minute lease ends.
• Hourly, not every 15 minutes, for the same reason.
• A release that fails while Drukbox is down is not retried. Client.release revokes the identity first, so the box waits for its lease, and that bounds the cost at one lease.
• An identity that never bound a box is left alone. It expires with the lease it never used.
• Rebased on the vault: the rows are sandbox identities, and the mint is the issuer. Two tests from the grant version did not come across. The run wrapper's release test named seams the workflow module no longer has, and the integrated mint test ran through the old mint route. The issuer's denial of a terminal run's identity is covered in test_sandbox_identities.py.

Names

• release_orphan_boxes beside reap_deleted_files; _release_orphan_boxes is the body a test calls, as _refresh is.
• list_orphans follows list_for_secret.
• secrets_exchange matches the compose service drukbox-exchange in the doctor output.

Gates

• ruff check backend and ruff format --check backend: clean.
• pytest backend/ with the proof app installed, rebased on main: 1698 passed.
• CI runs the full suite. No migration.

Review

Real bed, Paulo's run. Dispatch a run on a warm box, then kill the web process before it ends. Within an hour of the next start, record the task's log line for that box and confirm the box is gone from Drukbox. Also run druks doctor once with the exchange stopped and once with it up, and record the secrets_exchange line each time.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
druks	🟢 Ready	View Preview	Sep 8, 2026, 4:21 PM

💡 Tip: Enable Automations to automatically generate PRs for you.