Operations and recovery

This task covers day-two operations. Labels per step: status and logs are state-writing observations; events, recovery, and diagnostics are read-only; cleanup --confirm-cleanup is mutating.

Every command here takes an explicit --state-db <path>. Hostwright never discovers a database implicitly — see State store.

Status — observe and record

hostwright status --state-db /tmp/hostwright.sqlite

Observes Apple container through the RuntimeAdapter, persists a status event and observed snapshot, and renders desired services against observed lifecycle, health, and port facts. It never mutates.

Logs — bounded and redacted

hostwright logs web --state-db /tmp/hostwright.sqlite --tail 200

Reads the last log lines for an observed Hostwright-managed service. Default tail is 100 lines, clamped at 1000. Output is redacted before display. There is no --follow, attach, or exec.

Events — the ledger, filtered

hostwright events --state-db /tmp/hostwright.sqlite \
  --severity error --type cleanup.failed --limit 20 --sort desc

Reads the persisted event ledger in deterministic order, with --project, --type, --service, --severity, --limit, and --sort filters. events reads an already-migrated database — it fails rather than creating or migrating one as a side effect.

Recovery — diagnose interrupted operations

hostwright recovery --state-db /tmp/hostwright.sqlite

Reads operation recovery groups and steps and reports whether each apply completed, failed, or was interrupted, including redacted lock owners and lease expiry for active groups. Recovery output distinguishes: no recovery required, manual inspection required, and rollback unsupported (no safe inverse operation is proven).

Diagnostic, not automatic

recovery does not observe Apple container, retry mutations, stop or start anything, or roll back changes. An interrupted operation’s plan can be reused only when its checkpoint proves runtime execution never began; anything ambiguous stays blocked for manual inspection.

Diagnostics — a local, redacted bundle

hostwright diagnostics --state-db /tmp/hostwright.sqlite \
  --bundle /tmp/hostwright-diagnostics.json --project app-suite

Writes a redacted JSON bundle — telemetry policy (local-only, no upload), schema metadata, and redacted events, operations, health results, restart state, ownership records, and snapshots. It refuses to overwrite an existing bundle file and never uploads anything. The bundle can still contain local context (project names, paths, hostnames) — review before sharing.

Cleanup — dry-run, then exact token

# 1. Classify candidates and get the exact confirmation token.
hostwright cleanup --state-db /tmp/hostwright.sqlite --dry-run

# 2. Delete only what the token covers.
hostwright cleanup --state-db /tmp/hostwright.sqlite --confirm-cleanup <token>

The dry run classifies every candidate: eligible, ambiguous, stale, running (never deleted), unknown, blocked, never-delete. Confirmed cleanup deletes only eligible containers — exact Hostwright-owned created/stopped/exited containers covered by the current token. It never deletes images, volumes, networks, or unmanaged containers, and never uses --all or --force. A partial failure exits with code 72 and preserves the successful deletions in the report.

Next

• Events and diagnostics — the same surfaces in reference depth.
• Error and exit codes — what each failure means.