feat: unattended auto-update with trust/control UX (Phase 1 + 2)

[songcarver]

Summary

• implement unattended scheduler-driven auto-update path with hook-safe global locking
• persist updater state/retry metadata and enforce stable-only background install policy
• add scheduler provisioning/reconciliation and health visibility in status/doctor
• add trust/control surfaces: cadence auto-update status|enable|disable|uninstall
• add cadence doctor --repair and explicit remediation guidance
• clarify update vs auto-update behavior and uninstall controls in README

Validation

• cargo fmt
• cargo clippy
• cargo test

Notes

• scheduler cleanup/install flows are idempotent
• disabled mode (auto_update=false) causes scheduled updater runs to no-op

[songcarver]

Testing is the next step.

Apparently …

`Use a fully local canary flow so nothing touches real releases.

Build two local binaries
old binary (current code)
new binary (same code but higher version, e.g. 1.3.1-dev)
Serve fake “latest release” locally
Run a local HTTP server that mimics GitHub redirect + release asset URLs.
Point updater to this URL in tests/dev mode (you already have injectable run_update_install_from_url patterns in code/tests).
Publish fake artifacts
Create local tar/zip artifacts + checksums-sha256.txt for all needed targets.
Ensure redirect points to fake v1.3.1-dev.
Isolate install/state paths
Run with temp HOME / temp cadence dir so you don’t touch real install or real scheduler.
Use a temp binary path as “installed cadence”.
Test scheduler path without waiting
Create scheduler entries with short interval in temp/dev mode, or invoke the internal updater command directly (cadence hook auto-update) to simulate scheduler run.
For hook collision testing, hold the lock in one process and run updater in another.
Validate outcomes
Binary replacement happened only in temp install path.
State file transitions (last_attempt, last_success, backoff, errors).
Disabled mode no-ops.
Uninstall command removes scheduler artifacts (in temp/dev harness).
If you want, I can draft a concrete scripts/e2e-autoupdate-local.sh harness for this repo.`

[cadence]

Cadence Session Review

Score	Plan-driven but missed key safety constraints in implementation details
Models	Codex (codex-5.3)
Sessions	8
Phases	30% planning/investigation, 55% implementation, 10% docs, 5% debugging

Multiple overlapping Codex sessions implemented a two-phase auto-update system from a detailed plan doc. The model followed the plan structure closely — scheduler provisioning, activity lock, updater state, trust/control UX — but made several architectural shortcuts that weaken the plan's safety guarantees.

