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.

Therapist v0.3.0 — self-hosted model provider

Therapist v0.3.0 — self-hosted model provider

Therapist v0.3.0 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.0 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.2.0

This release does not change the storage schema, which stays at version 3. A v0.2.0 data directory
keeps working and needs no migration, export, or deletion. The clean-break rejection still applies to
a store from an older or unknown schema.

Reinstall the background Telegram service after updating. The service definition now records the
model endpoint, and a definition written by v0.2.0 does not carry it.

What changed

A local: provider reaches any OpenAI-compatible chat-completions server, so a conversation can run
on hardware the operator controls. THERA_LOCAL_BASE_URL selects the endpoint and defaults to
http://localhost:8080/v1; THERA_LOCAL_API_KEY is sent only when set. Guided setup lists whatever
models that server advertises and offers them before the ChatGPT path; when no server answers, only
the ChatGPT path appears. Requests ask for xhigh reasoning effort, which servers without that field
ignore. The existing codex:, openai:, ollama:, and API-key paths are unchanged.

Installing the Telegram background service now records the resolved endpoint in the LaunchAgent's
EnvironmentVariables or the systemd unit's Environment= settings. A background service does not
inherit an interactive shell profile, so without this the listener silently fell back to loopback and
lost a local: server hosted elsewhere. Environment names and values containing control characters
are rejected rather than written into a unit file. THERA_LOCAL_API_KEY is deliberately not recorded,
because these definitions are plaintext on disk.

Reinstalling the macOS service over a running job no longer fails with Bootstrap failed: 5: Input/output error. launchctl bootout returns before launchd finishes unloading, and the immediate bootstrap hit
a label that was still held, leaving a written plist and no running job; install now waits for the
label to be released.

Provider and data flow

The supported first-alpha inference configuration remains a personal ChatGPT account through the
experimental codex: OAuth provider and gpt-5.6-sol. OpenAI documents ChatGPT authentication for
official Codex clients, not this independent direct-backend integration. The path may change or stop
working, is not the OpenAI API, implies no OpenAI endorsement, and must not be used for SaaS.

With the supported configuration, conversation content, selected bounded context, successful session
history, and any dynamically loaded skill are sent to ChatGPT for inference. With a local: server on
the same device, no conversation content is intentionally sent to a remote model or transport; with a
local: server on another host of the operator's own network, that same model input crosses that
network to hardware the operator controls and reaches no third-party provider. Embeddings and
encrypted application state remain local in every configuration. Telegram additionally receives
transported messages when enabled. There is no hosted Therapist service, publisher-operated
inference, product telemetry, or normal publisher access to application data.

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 longitudinal-memory evaluation, bilingual
conversational role-plays, and three repeats of the bilingual safety suite recorded for v0.2.0
remain the current evidence for that configuration. They were not re-run for this release, and this
release adds no protocol, prompt, or memory change that they would have exercised differently.

The local: provider has no live evaluation of any kind. Every recorded role-play, memory, and safety
result was produced against codex:gpt-5.6-sol. Nothing is known about how a self-hosted model
behaves on the safety floors, and that path carries no support claim.

The GitHub prerelease attaches the built distributions, SHA256SUMS, a locked-runtime CycloneDX
SBOM, and GitHub/Sigstore provenance and SBOM attestations. Verify downloaded artifacts against
those release attachments.

Known limitations and rollback

The protocol is experimental, has no clinical review or efficacy evidence, and may respond poorly.
Codex subscription limits and compatibility can interrupt use. A self-hosted model chosen through
local: is unevaluated here and may be far weaker on refusal and safety behavior than the evaluated
configuration; treat that path as an escape hatch you assess yourself. 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
is still undocumented.

To roll back, reinstall the v0.2.0 tag. The storage schema is unchanged between these two
versions, so that binary accepts the same data directory. Do not point either binary at a store from
an older or unknown schema. For a material release defect, the prerelease will be marked withdrawn
and the installer channel moved forward to a fixed tag.

Therapist v0.2.0 — longitudinal memory alpha

Therapist v0.2.0 — longitudinal memory alpha

Therapist v0.2.0 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.2.0 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.

Clean-break warning

This release intentionally has no schema migration or legacy compatibility layer. A store from an
older or unknown schema is rejected without modification. Before replacing an older installation,
retain any export and the old local store separately if you need them, then use a fresh data
directory or deliberately delete the incompatible store. Exports are plaintext and need separate
protection.

What changed

• Separated the root protocol, verified skill catalog, dynamically loaded skill body, successful
  model history, and bounded JSON case data.
• Expanded the experimental bilingual pack to fifteen process skills and added verified source
  bases for every skill. No reviewer or clinical validation is claimed.
• Rewrote the pack in positive, semantically routed form and specified an idiomatic conversational
  Italian register without fixed response templates.
• Replaced overloaded memory status with independent origin, fit, lifecycle, evidence relation,
  conflict, and staleness semantics.
