feat(hooks): background hook jobs + universal logging + daft hooks jobs CLI

[avihut]

Summary

Big feature branch landing the background-hook-jobs subsystem and everything that grew around it. Three independent sub-projects bundled into one PR (each was originally going to ship separately, but they share enough state — log store, coordinator IPC, retention policy — that splitting them at this point would create more churn than it saves). 194 commits, +35.2k / -302 lines, 119 files.

What's in here

Background hook jobs (sub-project A core). worktree-post-create and friends can declare background: true jobs that run asynchronously after the command returns. A single forked coordinator process per repo manages them — runs jobs as threads, persists results, exposes a Unix-socket IPC for cancel/list/shutdown. New src/coordinator/ module: process.rs (fork + run), client.rs/ipc.rs (Unix-socket protocol), log_store.rs (<state>/jobs/<repo-uuid>/<inv-id>/<job-name>/{meta.json,output.log}), clean_policy.rs (retention/budget/keep-last).

Universal hook invocation logging. Every hook fire — foreground or background, declared or not — produces an invocation record + per-job records. Removes the long-standing gap where pre-remove hooks with only foreground jobs left no audit trail. Cross-worktree resolution lets you address jobs even after the worktree directory is gone.

`daft hooks jobs` CLI. New top-level command tree: `list`, `logs`, `cancel` (per-job + `--all`), `retry` (single + invocation-prefix bulk), `prune` (replaces the deprecated `clean`). Multi-format output (`--format json|yaml|tsv|csv|markdown|toon|ndjson|template`) and a `--template` flag for Tera. Filters: `--worktree`, `--status`, `--hook`, `--all` for cross-repo views. Composite addressing (`worktree::job`, `inv:job`, `worktree:inv:job`) with hex/slash heuristics so users don't have to think about disambiguation.

Log maintenance (sub-project B). Three-pass cleanup: per-log truncation (`max_log_size`, default 10 MB), retention sweep (`retention`, default 7 d, with `keep_last` floor of 3), per-repo budget (`max_total_size`, default 500 MB, LRU eviction). Auto-fires once per 24 h via a detached `daft __clean-logs` child (gated by `DAFT_NO_LOG_CLEAN` and CI detection). Manual escape hatch: `daft hooks jobs prune [--dry-run] [--older-than]`. Repo-level policy (`max_total_size`/`keep_last`/`stale_running_after`) persisted to a `repo-policy.json` sidecar so cleanup never has to re-read `daft.yml`.

UX polish. Outline renderer for the listing's vertical-spine timeline; column alignment across invocations; proper sub-second duration rendering (`36ms` instead of `<1m`); tab completion for hooks-jobs commands (job names, invocation prefixes, worktree drill-down); deprecation warnings for the old `hooks jobs clean` verb.

Ultrareview bug fixes (final 20 commits). Wrapping up four findings from a cloud review:

1. Background-job cancellation was non-functional end-to-end. `ChildPidMap` was never populated (`run_command` didn't expose the spawned PID); per-job cancel produced `Failed` not `Cancelled`; worktree-removal cancel compared filesystem path against branch slug; `branch-delete` path didn't call the cancel helper at all; the coordinator IPC server is one-request-per-stream but the cancel helper reused a single client.
2. Documented `log` / `background_output` fields were silent no-ops. Top-level `log:` block never propagated to per-job `log_config`; `background_output: silent` parsed and validated but no execution path consulted it; `log.path` was parsed and merged but no writer ever read it (stripped, since the subsystem is unreleased).
3. `write_repo_policy` clobbered persisted tuning. Truncate-write of an all-`None` policy (the common case for hooks without log blocks) silently reset user values to defaults. Now field-merges with on-disk so unset fields preserve.
4. Cleanup summary accounting was wrong. `enforce_budget` returned only the eviction count, dropping the per-invocation byte/job totals it had already computed. `prune --dry-run` always reported `across 0 invocation(s)`. Fixed to return a full `BudgetOutcome { evicted_invocations, freed_bytes, freed_jobs }` and to hoist the dry-run tally above the early-return.

Why now

The three sub-projects feed each other tightly. Sub-project A introduced the log store; B added the cleanup machinery that needs A's persisted retention; the universal-logging work sits between them. Splitting the merge at this stage would mean either landing B without enough of A's machinery to test against (`prune` with no logs to prune), or landing the universal-logging changes on top of an unmerged sub-project A. Cleaner to ship the bundle.

Spec/plan trail

• `docs/superpowers/specs/2026-03-27-background-hook-jobs-design.md` — sub-project A.
• `docs/superpowers/specs/2026-04-11-universal-hook-logging.md` — universal logging.
• `docs/superpowers/specs/2026-04-25-hooks-jobs-log-maintenance.md` — sub-project B.
• `docs/superpowers/plans/2026-04-26-hooks-jobs-ultrareview-fixes.md` — final 4-bug fixup.

User-facing docs in `docs/guide/hooks.md` (`Background Jobs`, `Log Configuration`) and `docs/cli/daft-hooks-jobs.md`.

Deferred follow-ups

Tracked in `~/.claude/projects/.../memory/project_hooks_jobs_followups.md` so they don't drop on the floor:

• `cancel_background_jobs_for_worktree` cross-module placement (lives in `prune.rs` but called from `branch_delete.rs` too).
• `write_repo_policy` atomicity (tmpfile+rename) and version-downgrade handling.
• `prune --dry-run` summary gate is asymmetric (defense-in-depth tighten).
• Argument-bag refactor for `yaml_jobs_to_specs` (8 args) / `execute_yaml_hook_with_rc` (11 args) / `run_single_background_job` (7 args).
• Composite-address parser quirks (`worktree:job` requires three-segment form).

Test plan

• `mise run ci` green locally — 484 manual scenarios, 1802 steps, all 4 matrix combos (default+gitoxide × bash+yaml). Total ~20 min.
• `mise run test:unit` — 1375 tests pass, clippy clean, fmt clean.
• Per-task unit tests for each of the 4 ultrareview bugs (PID register/deregister, per-job cancel marks Cancelled, silent log delete on success / preserve on failure / preserve on cancellation, repo-policy field-merge preserves and overrides, budget outcome reports bytes+jobs, dry-run tallies invocations).
• Manual scenarios for each of the 4 ultrareview bugs (`bg-job-cancel-by-name.yml`, `bg-job-cancel-on-worktree-remove.yml`, `repo-log-defaults-applied.yml`, `repo-policy-not-clobbered.yml`, `prune-budget-accounting.yml`, `prune-dry-run-invocations.yml`, `bg-output-silent.yml`). Mutation-tested the silent-stderr negative assertion to confirm it has teeth across the fork+setsid boundary.
• Sandbox sanity walk after merge: per-job cancel terminates child, `--all` cancel terminates all, `git-worktree-branch -D` triggers auto-cancel, top-level `log: { max_total_size: 100MB }` shows `104857600` in `repo-policy.json` and survives a subsequent hook fire without the log block, `prune` with tight budget reports non-zero `freed`, `prune --dry-run` reports correct `across N invocation(s)`, silent bg job leaves no `output.log` on success.

🤖 Generated with Claude Code