| name | resource-lifetime-audit |
| description | Audit and fix Audiobook Boss resource-lifetime foot-guns with high bug potential. Use when the user asks to hunt for lifecycle bugs, file-handle contention, Windows/cross-platform file behavior, temp-file cleanup, process lifetime, FFmpeg/mp4ameta reopen issues, rename/replace semantics, or "similar in-kind" high-ROI issues. |
Resource Lifetime Audit
Scan Scope
Scan the highest-risk boundaries first: audio processing, metadata read/write/remux, output artifact commit, path validation, cleanup, cancellation, and external process handling.
Hunt Pattern
Search for code that crosses one lifecycle phase into another:
- probe/open/read -> reopen same path
- FFmpeg context -> mp4ameta read/write on same path
- write temp -> rename/copy/replace final path
- spawn process -> read pipes -> cancel/kill/wait
- register cleanup -> remove path from cleanup ownership
- validate path -> persist or write path
For each candidate, ask:
- What resource is still alive?
- What opens, mutates, deletes, renames, or replaces the same resource next?
- Does this rely on macOS/POSIX behavior that may fail on Windows?
- Would a failure cause false success, file loss, residue, stuck jobs, or noisy retries?
- Is the fix local and testable?
Priority
Prioritize findings that touch:
- source audiobook files
- final output artifacts
- metadata writes and cover art
- FFmpeg input/output contexts
- external FFmpeg processes
- cleanup/cancellation terminal paths
Defer low-impact style cleanup unless it prevents repeated lifecycle mistakes.
Fix Shape
Prefer explicit ownership transitions:
- Drop FFmpeg probe contexts before reopening the same path.
- Keep replacement behavior in the owning boundary.
- Use backup/rollback or create-new semantics instead of assuming rename-over-existing is portable.
- Remove cleanup ownership only after the durable artifact is committed.
- Map file/path errors through existing
AppError patterns.
Add focused tests when behavior is deterministic without real media. Use the
owner-scoped command menu from README.md / scripts/AGENTS.md for code
changes.
Report Shape
Lead with the category name, affected boundary, impact, and fix. Use "resource-lifetime foot-gun" for hazards that are not always active bugs but have credible cross-platform or edge-case failure paths.