• Added exact-evidence tools for reports, hypotheses, corrections, reviews, accepted focus,
  process preferences, interventions, outcomes, unwanted effects, and support choices.
• Enforced quoted-data polarity and grounded extractive restatement in both conversation tools and
  the durable store, including a dedicated accepted-focus persistence check.
• Added hybrid local semantic retrieval, complete encrypted model history, context-boundary session
  rollover, and end-of-session consolidation.
• Added standard, transcript-only, and ephemeral memory modes, optional retention, selective
  deletion, and user-visible memory inspection and correction commands.
• Added the full-screen Textual chat, cumulative streaming drafts, and native per-user Telegram
  background services for macOS, Linux, and Windows.
• Updated the pinned dependency set to exclude the cryptography PKCS#7 vulnerability fixed in
  50.0.0; Therapist does not use the affected PKCS#7 APIs.

Provider and data flow

The supported first-alpha inference configuration is a personal ChatGPT account through the
experimental codex: OAuth provider and gpt-5.6-sol. OpenAI documents ChatGPT authentication for
official Codex clients, not this independent direct-backend integration. The path may change or stop
working, is not the OpenAI API, implies no OpenAI endorsement, and must not be used for SaaS.

Conversation content, selected bounded context, successful session history, and any dynamically
loaded skill are sent to ChatGPT for inference. Embeddings and encrypted application state remain
local. Telegram additionally receives transported messages when enabled. There is no hosted
Therapist service, publisher-operated inference, product telemetry, or normal publisher access to
application data.

Verification and artifacts

The release candidate must pass the deterministic suite, branch-coverage floor, Ruff, ty, protocol
hash validation, installer checks, wheel installation, package metadata checks, locked dependency
audit, live longitudinal-memory evaluation, bilingual conversational role-plays, and three repeats
of the bilingual safety suite. The exact results and residual limitations are recorded in the
current release-readiness document.

The GitHub prerelease attaches the built distributions, SHA256SUMS, a locked-runtime CycloneDX
SBOM, and GitHub/Sigstore provenance and SBOM attestations. Verify downloaded artifacts against
those release attachments.

Known limitations and rollback

The protocol is experimental, has no clinical review or efficacy evidence, and may respond poorly.
Codex subscription limits and compatibility can interrupt use. There is no confidential
project-specific conduct inbox, second administrator, hosted support, or deletion control over
provider, Telegram, plaintext export, backup, or terminal copies.

To roll back, install a prior immutable tag only with the separate store that belongs to that
schema. Do not point an older binary at a v0.2.0 data directory. For a material release defect,
the prerelease will be marked withdrawn and the installer channel moved forward to a fixed tag.

Therapist v0.1.2 — guided setup fix

Therapist v0.1.2 — guided setup fix

This patch fixes the next guided-setup failure exposed after the macOS terminal correction in
v0.1.1. Therapist passed newly constructed Choice objects as defaults for yes/no prompts.
Questionary requires the default object to be present in the choices, so setup raised ValueError
when it reached the Telegram question.

All yes/no menus now share one helper that reuses the selected object from its actual choice list.
The macOS pseudoterminal fix from v0.1.1 remains included.

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"

For a reproducible installation pinned to this patch, replace main with v0.1.2 in either URL.
Re-running the installer preserves encrypted application data and the shared model cache.

Scope and safety

Therapist remains an experimental, single-adult-user, self-hosted AI agent for reflection. It is not
therapy, diagnosis, medical advice, emergency care, clinical validation, or human monitoring.
Supported alpha conversation uses the CLI or one private allowlisted Telegram bot with a personal
ChatGPT Plus/Pro account through experimental Codex OAuth.

Local archives, memory, credentials, and semantic indexes remain encrypted on the host. ChatGPT
receives the content and selected context required for inference; Telegram also receives transported
messages when enabled. There is no hosted Therapist service or product telemetry.

Verification

• A regression test constructs the real Questionary prompts through the supported setup path.
• Every yes/no default is checked by Questionary against its actual choice list.
• macOS CI retains the real prompt_toolkit pseudoterminal smoke test.
• The full deterministic suite, CI, CodeQL, dependency audit, packaging checks, CycloneDX SBOM,
  checksums, and build/SBOM attestations run on the release commit.

The experimental Codex backend and all limitations documented for prior alphas remain. Use synthetic
data in public issues and private vulnerability reporting for security reports.

[WITHDRAWN] Therapist v0.1.1 — use v0.1.2

Therapist v0.1.1 — macOS installer fix

Withdrawn: this release fixes the initial macOS terminal failure, but guided setup later
fails when constructing the Telegram selection prompt. Use v0.1.2 or later. The original
immutable artifacts remain available as release evidence.

This patch fixes guided setup when the macOS installer is launched through the documented
curl | sh command. Version v0.1.0 installed the application successfully but then reopened
/dev/tty directly; prompt_toolkit could not register that descriptor with macOS kqueue and
raised OSError: [Errno 22] Invalid argument.

