Cut private Telegram text over to Workshop delivery

[dcellison]

Summary

• cut authenticated private-chat plain-text replies with voice mode off over to durable Workshop finalization
• start and supervise one exact-authority-epoch Telegram finalization worker before accepting ingress
• bind confirmed streaming previews and atomically commit the canonical reply, delivery request, and immutable edit/send plan
• resolve ambiguous SQLite commit results deterministically and refuse duplicate direct fallback when resolution fails
• add operator authority status/deactivation commands and a concrete rollback contract

This is a production authority change

This PR crosses the first user-visible Workshop boundary. For an authenticated Telegram private text message, when canonical inbound recording succeeds and voice mode is off, the final reply is no longer finalized directly by the handler. The handler atomically commits durable Workshop delivery work and the supervised worker edits the streaming preview or sends the planned fragments.

The following paths remain unchanged:

• commands
• Telegram groups
• photos and documents
• voice messages
• text-plus-voice and voice-only output
• schedules
• GitHub and generic webhooks
• file delivery
• notification-group delivery

Startup and health

Production startup now:

1. opens a dedicated Workshop store connection for delivery;
2. transactionally resumes or creates the single conversation-delivery authority epoch;
3. recovers expired leases for that exact epoch;
4. starts the supervised finalization worker;
5. only then starts webhook or polling ingress.

Unexpected worker exit reaches Kai's fatal top-level path rather than leaving a loaded service unable to deliver replies. Shutdown stops ingress, cooperatively stops the worker, closes its dedicated store, and then closes the Telegram application and shared session database.

Handler authority and duplicate prevention

handle_message passes an explicit typed delivery route only when the Telegram chat ID equals the authenticated human's ID. _handle_response additionally requires:

• voice mode off;
• a successfully recorded canonical inbound message;
• the installed preview and finalization adapters.

After Telegram confirms a streaming-preview message ID, Kai binds it to the canonical inbound message without accepting a destination from the handler. On agent completion, the locked session adapter commits the canonical assistant message, exact-epoch outbox request, and immutable edit/send plan in one transaction.

Once that transaction is confirmed, the handler performs no direct final edit/send and writes no shadow delivery observation. The worker owns finalization.

If an SQLite error may have obscured the commit result, the adapter repeats the deterministic operation while the session write lock remains held. The retry either creates rolled-back work or observes the identical committed state. If the resolution attempt also fails, Kai sends only a bounded operational notice and refuses a direct resend that could duplicate committed work.

A definite preview-binding or finalization-preparation failure retains the current direct delivery path, preserving availability without creating two authorities for a confirmed outbox transaction.

Operator rollback

The implementation map records the rollback sequence. After stopping Kai and reconciling all aggregate delivery counts, the deployed database owner can inspect or deactivate authority with:

python -m kai workshop \
    delivery-authority \
    status

python -m kai workshop \
    delivery-authority \
    deactivate

Deactivation refuses pending, leased, or retry-wait work. Terminal failures require the explicit --acknowledge-terminal-failures option. No delivery work is deleted or reassigned, and a later activation creates a new epoch that cannot claim prior-epoch rows.

Tests

• make check
• make typecheck
• .venv/bin/python -m pytest -q

Result: 5404 passed, 1 skipped

Focused and integrated contracts cover:

• private-text route selection and group exclusion
• voice-mode exclusion
• preview binding and worker-owned final edit
• no handler direct send or shadow observation after durable commit
• definite preparation fallback
• unresolved commit fail-closed behavior
• deterministic SQLite outcome retry
• authority reuse across service restart
• startup recovery before worker readiness
• worker fault propagation and cooperative shutdown
• shared canonical writer plus dedicated worker connection finalizing one preview without a second send
• operator status and clean deactivation without exposing epoch identifiers

Installed verification after merge

This cutover remains pending installed qualification until the deployed system demonstrates a short streamed reply finalized in place without a second copy, an all-send reply, ordered fragmentation, restart recovery, clean aggregate authority counts, clean canonical/JSONL parity, and unchanged non-cutover paths.