docs(FN-4795): add secrets env-cleanup documentation and changeset

- Add changeset for env cleanup secret-write/event emission
- Create docs/secrets.md with secret env-write and env-cleanup documentation
- Update AGENTS.md run-audit filesystem events with env-cleanup entries

Fusion-Task-Id: FN-4795
This commit is contained in:
Fusion (runfusion.ai)
2026-05-17 02:05:34 -07:00
committed by gsxdsm
parent 2f2f7de85a
commit 2f2198a622
3 changed files with 26 additions and 1 deletions

View File

@@ -0,0 +1,5 @@
---
"@runfusion/fusion": patch
---
Add worktree teardown cleanup for Fusion-managed secrets env files by deleting only files whose fingerprint still matches the recorded write, and emit cleanup/skip audit events.

View File

@@ -665,7 +665,7 @@ See [docs/workflow-steps.md](./docs/workflow-steps.md) for the full reference in
The run-audit system records every mutation performed by the engine across four domains:
- **Database** — task:create, task:update, task:move, etc.
- **Git** — worktree:create, commit:create, merge:resolve, etc.
- **Filesystem** — file:write, prompt:write, attachment:create, etc.
- **Filesystem** — file:write, prompt:write, attachment:create, secret:env-write, secret:env-write-skipped, secret:env-cleanup, secret:env-cleanup-skipped, etc.
- **Sandbox** — backend lifecycle (`sandbox:prepare`, `sandbox:run`, `sandbox:failure`, `sandbox:fallback`) from `SandboxBackend` wiring in executor/merger/routine-runner.
Events are tied to specific run IDs for end-to-end traceability. See [docs/architecture.md](./docs/architecture.md) for the audit API reference.

20
docs/secrets.md Normal file
View File

@@ -0,0 +1,20 @@
# Secrets
## Worktree `.env` export
Fusion can materialize selected secrets into a task worktree env file during provisioning.
### Worktree teardown cleanup
When a worktree is removed, Fusion checks the fingerprint sidecar created at write-time.
- If the env file still matches the persisted SHA-256 fingerprint, Fusion deletes the env file and the sidecar.
- If the env file is missing, Fusion removes the sidecar and records a skipped cleanup reason.
- If the fingerprint does not match (file edited/replaced), Fusion preserves the env file, removes the sidecar, and stops claiming ownership.
Audit events for this lifecycle are emitted without secret values:
- `secret:env-write`
- `secret:env-write-skipped`
- `secret:env-cleanup`
- `secret:env-cleanup-skipped`