Events and diagnostics

Every meaningful step (observations, applies, cleanups, daemon iterations, health checks) lands in the event ledger of the resolved state database, so failures are explainable after the fact. Three read-only commands expose it. All three read an already-migrated database and fail rather than creating or migrating one as a side effect.

Events

hostwright events --state-db /tmp/hostwright.sqlite \
  [--project <name>] [--type <event>] [--service <name>] \
  [--severity info|warning|error] [--limit <n>] [--sort asc|desc] \
  [--output text|json]

Events render in deterministic timestamp/id order. Types include status observations, logs.read, apply start/success/failure, cleanup.*, team.profile.selected, team.approval.recorded, daemon.started, daemon.reconcile.succeeded, daemon.reconcile.failed, daemon.backoff, daemon.sleep_wake_resumed, daemon.stopped, health.check.*, and restart.policy.state. Payloads are redacted before persistence, so the ledger is safe to read but still local-context-rich.

Recovery

hostwright recovery --state-db /tmp/hostwright.sqlite [--project <name>]
hostwright recovery resume --group <uuid> --confirm-plan <hash> [--state-db <path>]
hostwright recovery rollback --group <uuid> --confirm-plan <hash> [--state-db <path>]

A lifecycle command persists an operation recovery group with step records (intent, checkpoints, forward runtime steps, provable inverse actions, and redacted manual recovery hints) before and during mutation. The bare recovery command reads those groups and reports, per operation:

• no recovery required: it completed;
• resumable: it can continue from its persisted checkpoint;
• compensable: a provable inverse action can roll it back;
• manual inspection required: interruption left it in an ambiguous state with no provable resume or rollback path.

Active groups show their redacted lock owner and lease expiry. A group with no persisted mutation intent can be reacquired after lease expiry (the old group is marked interrupted). Older databases with legacy restart recovery records render those as legacy entries.

recovery resume and recovery rollback require the exact group UUID and its persisted plan hash, and both re-observe current provider identity, capabilities, and ownership before acting. resume continues only steps not already verified complete. rollback applies only the precomputed inverse actions the group can prove are safe; anything it cannot prove stays in a safe hold rather than being forced.

Nothing happens without a fresh confirmation

The bare recovery command only inspects: it never observes the runtime, retries mutation, or changes anything. resume and rollback act only when explicitly invoked with a matching plan hash, and only on the exact steps their persisted evidence supports.

Diagnostics bundles

hostwright diagnostics --state-db /tmp/hostwright.sqlite \
  --bundle /tmp/hostwright-diagnostics.json [--project <name>] [--manifest <path>]

Writes a local redacted JSON bundle containing:

• the telemetry policy statement (local-only, no upload);
• state schema and version metadata;
• an optional manifest summary (omitting --manifest makes the bundle state-only; only paths you pass are read);
• redacted events, operations, operation groups and steps, health results, restart policy state, restart recovery records, ownership records, and observed snapshots.

It refuses to overwrite an existing bundle path (HW-CLI-002) and never inspects or mutates the runtime, creates or migrates a database, or uploads anything. Bundles can still contain sensitive local context (project names, service names, paths, hostnames, identifiers). Review before sharing.

Telemetry policy

Hostwright’s telemetry policy is local-only and is itself reported in doctor, status, and diagnostics output. There is no external telemetry, hosted diagnostics, automatic upload, or OSLog integration. See Limitations.