Yoetz v0.2.5 — session recovery and setup fixes

This patch in the 0.2 public-alpha line improves session recovery, setup, observation reporting,
and completion checks across the existing Codex, Claude Code, and Cursor integrations. It includes
the fixes on main after v0.2.4; richer task interaction remains outside this release.

Changes

• Reattach an exact known session even when independent tasks share the workspace. Automatic
  recovery retains task identity, workspace fences, and admission checks (#811, #815).
• Recover cold hook attachment within host budgets and expose capture recovery, delivery loss,
  quarantine, and pending-operation state more clearly (#790, #792).
• Report differences between a completion claim and the effective plan, and prevent unrelated
  command gaps from invalidating otherwise qualifying finding-repair proof (#793, #794).
• Preserve setup approvals and inspect the selected installation. Identify Linux Cursor IDE
  installations without launching them (#795, #796).
• Fit Claude's startup instructions within its observed MCP rendering limit while retaining
  recovery guidance and reporting plugin-managed versus bare MCP registration (#791).
• Offer opt-in required startup for native Claude and Cursor plugins, with owner controls,
  scope-bound plan checks, and same-task pending-operation recovery (#797).
• Add unattended dogfood CI for Codex, Claude, and Cursor Agent CLI on macOS arm64, Linux x86-64,
  and Ubuntu under WSL 2 (#803).

Verification and limits

Release issue #801 tracks the exact release
revision and the package, CI, dogfood, and publication gates; results are added as each gate
completes. Tagged Release
publishes the tested Python and npm artifacts and attaches checksums, an SBOM, and release
evidence to GitHub. The public protocol namespace remains 0.1; previously released schema bytes
remain unchanged.

The pre-version source revision 2e3268340a6d2866d8ae1383fd70b2109ee01a0f passed
CI and all nine
dogfood lanes. Each lane
reported a successful native session with task mapping, a drained observation queue, and
successful AI-powered review both before and after service restart. Those runs used development
packages still numbered 0.2.4; the release issue separately records checks of the 0.2.5 candidate.

These are bounded installation, ledger, observation-delivery, and recovery checks, not a claim of
complete recording or correctness. Transient hook/drain budget diagnostics remain visible even
when final queues drain. The hosted macOS Claude lane uses --plugin-dir; the macOS Cursor lane
uses MCP only and does not establish hook activation. Native macOS approval dialogs, full desktop
activation, Windows-side Cursor Remote WSL, and comprehensive retained-content coverage are not
established by this matrix. See dogfood CI and
required startup for the precise acceptance boundaries.

Supported platform claims remain macOS arm64 and glibc Linux x86-64, including Linux under WSL 2.
Native Windows remains unsupported; Linux arm64 remains an explicitly untested platform cell.
OS identity checks, repository trust, observation consent, and provider disclosure permissions
remain separate requirements.

Yoetz v0.2.4 — consistent desktop installation

This patch in the 0.2 public-alpha line brings Codex, Claude Code, Cursor IDE and Cursor Agent
CLI into the same guided installation and connection lifecycle. It targets macOS, Linux and
Windows through WSL 2. Native Windows and mobile platforms remain unsupported.

Changes

• Discover executable-backed installations, offer a host selection, and retain the exact selected
  profile and project in the connection preview and continuation.
• Connect Claude's plugin installation and enablement in one reviewed operation. Configure the
  appropriate Cursor project binding while preserving unrelated configuration.
• Show installed, enabled/configured, reload-required and connection-observed state separately.
  Repeated setup can be a no-op; interrupted work remains inspectable and retryable.
• Disconnect both plugin activation and managed MCP registration, retain Yoetz data, and support
  reconnect through the same flow.
• Keep Linux/WSL PAM approval on the foreground thread. When terminal handover is unavailable,
  show the exact approved continuation instead of failing the TUI worker.
• Keep the selected runtime first in the host handoff's PATH, alongside explicit profile and
  isolated-instance bindings.

The version-report schema advances to 2.2.2 for the added host-connection contract. Released
2.2.1 and earlier schema bytes remain unchanged. The public protocol namespace remains 0.1.

Verification and limits

Issue #767 and
PR #788 record source, installation evidence,
review disposition and release status. Installation verification covers preview, apply, status,
repeat setup, disconnect and reconnect. Model-provider authentication and full model tasks are
outside this patch's requested acceptance scope. Configuration success does not assert a working
model session, complete observation, or AI-powered review.

The installed candidate uses the same wheel on macOS arm64 and Linux x86-64. The installation
matrix records configuration and lifecycle checks, not GUI/session activation:

Host	macOS arm64	Ubuntu 24.04 x86-64	Ubuntu 24.04 on WSL 2
Codex CLI 0.153.4	Passed	Passed	Passed
Claude Code 2.1.261	Passed	Passed	Passed
Cursor Agent CLI	Passed (2026.08.25)	Passed (2026.09.18)	Passed (2026.09.18)
Cursor IDE	Passed (3.20.0)	Passed (3.21.16)	Windows-side Remote WSL cell unverified

Each passed cell includes preview, install/connect, status, repeated no-op setup, disconnect and
reconnect using an isolated installed runtime. A real interactive Linux installation also passed
its confirmation and single password prompt. macOS uses the owner's real OS approval; Linux and
WSL use disposable local accounts and the real PAM console path. The Windows-side Cursor IDE
cell remains owned by the integration maintainer in #722; CLI evidence does not establish it.

Required OS identity checks, repository trust, observation consent, provider credentials and
disclosure permissions remain separate. Headless Linux/WSL without secure storage still uses
the supported passphrase route; this patch does not resolve every onboarding limit in #737.
The observation and platform limits recorded in v0.2.3 remain in effect.

Yoetz v0.2.3 — integration and session recovery fixes

This patch in the 0.2 public-alpha line repairs existing installation, transport, observation
and receipt behavior. The separate 0.3 feature line is unchanged.
Issue #786 records the tested artifacts,
maintainer release decision and remaining verification limits.

Repairs

• Privacy receipt list/get serialize stored timestamps and accept the existing local disclosure
  purpose without changing stored receipt bytes or the external-egress purpose grammar.
• Codex setup uses the selected Codex home for both plugin activation and MCP registration. When
  activation changes the effective MCP entry, the interactive wizard displays the refreshed
  preview for confirmation. Foreign entries and subsequent drift still refuse.
• Newer Codex transcript records retain their surrounding message when optional metadata contains
  fractional numbers. Compatibility parsing does not promote exact-version capability support.
• Cursor project registration writes the validated absolute project path. Cursor Agent CLI
  passes the IDE placeholder literally; the absolute path allows startup. Native roots and owned
  registration must still agree. Existing placeholder entries remain valid for IDEs and can be
  upgraded through an accepted preview.
• Transport send failures retain their retryability. Existing selected observations, protected
  reads and bounded routine summaries can cross local control without schema rejection.
• Routine-read classification retains its proven outcome. Older buffered groups that cannot
  qualify as summaries drain as their original individual records, preserving source order and
  their actual outcome limitations instead of blocking later hooks.
• Session attachment waits briefly for existing runtime users and yields a stopped busy-start
  lease without losing its durable identity. Exact-request retry guidance now reaches CLI and
  MCP. Optional background reviews yield to attachment, retain cancellation accounting, and
  release their runtime once even when multiple hosts reconnect. Observation ingestion also
  releases its runtime when optional final backlog feedback fails or is cancelled.

Request and result control schemas advance independently to 2.6.1. Released 2.6.0 schemas remain
byte-identical. The public protocol namespace remains 0.1; package versions are independent.

Verification and limits

The release is available as the Python yoetz package on PyPI, the version-matched yoetz launcher
on npm, and the GitHub release assets. The npm launcher requires uv and installs the same exact
Python version. Use uv tool install --python 3.14 yoetz==0.2.3 or npx yoetz@0.2.3.

Verification used independent installed test instances and synthetic workspaces. The final runtime
candidate passed full CI; independently built Mac and WSL wheels had identical bytes. The tagged
release workflow separately verifies its built artifacts before publication and downloads the
published distributions afterward.

Environment	Evidence	Scope limits
macOS arm64	Native Codex, Claude Code with Opus, and regular Cursor completed bounded work, local checks and receipts; Codex attached successfully in fresh and subsequent sessions.	Claude used the development plugin export. Cursor evidence covers candidate project MCP, not the pre-existing global hook plugin.
Linux x86-64	Ubuntu CI and earlier native Modal runs; exact revisions and receipts are retained in #786.	Earlier native runs precede the final session-cleanup repair. CI does not replace final-head native host acceptance.
Windows through WSL 2	Windows Server 2025, WSL 2.7.14.0 and Ubuntu 24.04: 153 focused tests, a real network-isolated approved check, service restart/unlock, full WSL terminate/restart with passphrase unlock, and refusal of state storage on /mnt/c.	Authenticated native Codex/Claude/Cursor runs were not completed. This is not Windows 11 desktop or native-Windows certification.

Known limitations retained in this release:

• Observation is bounded and may be incomplete. The final Mac Codex default-capacity run reported
  eight unrecoverable observations and an overflow diagnostic; a larger-capacity follow-up reported
  seven additional losses. Both queues drained. Different native calls and a reused task prevent a
  controlled causal comparison; increasing capacity is not a promise of lossless capture.
• One follow-up MCP dry run timed out and its recovery read returned frame_invalid. The exact
  replay recovered; a fresh connection could inspect the operation. #786 retains this sequence
  for follow-up rather than treating it as a clean transport run.
• Strict/private test routes deliberately blocked AI-powered review. Their receipts remain
  coverage-limited. Optional hook advice can describe this policy ceiling as a provider-readiness
  problem; the typed check result is authoritative.
• Cursor Agent CLI 2026.09.18-9a7762b needs explicit registered-project binding because it does not
  provide matching MCP roots/list. Desktop retains mandatory roots binding. Linux CLI results do
  not establish Linux desktop behavior.
• Headless Linux/WSL without an approved credential backend uses explicit passphrase setup and
  unlock. Keep state on the Linux filesystem, never a Windows-mounted drive. Easier onboarding
  remains tracked in #737.
• First-run setup connects Codex only. Claude Code and Cursor installation remain separate;
  multi-host first-run setup is tracked in #767 and is outside this patch.

The maintainer approved publication with these limits after reviewing the recorded tests. This
release does not claim complete observation, AI-powered verification, or universal host/platform
readiness. Native coverage follow-ups remain open in #786.

Yoetz v0.2.2 — install paths that work on any machine

Yoetz 0.2.2 is a patch release in the 0.2 public-alpha line. It removes the ways a
fresh install could fail or mislead: the website's PyPI button named a version that did not
exist, npx yoetz bound agent connections to a cache that uv may prune, the prompt-loop
first run could crash, and setup asked people to type a Codex home path by hand. It also ships
typed recovery directives on public errors (#743) and the product-wording pass (#773) that merged
after 0.2.1. Nothing about the ledger, checks, receipts, or the wire schemas changes; this release
is about getting to first run and past the first error (#766).

Python and npm packages both use 0.2.2. The public protocol namespace remains 0.1;
package releases and immutable wire-schema versions advance independently.

Highlights

• Any machine, any Pythons. The documented command,
  uv tool install --managed-python --python 3.14.6 yoetz, downloads the exact Python 3.14 it
  needs and is unaffected by pyenv, Homebrew, system, or project Pythons. The docs now say so,
  name the two uv settings that block the download, and say that pip or pipx on an older
  Python cannot install Yoetz (#766, #768).
• npx yoetz connections survive uv cache clean. The npm launcher makes the exact version a
  persistent uv tool install first (a no-op once present) and then runs that installed
  environment, so hooks and MCP entries bind a launcher that stays where it is. The launcher
  still bundles and downloads nothing itself (#766, #768).
• The website's install buttons work. The PyPI button is unpinned, so it can never name a
  release PyPI lacks again; both popups say uv is required and give its one-line installer
  (#766, #770).
• Setup asks less. The Codex home is offered from CODEX_HOME or ~/.codex for confirmation,
  yoetz setup run --codex-path works without --codex-home, the prompt-loop first run opens the
  wizard instead of exiting internal_error, each Codex installation is listed once, and a
  console script that cannot prove itself reports launcher_unproven (#766, #768).
• Errors say what to do next. A public error on the MCP or CLI surface carries a typed
  continuation token, and each surface renders the directive, guidance pointer, and nudge from a
  checked-in registry, so a flow such as vault_initialization_required no longer dead-ends an
  agent. Directive text never travels on the wire, so the egress fence is unchanged
  (ADR-030;
  #739, #740, #669, #743).
• One vocabulary. Receipts, the terminal interface, CLI and MCP descriptions, guidance, skills,
  and docs all say "local checks" and "AI-powered review"; the
  product vocabulary table
  maps those words to the unchanged wire identifiers (#769, #773).

What this release does not claim

• First run still connects Codex only. Claude Code and Cursor are connected afterwards with
  yoetz integrate claude ... and yoetz integrate cursor ...; detecting and connecting them
  during first run is tracked as #767.
• yoetz 0.0.1 on PyPI is a name reservation. Until it is yanked, pip or pipx on a
  Python older than 3.14 can still resolve it and install nothing usable (#771).
• Everything listed under "What this release does not claim" in
  v0.2.1
  still applies: real WSL 2 is untested, Linux Claude Code and Cursor native-host acceptance is
  incomplete, and privacy-receipt CLI bugs #731 and #732 remain open. See
  docs/public-claims.json
  and
  docs/OPEN_QUESTIONS.md.

Install

uv tool install --managed-python --python 3.14.6 "yoetz==0.2.2"

For a one-off run: uvx --python 3.14 "yoetz==0.2.2". With uv already installed:
npx yoetz@0.2.2 (the npm package is a dependency-free launcher that makes the same persistent
uv tool install of the exact PyPI distribution).

Release integrity

Verify the artifacts against the attached SHA256SUMS, NPM_SHA256SUMS, SBOM, support matrix,
known limitations, release-evidence bundle, and VERIFY.md.

Full changelog

Curated notes above; the complete list of merged changes since v0.2.1:

• #743: typed recovery directives on MCP
  and CLI error surfaces (ADR-030).
• #768: make the documented install paths
  work and stop asking for typed paths.
• #770: unpin the landing page's PyPI
  install command and say what uv does.
• #772: prepare the 0.2.2 release.
• #773: say "local checks" and
  "AI-powered review" everywhere people read.
• Product Hunt featured badge on the website's hero (direct commit).

Compare: v0.2.1...v0.2.2

Yoetz v0.2.1 — Linux and WSL compatibility fixes

Yoetz 0.2.1 is a patch release in the 0.2 public-alpha line. It fixes significant bugs
that rejected Linux and WSL subscription review and native plugin approval, improves platform
and storage diagnostics, and repairs privacy-receipt service reads. It also includes the complete
0.2 baseline: Codex, Claude Code, and Cursor integrations, bounded observation, session recovery,
and guided upgrades. The prepared 0.2.0 candidate was not tagged or published; 0.2.1 supersedes it.

Python and npm packages both use 0.2.1. The public protocol namespace remains 0.1;
package releases and immutable wire-schema versions advance independently.

Highlights

• Linux subscription review can start. Codex subscription setup now selects the exact
  Linux x86_64 evaluator cell instead of rejecting it with codex_runtime_platform_unsupported.
  WSL 2 Linux userspace uses that path; actual WSL acceptance remains untested. macOS arm64
  keeps its own cell, and a mismatched binding fails before launch (#716, #717).
• Linux plugin approval uses PAM. Cursor and Claude Code plugin lifecycle operations can
  request the invoking Linux account's password at a trusted terminal. A disposable worker
  bounds PAM work; cancellation, timeout, missing-console and failed-authentication paths stay
  closed. Preview names the mechanism and platform. This implementation includes WSL Linux
  userspace, but does not establish completed native-host or WSL acceptance (#719, #726).
• Platform failures explain the next step. Linux and WSL diagnostics distinguish sandbox,
  credential-store, filesystem and runtime-cell facts. Native Windows receives an explicit WSL
  path instead of an opaque stateful-command error; installation guidance tells users which
  side of Windows runs each command (#709, #710, #720–#725, #727).
• Reviewer usage survives restart. Subscription reviewer token usage is persisted with its
  attempt and provenance. Missing usage is not invented, and historical events keep their
  original shape (#715, #718).
• Privacy-receipt service reads are registered. Ordinary control clients can retrieve and
  list receipts, and the catalog decodes network-egress receipts. Two remaining CLI rendering
  and local-receipt schema defects are called out below (#730, #729).

What this release does not claim

• Real WSL 2 has not been tested. Ubuntu x86_64 evaluator smoke demonstrated device login,
  login reuse, two Luna/high semantic reviews, usage, service restart/unlock, provenance,
  production-client network-receipt reads, logout and rollback. It does not establish WSL
  mount behavior, distribution shutdown/relaunch, networking or sandbox-policy acceptance.
• Linux Claude Code and Cursor native-host acceptance remains incomplete. Scripted PAM
  evidence and an evaluator smoke run do not prove a human-authorized plugin lifecycle,
  native model use, observation coverage or clean workflow closure (#719, #722).
• Two privacy-receipt CLI bugs remain open: datetime rendering can crash (#731), and a
  local-receipt purpose can violate the control schema and break listing (#732). The service
  read repair does not mean every advertised receipt CLI path succeeds.
• The package version does not widen the supported-cell allowlist or erase evidence gaps.
  See the public claims,
  release-gate ledger
  and Linux/WSL runbook.

Install

uv tool install --managed-python --python 3.14.6 "yoetz==0.2.1"

For a one-off run: uvx "yoetz==0.2.1". With uv already installed: npx yoetz@0.2.1.
The npm package delegates to the exact Python version. Existing users can run yoetz upgrade
for package, migration and host-refresh guidance; replacing the package alone does not activate
new plugin bytes in an already-running host.

Release integrity

The tagged workflow builds and tests one candidate, publishes those exact Python and npm bytes,
and compares registry downloads with the candidate. Its release assets include SHA256SUMS,
NPM_SHA256SUMS, SBOM, capability and support matrices, known limitations, the release-evidence
bundle and VERIFY.md. Consult the actual attached evidence for the tested cells and outcomes.

Full changelog

• #704: landing setup guidance.
• #705: current-candidate release verification.
• #708: landing layout and installation clarity.
• #710: platform-aware agent installation guide.
• #713: mobile landing layout and explicit
  experimental Linux/WSL platform wording.
• #729: integrates #717, #718, #726 and #727,
  plus the privacy-receipt control/catalog repair.
• 0.2 baseline notes:
  the earlier changes included in this release, with their per-PR references.

Full changelog from the last public tag.

Yoetz v0.1.0 — public alpha

Yoetz v0.1.0 — public alpha

Yoetz v0.1.0 is the first usable public release: a local-first evidence ledger and review engine
for agent work. It records bounded facts that participants publish, checks that record with
versioned policy packs, and produces receipts whose wording stays inside the evidence actually
available.

Highlights

• A six-operation protocol: start, publish_work, check, respond, status, and
  receipt, with the same contracts over CLI and MCP.
• Local-first trust: one per-user service owns keys, decrypted state, SQLite writers, privacy
  policy, and provider dispatch. CLI, MCP, and the terminal interface are bounded clients.
• Honest completion receipts: coverage, provenance, freshness, findings, and limitations remain
  separate. A clean deterministic check is never presented as proof that work is correct.
• A full-screen terminal experience: first run, status, privacy, provider, integration, service,
  and receipt flows share one interface without moving confidential input into the UI.
• Privacy-gated semantic review: optional model review stays behind explicit provider binding,
  reauthenticated policy authority, minimization, secret scanning, and durable egress receipts.
• Codex integration without inflated claims: Yoetz ships Codex skill, plugin, MCP, hook, and
  observation machinery, but v0.1.0 deliberately advertises no tested Codex version or capability
  profile. Installation or registration alone is not support evidence.
• Recoverable local durability: encrypted task bundles, generation-fenced SQLite writers,
  backup/restore, forward-only migrations, and explicit operational recovery surfaces.

Install

The canonical package is the Python distribution:

uv tool install --managed-python --python 3.14.6 "yoetz==0.1.0"
yoetz

For a one-off run:

uvx "yoetz==0.1.0"

Or, when uv is already installed:

npx yoetz@0.1.0

The npm package is a dependency-free launcher. It bundles no Python and no Yoetz implementation;
it delegates unchanged arguments and terminal I/O to uvx yoetz==0.1.0.

What the alpha does not claim

• It has not received the two independent threat reviews required for the first non-alpha release.
• It publishes no verified Codex-version, hook-observation, provider-endpoint, keyring/platform, or
  structural subject-capture support cell where release-bound evidence is absent.
• It makes no support-mailbox availability or response-time promise.
• On Linux, approved external-command checks fail closed in v0.1.0 because the bubblewrap launch
  profile is not release-certified. Built-in deterministic checks and the ledger remain available;
  Yoetz does not claim that an external command ran when its sandbox boundary is unavailable.
• It does not claim bit-for-bit reproducible Python archives, package signing, or broad platform
  support beyond the exact release jobs and artifacts that passed.
• Semantic output is advisory. Yoetz records challenges and provenance; it does not replace code,
  security, or maintainer review.

These are bounded release statements, not fine print. The exact claim inventory and dated
dispositions are in
docs/public-claims.json
and
docs/OPEN_QUESTIONS.md.

Release integrity

The tag workflow builds each distribution once, tests the candidate artifacts, records SHA-256
checksums and build provenance, assembles the release evidence and capability matrices, then
crosses dedicated publication environments. PyPI publishes first. npm then publishes the exact
approved launcher tarball through trusted publishing. The GitHub release attaches both candidates
and the evidence bundle. Post-publication jobs download the public artifacts and compare them to
the approved bytes. The immutable schema tree is deployed from the exact candidate before tagging
and the workflow re-fetches every hosted file for byte comparison.

Inspect the attached SHA256SUMS, npm checksum file, candidate manifests, SBOM, support matrix,
known limitations, and release-evidence bundle alongside the wheel, source archive, and npm
tarball.

Security and support

Report vulnerabilities through GitHub private vulnerability reporting, with
support@yoetz.dev as the fallback. Use repository issues for ordinary bugs and support. See
SECURITY.md and
CODE_OF_CONDUCT.md.

Full changelog

This first public alpha has no previous usable release to compare against. The complete feature,
fix, privacy, durability, integration, and upgrade notes are in
CHANGELOG.md.