# `thothctl pi` lifecycle contract

`thothctl` is the only component that drives Docker lifecycle operations. The `core` container
does not mount a Docker socket and Pi is never updated in a running container.

## Read-only operations

```text
thothctl --installation /absolute/path/thothii-installation.yaml pi status
thothctl --installation /absolute/path/thothii-installation.yaml pi doctor
thothctl --installation /absolute/path/thothii-installation.yaml pi test
thothctl --installation /absolute/path/thothii-installation.yaml pi logs [--follow]
```

`status` executes the image-bundled `pi --version`. `doctor` requires the rendered `core` image,
the external `THT_LLM_URL` contract, writable `/home/thoth/.pi`, the read-only Pi auth file, and
private `/health`. `test` additionally reads private `/models` and `/settings`; this temporary
composite smoke is replaced by the Pi Management API in Task 8. `logs` is core-only and uses the
same credential redaction as every other `thothctl` diagnostic.

`pi check` is an alias for `pi test` for operational scripts.

## Updating Pi

An update always specifies a pinned Pi version and an explicit confirmation:

```text
thothctl --installation /absolute/path/thothii-installation.yaml pi update \
  --version 0.81.0 --source build --yes
```

`--source build` rebuilds only `core` using `PI_VERSION=<version>`. A pulled source must be a
digest-pinned image; tags are rejected:

```text
thothctl --installation /absolute/path/thothii-installation.yaml pi update \
  --version 0.81.0 --source pull \
  --image registry.example.invalid/thothii-core@sha256:<64-lowercase-hex-digits> --yes
```

Before changing anything, the command validates the rendered Compose configuration, Pi auth/state
preconditions, health, current version, active sessions, the current image ID, named-volume set,
and a digest of the rendered non-secret configuration. It therefore keeps the exact installation
Compose files and environment, including the external `THT_LLM_URL` endpoint, when it recreates
only `core` with `--no-deps --force-recreate`. It never recreates `frontend` and never uses volume
replacement flags.

Open, unarchived sessions stop an update. After an operator has completed or otherwise drained
their work, `--drain` makes the command re-check that the session list is empty before continuing.

## Recovery and rollback

Before a candidate is built or pulled, the command atomically writes:

```text
<projectDirectory>/.thothctl/update-state.json
```

The file is mode `0600` and records only the previous/candidate image references and IDs, named
volume names, requested version/source, rendered-configuration digest, phase, and timestamp. It
never contains credentials, endpoint values, secret paths, Compose output, or logs.

After recreate, the command checks core health, the requested `pi --version`, the Pi/core smoke,
unchanged configuration digest, and unchanged named-volume set. Any failure after recreation
automatically retags and recreates the recorded previous image. A failed or interrupted operation
leaves the same metadata for explicit operator recovery:

```text
thothctl --installation /absolute/path/thothii-installation.yaml pi rollback --yes
```

Both update and rollback require `--yes`; without it they exit `2` before invoking Docker. Invalid
arguments, a pending recovery, and active sessions also exit `2`. Docker or verification failures
exit nonzero with concise, redacted guidance. The original Docker child exit code is preserved for
direct read-only/log command failures.