Therapist v0.3.1 — diagnosable local-server failures

Therapist v0.3.1 — diagnosable local-server failures

Therapist v0.3.1 is an experimental, free, non-commercial, adult-only self-hosted alpha for
technical contributors and informed self-hosters. It is AI for private self-reflection, not therapy,
diagnosis, medical advice, emergency care, clinical validation, or human monitoring.

Install or update

macOS or Linux:

curl -LsSf https://raw.githubusercontent.com/matteodante/therapist/main/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/matteodante/therapist/main/install.ps1 | iex"

The installer pins the immutable v0.3.1 source, replaces an earlier isolated thera tool, runs
guided setup, and finishes with thera doctor. It preserves local application files and the shared
embedding-model cache.

Upgrading from v0.3.0 or v0.2.0

The storage schema is unchanged and stays at version 3, so an existing data directory keeps working
without migration. Reinstall the background Telegram service after updating.

What changed

On macOS 15 and later, a Telegram listener installed as a launchd agent could not reach a local:
server on the operator's own network, while the same binary reached it from a terminal. Apple grants
local network access to command-line tools and to launchd daemons, but explicitly not to launchd
agents (TN3179, Understanding local network privacy). The block arrived as EHOSTUNREACH inside
the provider SDK, so the listener stayed responsive on Telegram, logged nothing unusual, and told the
user only that it could not respond.

thera doctor now reports the configured local: endpoint and names this cause when the failure is
EHOSTUNREACH, keeping other connection failures distinct. The operator resolves it by exempting the
server's address from local network privacy, which requires a restart:

sudo defaults write com.apple.network.local-network AllowedWiFiLocalNetworkAddresses -array "<ip>/32"
sudo defaults write com.apple.network.local-network AllowedEthernetLocalNetworkAddresses -array "<ip>/32"

Prefer a single address over a whole subnet: that preference removes the protection for every listed
address for every program on the machine.

Two changes make such failures diagnosable at all. The Telegram listener now logs a model error's
message and underlying exception instead of the class name alone, which could not separate a refused
request from a dropped connection; the text is bounded so a provider cannot echo conversation content
into the log. The background service now runs with PYTHONUNBUFFERED, because its output goes to a
file where Python block-buffers it, and diagnostics were lost on every restart.

No conversation, memory, protocol, or storage behavior changes in this release.

Provider and data flow

Unchanged from v0.3.0. The supported inference configuration remains a personal ChatGPT account
through the experimental codex: OAuth provider and gpt-5.6-sol. A local: server on the
operator's own hardware receives model input without reaching a third-party provider; embeddings and
encrypted application state stay local in every configuration.

Verification and artifacts

The candidate passed the deterministic suite, branch-coverage floor, Ruff, ty, protocol hash
validation, installer checks, wheel installation, package metadata checks, and the locked dependency
audit. The behavior pack and its protocol root hash are byte-identical to v0.2.0, and the supported
inference configuration is unchanged, so the live evaluations recorded for v0.2.0 remain the
current evidence for that configuration. They were not re-run, and this release adds no protocol,
prompt, or memory change that they would have exercised differently.

The local: provider still has no live evaluation of any kind, and carries no support claim.

The GitHub prerelease attaches the built distributions, SHA256SUMS, a locked-runtime CycloneDX
SBOM, and GitHub/Sigstore provenance and SBOM attestations.

Known limitations and rollback

The protocol is experimental, has no clinical review or efficacy evidence, and may respond poorly.
A self-hosted model chosen through local: is unevaluated here and may be far weaker on refusal and
safety behavior than the evaluated configuration. There is no confidential project-specific conduct
inbox, second administrator, hosted support, or deletion control over provider, Telegram, plaintext
export, backup, or terminal copies. A real Telegram message round-trip remains undocumented as a
recorded gate, though the fix above was confirmed against a live bot.

To roll back, reinstall v0.3.0 or v0.2.0: the storage schema is unchanged across all three, so
they accept the same data directory. For a material release defect, the prerelease will be marked
withdrawn and the installer channel moved forward to a fixed tag.