The macOS bootstrap now runs thera setup inside a fresh pseudoterminal. Linux and Windows behavior
is unchanged. The README also provides one stable latest-alpha installer URL: running the same
command again installs the newest explicit release tag while preserving encrypted application data.

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"

For a reproducible installation pinned to this patch, replace main with v0.1.1 in either URL.

Scope and safety

Therapist remains an experimental, single-adult-user, self-hosted AI agent for reflection. It is not
therapy, diagnosis, medical advice, emergency care, clinical validation, or human monitoring.
Supported alpha conversation uses the CLI or one private allowlisted Telegram bot with a personal
ChatGPT Plus/Pro account through experimental Codex OAuth.

Local archives, memory, credentials, and semantic indexes remain encrypted on the host. ChatGPT
receives the content and selected context required for inference; Telegram also receives transported
messages when enabled. There is no hosted Therapist service or product telemetry.

Verification

• Regression test locks the macOS pseudoterminal launch path.
• macOS CI exercises a real prompt_toolkit prompt through the same PTY mechanism.
• Installer versions are checked against package and runtime versions.
• The full deterministic suite, CI, CodeQL, dependency audit, packaging checks, CycloneDX SBOM,
  checksums, and build/SBOM attestations run on the release commit.

The experimental Codex backend and all limitations documented for v0.1.0 remain. Use synthetic
data in public issues and private vulnerability reporting for security reports.

[WITHDRAWN] Therapist v0.1.0 — use v0.1.2

Therapist v0.1.0 — first public alpha

Withdrawn: the documented macOS curl | sh path installs the application but guided setup
then fails in prompt_toolkit. Use v0.1.1 or later. The original immutable artifacts remain
available as release evidence and must not be treated as the supported installer.

Therapist is an open-source AI agent for reflection, not code. This first alpha is for informed
adults running one private, self-hosted instance.

Experimental and not clinically validated. Therapist is an AI, not therapy, diagnosis,
medical advice, emergency care, or human monitoring. Its output can be wrong.

Install

macOS or Linux:

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

Windows PowerShell:

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

The bootstrap installs a managed Python 3.12 and the isolated thera command, then runs guided
setup and thera doctor. No existing Python, Git checkout, or administrator privileges are needed.

Included

• Italian and English conversation through the Textual CLI or one private, allowlisted Telegram
  bot.
• Experimental conversation inference through a personal ChatGPT Plus/Pro account using Codex
  OAuth.
• Encrypted local archive, evidence-linked longitudinal memory, local semantic retrieval, session
  consolidation, correction, forgetting, export, and deletion.
• Visible agent tool events and durable-change notices.
• A Git-versioned experimental transdiagnostic conversation protocol.
• Per-user Telegram background installation for macOS, Linux, and Windows.

Data flow

The local archive, structured memory, credentials, and semantic index remain encrypted on the host.
The personal ChatGPT provider receives the message, successful session history, and selected context
needed to answer. When Telegram is enabled, Telegram also receives transported messages and replies;
bot chats are cloud chats, not end-to-end encrypted. The repository maintainer receives no normal
application data and operates no hosted service or telemetry.

Read PRIVACY.md before use.

Release evidence

• Offline suite: 131 passed; branch coverage gate at 75%.
• Bilingual live safety evaluation: 10 scenarios, three repeats each, on codex:gpt-5.6-sol.
• Live longitudinal-memory evaluation passed.
• Private Telegram smoke test passed for privacy/status views, persistent text delivery, text-only
  media rejection, and avoidance of durable memory for an explicitly synthetic message.
• CI, CodeQL, OpenSSF Scorecard, dependency audit, packaging checks, SBOM generation, checksums, and
  build/SBOM attestations passed on the release commit.

The attached SHA256SUMS covers the wheel, source distribution, and CycloneDX runtime SBOM.
Attestations prove the GitHub-hosted build provenance; they are not a clinical or security
certification.

Known limitations

• The direct Codex backend is experimental, is not the OpenAI API, and may change or stop working.
• This is single-user software with a single maintainer and best-effort support.
• No SaaS, PyPI package, voice conversation, web UI, mobile app, group chat, webhook, clinical use,
  or minor use is supported.
• Telegram processing is not durably idempotent across every crash boundary.
• AI Act Article 50 output-marking requirements remain tracked against the documented 2026
  transition dates; no general regulatory-compliance claim is made.

Support, security, and withdrawal

Use GitHub Issues only with synthetic data.
Report vulnerabilities through
private vulnerability reporting.

uv tool uninstall therapist-cli removes the command but intentionally leaves local data. Run
thera delete-data first when local application records should also be removed. If this release is
withdrawn, its GitHub release page will carry a prominent warning and a fixed version will use a new
tag; published artifacts will never be silently replaced.