Events and diagnostics

Every meaningful step (observations, applies, cleanups, daemon iterations, health checks) lands in the event ledger of the explicit 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>]

Apply persists an operation recovery group with step records (intent, checkpoints, forward runtime steps, rollback-unavailable markers, and redacted manual recovery hints) before and during mutation. recovery reads those groups and reports, per operation:

• no automatic recovery required: it completed;
• manual inspection required: it failed or was interrupted;
• rollback unsupported: no safe inverse operation is proven.

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). A recorded intent stays blocked unless its checkpoint proves runtime execution never began (pre-runtime-state-incomplete); ambiguous or post-runtime interruptions require manual inspection. Older databases with legacy restart recovery records render those as legacy entries.

Diagnostic output

Recovery never observes Apple container, retries mutation, stops/starts/ deletes resources, or rolls anything back. Hostwright has no automatic rollback because no safe inverse operation is proven; the output is a diagnosis, not a repair.

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.