• Activity lock acquired too late in the install pipeline (only at binary replace), not at the full operation scope as the plan specified
• Blocking lock acquisition has no timeout, risking infinite spin in edge cases
• Heavy sysinfo::refresh_processes() used for simple PID-alive check in a hook-critical path
• Manual update path lost auto_update=true as a confirmation bypass (regression from plan's "preserve existing semantics")
• Sessions show significant redundancy — at least 4-5 sessions with near-identical opening prompts and exploration patterns

Recommendations

Prompting — Add explicit safety-invariant verification checkpoints to implementation prompts

The handoff prompt told the model to treat the plan as source of truth but didn't call out specific invariants that must hold. The model implemented the structure but violated the lock-scope and confirmation-bypass semantics. Adding explicit verification checkpoints in the prompt forces the model to self-audit against the plan's safety properties.

Before
Implement the plan in: docs/auto-update-v1-plan.md\n\nImportant:\n- Treat that file as the source of truth.\n- Build unattended background auto-update exactly per plan constraints

Reframe
Implement the plan in: docs/auto-update-v1-plan.md\n\nCritical constraints to verify before committing:\n1. Activity lock must guard the ENTIRE install pipeline (download through replace), not just the replace step\n2. Blocking lock acquire must have a bounded timeout (e.g. 30s) to prevent hook stalls\n3. Manual cadence update must preserve existing auto_update=true confirmation bypass behavior\n4. All scheduler provisioning paths must be tested on the target platform before push

Tip
When a plan doc has safety-critical constraints, list them as explicit acceptance checks in the prompt rather than relying on the model to infer them from the plan.

Agent instructions — Add hook-path performance constraints to AGENTS.md

The AGENTS.md says 'Use Tokio for production I/O' and 'Do not block the Tokio runtime' but doesn't mention lock timeout requirements or heavyweight-dependency avoidance in hook paths. Adding a rule like 'Hook paths must complete within a bounded time budget — never use unbounded loops or heavy process-table scans in code reachable from hooks' would have prevented two issues in this PR.

Tip
Agent instruction files should encode performance invariants for latency-sensitive code paths, not just general async hygiene.

Prompting — Reduce session redundancy with structured handoff state

At least 4 sessions used near-identical opening prompts and re-discovered the same codebase state before making incremental changes. Each session re-ran rg --files, re-read the plan, and re-explored src/update.rs. Structuring the handoff prompt to include a summary of what was already implemented (with commit SHAs) and what remains would reduce redundant exploration and increase the useful work per session.

Tip
Include a 'completed so far' section in handoff prompts: list committed files, functions added, and remaining plan items. This prevents the model from re-reading everything.

[cadence]

The model acquires the activity lock only at the self-replace step (line R1052), but the entire download/checksum/extract pipeline runs outside the lock. This means a hook can start while the updater is mid-download, and the lock only gates the final binary swap. The plan specifies the updater should attempt non-blocking acquire and "exit fast if unavailable" — the intent was to hold the lock for the full install operation, not just the replace step. This late-lock pattern reduces the safety guarantee the plan called for.

[cadence]

The model duplicated self_replace_binary(&new_binary)? in both branches of an if/else — the only difference is the activity lock acquisition in the unattended path. This could be simplified by acquiring the lock earlier (guarding the whole install) or extracting the lock acquisition before the shared call. The duplication is a code smell the model should have noticed.

[cadence]

Using sysinfo with refresh_processes() to check if a single PID is alive is heavyweight — it refreshes the entire process table. On systems with many processes this adds unnecessary latency to every lock-staleness check. A lighter approach (e.g., kill(pid, 0) on Unix or OpenProcess on Windows) would be more appropriate for a hook-safe path that must remain fast.

[cadence]

The blocking lock acquisition loops with a 20ms sleep and no timeout. In a pathological case (e.g., stale lock from a killed process whose PID was recycled by another long-running process), clear_stale_activity_lock won't remove it (process appears alive), and hooks will spin forever. The plan states "hooks/deferred-sync acquire and run immediately" — a bounded retry with a timeout would be safer.

[cadence]

The model's run_update_install_from_url_mode for SilentUnattended mode skips loading config for auto-update preference (line R956-R961) but then also skips the confirm_update call entirely (line R996-R998). However, in the background auto-update path (run_background_auto_update), the config is loaded separately and auto_update_enabled() is checked. This means the interactive path lost the auto_update config-based auto-confirm behavior — passing yes: true from the background caller masks this, but manual cadence update without --yes no longer respects auto_update=true from config as a confirmation bypass. The plan explicitly preserved the existing manual update semantics.

[cadence]

When auto_update is already set, the model shows a disclosure block and returns early. But the condition if cfg.auto_update.is_some() means this disclosure fires for both Some(true) and Some(false) — users who explicitly disabled auto-update still see the "background updater runs unattended" message, which is misleading. The early-return also skips the prompt for users who might want to change their mind.

[cadence]

Passive version check is now skipped for all hook commands (!is_hook_command), which is good. However, this changes behavior for Command::AutoUpdate subcommands too — they'll still trigger passive checks since they aren't hook commands. This is fine but worth noting: the model correctly addressed the plan's constraint that hooks shouldn't trigger passive checks, even though it wasn't explicitly called out for the new AutoUpdate command.