ThothII/docs/contracts/thothctl-pi.md

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.

Inspection and configuration

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
thothctl --installation /absolute/path/thothii-installation.yaml pi configure

status executes the image-bundled pi --version. doctor and test require a healthy core, a successful Pi smoke, valid settings, and an exact selected provider/model pair from the backend's available model entries. pi check remains an alias for pi test. Logs are always a bounded, sanitized 200-line snapshot; there is no follow mode.

On a TTY, pi configure presents numbered provider, model, and thinking choices. Providers and models come from the backend's closed model list, and the model choices are restricted to the selected provider. In non-interactive use, all choices must be explicit:

thothctl --installation /absolute/path/thothii-installation.yaml pi configure \
  --provider zai --model glm-5.2 --thinking medium

The helper snapshots the previous settings, applies the new values atomically, and verifies the readback and rendered-configuration digest. A helper, readback, or digest failure triggers an attempted restore followed by another readback. The command reports the actual host path from PI_AUTH_FILE; credentials remain in that protected host file and must never be passed as flags.

Updating Pi

Every update requires a pinned version, an explicit source, and confirmation:

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

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

--source build rebuilds only core with PI_VERSION=<version>. --source pull requires an immutable digest reference; mutable tags, URL forms, and credential-bearing references are rejected. --source is never inferred.

Before inventory, update activates the durable maintenance gate. Activation writes /data/settings/maintenance.json in the mounted settings volume, closes admission, and waits for all leases. A recreated candidate reads that marker at startup and therefore starts gated. The loopback-only control endpoints cannot be reached through the frontend proxy and do not depend on the configured authentication principal mode. Lost activation/deactivation responses are resolved by querying gate status.

Open, unarchived sessions stop an update. After an operator has completed or otherwise drained their work, --drain makes the command poll the authenticated bare-array GET /sessions?scope=all response until no active sessions remain.

The configured core.image is never retagged or mutated. Each installation transaction creates unique candidate and previous tags, including when two installations share a configured tag or the configured image is digest-pinned. A temporary lifecycle-only Compose override selects those tags for build, recreate, and rollback. Terminal success removes the override.

Only core is recreated, with --no-deps --force-recreate; frontend is not recreated and no volume-replacement flags are used. Verification checks health, exact requested Pi version, the provider/model/settings smoke, unchanged non-secret rendered configuration, and the complete persistence-mount fingerprint.

Recovery, rollback, and maintenance cleanup

Recovery state and lock diagnostics live under:

<projectDirectory>/.thothctl/update-state.json
<projectDirectory>/.thothctl/update-state.json.lock.owner.json

The recovery file is mode 0600 and records transaction-scoped image identities, mount fingerprints, target version/source, configuration digest, phase, and timestamp. It contains no credentials, endpoint values, secret paths, Compose output, or logs. A cross-platform OS advisory file lock serializes lifecycle operations; a crashed owner releases the lock automatically. Owner metadata is diagnostic only and cannot wedge acquisition if empty, partial, or stale.

Any post-candidate failure explicitly confirms or reactivates maintenance and rescans sessions before compensation. Automatic rollback selects the transaction's previous image through the lifecycle override and clears maintenance only after the previous image, configuration, mounts, health, Pi smoke, and terminal recovery write are verified. Ambiguous compensation remains gated.

For an interrupted transaction, first run:

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

Inspect and clean a stale durable gate with:

thothctl --installation /absolute/path/thothii-installation.yaml pi maintenance status
thothctl --installation /absolute/path/thothii-installation.yaml pi maintenance recover --yes

maintenance recover refuses a pending transaction. For terminal or absent recovery state, it removes a stale lifecycle override, verifies the running installation when the gate is active, and only then removes the durable marker and reopens admission. If rollback or recovery fails, leave the marker in place, preserve update-state.json, repair the reported Docker/configuration issue, and rerun rollback or maintenance recovery.

Missing confirmation, invalid arguments, active sessions, and an interrupted transaction exit 2. Docker and verification failures exit nonzero with concise, redacted guidance. Direct read-only/log commands preserve the original Docker child exit code.