## Problem
uvloop 0.22.1 rejects the Python 3.14-only `eager_start` task keyword,
so every Telegram and Discord message fails on Unix. Removing the
keyword alone would let eager task factories execute claims before FCC
publishes task ownership. Fixes #1108 and fixes #1115.
## Changes
| Before | After |
| --- | --- |
| Claim tasks depend on `eager_start=False`, which uvloop does not
accept. | Claim tasks use the portable event-loop contract behind an
explicit ownership gate. |
| Task execution ordering depends on event-loop keyword support. | Task
execution begins only after FCC attaches the task and completion
callback. |
| Regression coverage exercises native asyncio only. | Regression
coverage exercises a restricted task contract, eager task factories, and
real uvloop. |
| The package version is 4.5.0. | The package version is 4.5.1 with a
refreshed lockfile. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR fixes messaging claim lau…
Give messaging clear exact subtree semantics (#1072)
## Problem
Messaging `/clear` did not follow the selected platform message
boundary. Reply clears preserved the selected user prompt, while
standalone clears preserved user-authored messages and could reset FCC
state outside the invoking chat.
## Changes
| Before | After |
| --- | --- |
| Reply `/clear` removed a logical conversation branch but retained the
selected message. | Reply `/clear` deletes the selected message and its
literal reply subtree, including the clear command. |
| Standalone `/clear` retained user prompts and voice notes while
resetting global messaging state. | Standalone `/clear` deletes every
tracked message and resets FCC state only in the invoking platform and
chat. |
| Trees recorded only logical execution parentage. | Trees separately
persist logical execution ancestry and exact prompt/status reply
ownership. |
| Clear coordination used one global admission boundary. | Per-chat
clear generations coordinate admission, voice cancellation, persistence,
and bes…
Preserve user messages during messaging clear (#1068)
## Problem
Messaging `/clear` used one untyped collection for both internal reply
references and platform deletion targets. Clearing a branch or
cancelling a voice task could therefore delete the customer's prompt or
voice note along with FCC's own status and reply messages.
## Changes
| Before | After |
| --- | --- |
| Tree transitions exposed one message-ID set for repository unindexing
and platform deletion. | Tree transitions now separate internal
`reference_ids` from FCC-owned `clearable_message_ids`. |
| Reply and global clear deleted user prompts and voice notes with FCC
output. | Clear removes FCC statuses, replies, notices, and the explicit
`/clear` command while preserving user-authored messages. |
| The persisted message log accepted ordinary inbound content. | The
clearable-message log accepts only FCC output and explicit clear
commands, and drops legacy user-content entries when loading. |
| Tests treated user-message deletion as successful cleanup. |
Deterministic and …
## Problem
Telegram's online notice was sent directly by the SDK runtime and its
message ID was discarded, so `/clear` could not delete it. Moving
delivery into the workflow also needs to keep slow sends from blocking
commands and prevent acknowledged notices from losing clear ownership.
## Changes
| Before | After |
| --- | --- |
| The Telegram runtime sent a transport-specific startup side effect. |
The platform declares a semantic notice intent that the application
gives to the workflow after transport readiness. |
| Startup delivery bypassed the persisted message log. | The workflow
renders and records each acknowledged notice in the same bounded log
used by `/clear`. |
| Serializing send and record held workflow state across platform I/O. |
A dedicated clear generation reserves publication, delivery runs outside
the state lock, and a short receipt finalizer commits or compensates. |
| Concurrent clear, cancellation, or record failure could leave a
delivered notice unowned. | Cl…
Use task status as the sole stop confirmation (#1065)
## Problem
Messaging `/stop` edited each affected task status to `Stopped` and also
posted a second success message. The duplicate confirmation added noise
even though the existing status already represented the terminal result.
## Changes
| Before | After |
| --- | --- |
| Successful active, queued, global, and bound-voice stops posted a
second confirmation. | Successful stops use the affected task status as
their sole success UI. |
| Stop commands returned an ambiguous integer or `None`. | A typed
`StopOutcome` carries the cancelled count and terminal status ownership.
|
| Statusless voice cancellation could become silent if confirmations
were removed unconditionally. | Statusless voice cancellation receives
one fallback confirmation. |
| A global stop could under-report work when any affected status was in
another chat. | The invoking chat receives one summary whenever any
affected status is outside its scope. |
| Zero-work global stops reported that zero requests were cancelled.…
Keep voice ownership continuous through admission (#1063)
## Problem
Pending voice ownership ended before workflow admission completed. A
concurrent reply or global stop/clear could miss the handoff and return
while transcribed work was still able to enter the tree.
## Changes
| Before | After |
| --- | --- |
| The registry released voice and status aliases before the workflow
callback finished. | The registry retains both aliases and an owned
child through callback completion or explicit cancellation and join. |
| Caller and nested cancellation could interrupt cleanup or form
recursive joins. | Completion-driven cleanup preserves cancellation
state and excludes current or actively cancelling claims. |
| Commands coordinated voice-registry and message-tree primitives. | The
workflow exposes typed reply and global stop/clear use cases that own
voice-to-tree synchronization. |
| Admission could be interrupted between tree mutation, processor
publication, and persistence. | One workflow-owned transaction validates
the epoch, admits work, publ…
Make application shutdown completion-driven (#1056)
## Problem\n\nShutdown could report success after bounded messaging
cleanup, hidden persistence failures, or failed managed-process stops.
An Admin restart could then construct a replacement while the old
runtime still owned work.\n\n## Changes\n\n| Before | After |\n| --- |
--- |\n| Runtime reused bounded interactive stop semantics for terminal
messaging cleanup. | Workflow close cancels work, stops managed
sessions, awaits every claim and recovery task, then flushes
persistence. |\n| Explicit persistence failures were logged and treated
as successful writes. | Explicit flushes and authoritative writes
propagate failure and stay dirty for retry; timer writes remain best
effort. |\n| Managed sessions and aliases were removed before subprocess
termination was confirmed. | Manager and session terminal states prevent
reuse, retain failed owners and PIDs, reject ID collisions, and retry
exact sessions. |\n| Admin restart followed the restart request even
after incomplete shutdown. | Superv…
## Problem
Reply-scoped `/clear` could miss a voice note during status delivery or
race its final handoff. It could report cancellation while the
transcription still executed or later emitted a contradictory error.
## Changes
| Before | After |
| --- | --- |
| Pending state appeared only after status delivery. | The flow reserves
an opaque claim before any status I/O. |
| Pending checks and removal were separate transitions. | One
registry-locked handoff claim is exclusive with cancellation. |
| Cancellation always assumed a status message existed. | Cancellation
returns the voice ID with an optional bound status ID. |
| Stale flows could mutate reused IDs or report late failures. | Exact
claim IDs reject ABA updates and make late canceled work cleanup-only. |
| Race coverage exercised only ordinary transcription cancellation. |
Deterministic tests cover pre-bind cancel, handoff races, stale claims,
and late failures. |
| The architecture documented registration but not ownership tr…
Replace historical architecture tests with declarative boundaries (#1050)
## Problem
Architecture contracts mixed real dependency rules with deleted-module
tombstones and exact internal file inventories. Correct refactors
therefore had to preserve history instead of the current ownership
model.
## Changes
| Before | After |
| --- | --- |
| Cross-package rules were duplicated across narrow source and layout
assertions. | One least-privilege matrix and AST scanner enforce every
production package edge. |
| Bare imports, undeclared ownership roots, and module cycles could
escape generic enforcement. | Namespaced imports, initialized owners,
exact exceptions, and an acyclic module graph are enforced. |
| Responses, messaging-tree, and optional dependency ownership relied on
scattered checks. | Facade use and lazy optional dependency owners are
declared and verified centrally. |
| The messaging facade re-exported workflow, persistence, and parsing
internals. | The messaging facade exposes only ingress values, platform
ports, and managed-session protocols. |
| …
Make messaging trees atomic ownership boundaries (#1048)
## Problem
Messaging tree state, queue coordination, task ownership, and
persistence were jointly mutated across several classes. Raw message IDs
were treated as globally unique, allowing cross-chat collisions and
unsafe cancellation or clear ordering.
## Changes
| Before | After |
| --- | --- |
| Managers and processors coordinated partial tree mutations through
exposed locks and mutable nodes. | MessageTree owns atomic transitions
and returns detached effects to task, UI, and persistence owners. |
| Raw message IDs and task identities could collide across chats or
detached generations. | Scoped tree identities and opaque claim IDs
isolate chats and reject stale task writes. |
| Session snapshots duplicated graph links and retained ingress
payloads. | Lean scoped snapshots rebuild validated indexes and continue
reading existing session files. |
| Stop, clear, and runner persistence could interleave across commit
boundaries. | Admission epochs, cancellation-safe detach, and
authorit…
Canonicalize provider failure and retry ownership (#1046)
## Problem
Provider SDK classification, retry policy, canonical failures, and
downstream wire errors shared exception types across layers. That
blurred ownership and let cleanup or provisional Responses tool failures
mask the real provider diagnostic.
## Changes
| Before | After |
| --- | --- |
| Provider failures carried Anthropic wire types and core code
classified OpenAI/httpx errors. | Protocol-neutral `ExecutionFailure`
values cross layers, providers classify SDK errors, and protocol
packages map wire types. |
| Provider adapters could author terminal wire events. | The HTTP commit
boundary selects non-2xx JSON or a protocol terminal event with one
ingress request ID. |
| Retry policy and diagnostic handling were spread across core and
provider modules. | Providers own the unchanged retry budgets while
neutral core utilities own bounded credential redaction. |
| Stream cleanup could replace an already-mapped provider failure. |
Cleanup records safe metadata and preserves the ca…
Replace global runtime resources with explicit ownership (#1042)
## Problem
Provider, messaging, and transcription resources relied on
process-global state, leaving replacement, cancellation, and shutdown
ownership ambiguous. Separate server lifetimes could share
event-loop-bound resources or retain failed cleanup work.
## Changes
| Before | After |
| --- | --- |
| Provider clients found limiters through global singleton and scoped
registries. | Each provider instance receives and owns one explicitly
constructed limiter. |
| Messaging queues and voice pipelines relied on singleton or
module-global state. | Each platform owns its limiter and outbox, while
the application owns one injected transcriber. |
| Messaging shutdown mixed ingress, active work, delivery, and SDK
cleanup. | Application shutdown quiesces ingress, drains work, closes
delivery, then releases transcription and providers. |
| Cancelled or failed provider cleanup could be forgotten or treated as
complete. | The provider manager retains shielded generation and
unpublished-runtime c…
Establish single-owner runtime with stream-safe provider hot swaps (#1036)
## Problem
Provider runtime ownership was split between lifecycle code and mutable
FastAPI state, so Admin replacements could leak the new runtime,
double-close the old runtime, or close providers still serving active
streams. The API package also owned concrete process composition,
obscuring subsystem boundaries.
## Changes
| Before | After |
| --- | --- |
| FastAPI routes inspected several concrete `app.state` resources. |
FastAPI receives one explicit `ApiServices` boundary and stores only
`app.state.services`. |
| Admin Apply persisted config and directly replaced one runtime
reference. | Admin Apply validates a candidate, commits atomically, and
publishes it through the single runtime owner. |
| Provider replacement could close clients used by active streams. |
Generation leases retain old providers until each streaming or
non-streaming response finishes. |
| Provider generations owned discovery state and model metadata. |
`ProviderRuntimeManager` owns one application-lifetime …
Move runtime packages under src namespace (#1029)
## Problem
Runtime modules were published as generic top-level packages like `api`,
`cli`, and `providers`. That shape is fragile for PyPI packaging and
weakens explicit ownership boundaries.
## Changes
| Before | After |
| --- | --- |
| Runtime code lived in root-level packages. | Runtime code lives under
`src/free_claude_code/`. |
| Console scripts targeted top-level modules. | Console scripts target
namespaced modules. |
| Tests and smoke helpers imported old package roots. | Tests and smoke
helpers import `free_claude_code.*`. |
| Packaging listed six root packages. | Packaging builds the single
namespaced package. |
| Contracts allowed old root package directories. | Contracts require
the src namespace and reject old root imports. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR moves the runtime packages into the `src/free_claude_code`
namespace. The main changes are:
- Console scripts now point to `free_claude_code.*` entrypoi…