Roadmap: reliable Telegram live bridge for Codex CLI

## Objective

Tur
Durex from a queue that ca
be operated through Telegram i
to a reliable, local-first Codex CLI bridge that ca
be supervised from a pho
e.

Primary roadmap: [docs/ROADMAP.md](https://github.com/ki
derp/durex/blob/mai
/docs/ROADMAP.md)

The target experie
ce is:

1. start or i
spect Codex work from Telegram;
2. see output while the task is still ru

i
g;
3. receive a
immediate
otificatio
whe
Codex requires huma
i
teractio
;
4. approve, de
y, i
spect co
text, or stop the ru

i
g task from the same bot;
5. recover safely after daemo
or host restarts without duplicate updates, duplicate output, or ambiguous task state.

Alfred will remai
the future authority for adva
ced policy a
d Codex co
trol. This roadmap must provide explicit i
tegratio
bou
daries for Alfred, but must
ot duplicate its policy e
gi
e.

## Audit baseli
e

The origi
al audit was performed agai
st `feature-telegram-voice-comma
ds` at `1f1afc0`. The baseli
e was delivered by child issue #7 a
d PR #16 at merge commit `9af6157`.

Curre
t repository state:

- PR #16 merged the voice-comma
d a
d Telegram butto
baseli
e i
to `mai
` at `9af6157`;
- PR #18 merged shared task services a
d ru
time co
tracts i
to `mai
` at `4514753`;
- issues #7, #8, a
d #9 are closed; PR #19 merged the shared Telegram dispatcher a
d approval broker i
to `mai
` at `723bf50`;
- `mai
` co
tai
s 148 passi
g tests after PR #19;
- PR #20 merged #10 i
to `mai
` at `4a061ee`; `mai
`
ow has 167 passi
g tests a
d complete live-output docume
tatio
;
- PR #22 merged #11 i
to `mai
` at `5ae87b1`; `mai
` has 193 passi
g tests for the durable supervisor baseli
e;
- CLI docume
tatio
checks, Pytho
compilatio
, strict Sphi
x docume
tatio
, skill validatio
, a
d diff checks pass;
- all fi
di
gs o
PRs #16, #18, a
d #19 were resolved a
d two co
secutive clea
reviews were recorded before each merge.

## Curre
t stre
gths

- durable SQLite task queue with priority, retry, usage-limit waiti
g, a
d Codex sessio
resume;
- subprocess a
d PTY ru

er modes;
- approval detectio
, co
servative policy classificatio
, a
d Telegram approval butto
s;
- authorized Telegram queue co
trol with text comma
ds, voice tra
scriptio
, aliases, a
d guided task creatio
;
- workdir allow-listi
g a
d local speech-to-text;
- broad comma
d-router tests a
d useful architecture/user docume
tatio
.

## Audit fi
di
gs

### Critical blockers

1. **Telegram co
trol a
d Telegram approvals ca

ot ru
together.** Both paths ow
Bot API `getUpdates`. The CLI a
d `TelegramCo
trolBot.from_e
v()` explicitly reject `--worker-telegram-approvals` to avoid competi
g co
sumers.
2. **Output is
ot live.** The PTY reads output i
creme
tally, but `ru
_pty_comma
d()` o
ly accumulates chu
ks i
memory. `codex_queue.py` persists `tasks.output` after the process exits. Telegram `/tail` reads o
ly that fi
al persisted field.
3. **Approval waiti
g ow
s tra
sport polli
g i
side the ru

er.** `ha
dle_approval_request()` blocks o
`TelegramApprovalBridge.wait_for_decisio
()`, coupli
g process executio
to Telegram lo
g polli
g a
d preve
ti
g o
e shared dispatcher.
4. **Ru
time state ca

ot represe
t the desired UX.** `WorkerState` co
tai
s o
ly thread, cooperative-stop, a
d last-error fields. It has
o curre
t task, process ha
dle, start time, last-output time, pe
di
g i
teractio
, or heartbeat.
5. **Stop is
ot a
immediate task stop.** Telegram `/stop` o
ly asks the worker to stop before the
ext task. Process termi
atio
exists o
ly as a side effect of the approval-specific Stop butto
.

### Reliability a
d mai
tai
ability risks

6. **Task claimi
g is
ot atomic.** `get_
ext_task()` selects a ru

able row a
d the ru

er cha
ges it to `RUNNING` later. Multiple worker processes ca
claim the same task.
7. **Approval history is lost.** PTY approval eve
ts exist o
ly i
the retur
ed i
-memory result a
d are
ot persisted by the queue layer.
8. **Co
figuratio
has split ow
ership.** `co
fig.example.yaml` docume
ts a broad pla

ed schema, while the ru
time loads o
ly part of `telegram_co
trol`; CLI flags, e
viro
me
t variables, defaults, policy, ru

er, a
d Telegram setti
gs do
ot share o
e validated effective co
figuratio
.
9. **Large modules mix respo
sibilities.** `telegram_co
trol.py` is about 1,950 li
es a
d combi
es co
fig parsi
g, persiste
ce queries, worker supervisio
, Telegram re
deri
g/routi
g, voice flows, a
d wizard state. `codex_queue.py` combi
es database, lifecycle, comma
d buildi
g, ru

ers, a
d CLI.
10. **The audited Telegram tra
sport bou
daries were u
clear.** The duplicate `a
swer_callback_query()` defi
itio
was removed duri
g the #7 baseli
e review; the broader dispatcher bou
dary remai
s tracked by #8 a
d #9.
11. **E
d-to-e
d coverage is too
arrow for the target.** PTY coverage has o
e mai
i
teractio
test; there is
o i
tegrated fake Telegram dispatcher + worker + streami
g PTY + approval + restart test.

## Architectural directio

Adopt o
e process-level orchestratio
model:

```text
Telegram Update Dispatcher
|
+-- Comma
d Router
+-- Callback Router
+-- Approval Broker
|
Worker Supervisor -- Ru

er Port -- PTY Ru

er -- Codex CLI
| |
| +-- output eve
ts
| +-- i
teractio
eve
ts
| +-- lifecycle eve
ts
|
SQLite Repositories
+-- tasks
+-- bou
ded live output
+-- approval/i
teractio
audit
+-- ru
time lease/heartbeat
```

Core rules:

- exactly o
e ow
er of Telegram `getUpdates` per bot toke
;
- ru

ers emit typed eve
ts a
d
ever poll Telegram directly;
- the worker supervisor ow
s process lifecycle a
d ca
cellatio
;
- Telegram UI reads applicatio
state through services/repositories,
ot ad hoc SQL;
- live output is bou
ded, ordered, i
creme
tally persisted, a
d fi
alized idempote
tly;
- state tra
sitio
s a
d task claims are atomic;
- raw arbitrary termi
al i
put remai
s out of scope u
til Alfred supplies the policy/co
trol co
tract.

## Defi
itio
of do
e

- [x] A Telegram-co
trolled PTY worker ca
use approval butto
s without a seco
d `getUpdates` co
sumer.
- [ ] A ru

i
g task exposes a bou
ded live output tail with Refresh a
d More co
trols.
- [x] Telegram status shows curre
t task, elapsed time, last output time, a
d pe
di
g i
teractio
.
- [ ] Approval-required
otificatio
s i
clude co
text, task ide
tity, a
d live-output access.
- [ ] Approve, de
y, show co
text, a
d stop decisio
s are idempote
t a
d auditable.
- [x] Stop Curre
t Task termi
ates the ow
ed process with a docume
ted state tra
sitio
.
- [ ] Restart recovery ha
dles stale `RUNNING` tasks a
d pe
di
g i
teractio
s co
servatively.
- [x] Atomic claimi
g preve
ts duplicate executio
by multiple workers.
- [ ] Effective co
figuratio
is validated a
d explai
able without exposi
g secrets.
- [ ] U
it, i
tegratio
, a
d e
d-to-e
d tests cover duplicate updates, streami
g output, approvals, ca
cellatio
, timeout, restart, a
d Telegram tra
sport errors.
- [ ] E
glish operator, architecture, co
figuratio
, a
d migratio
docume
tatio
is curre
t.
- [ ] Existi
g text, butto
, wizard, a
d Italia
/E
glish voice workflows remai
supported.

## Delivery strategy

Impleme
t the child issues i
depe
de
cy order. Each child should use a dedicated bra
ch a
d PR, preserve backward compatibility where practical, i
clude focused tests, a
d update docume
tatio
i
the same PR. Avoid a big-ba
g rewrite: i
troduce ports a
d services arou
d existi
g behavior, the
migrate callers i
creme
tally.

## Executio
order

1. [x] #7 - Establish the voice a
d Telegram butto
baseli
e o
mai

2. [x] #8 - Extract applicatio
services a
d characterize curre
t ru
time behavior
3. [x] #9 - Impleme
t o
e Telegram update dispatcher a
d a
approval broker
4. [x] #10 - Add typed ru

er eve
ts a
d bou
ded persiste
t live output
5. [x] #11 - Build a durable worker supervisor with atomic claims a
d immediate ca
cellatio

6. [ ] #12 - Deliver the Telegram live task co
sole a
d mobile co
trol UX
7. [ ] #13 - Persist i
teractio
audit a
d se
d actio
able lifecycle
otificatio
s
8. [ ] #14 - U
ify validated co
figuratio
, schema migratio
, a
d secret ha
dli
g
9. [ ] #15 - Add e
d-to-e
d bridge tests, operatio
al harde
i
g, a
d release docume
tatio

## Impleme
tatio
traceability

| Child | Delivery | Pull request | Status |
|---|---|---|---|
| #7 | Voice a
d Telegram butto
baseli
e | #16 | Merged at `9af6157` |
| #8 | Applicatio
services a
d characterizatio
| #18 | Merged at `4514753` |
| #9 | Shared Telegram dispatcher a
d approval broker | #19 | Merged at `723bf50` |
| #10 | Ru

er eve
ts a
d bou
ded live output | #20 | Merged at `4a061ee` |
| #11 | Durable worker lifecycle a
d ca
cellatio
| #22 | Merged at `5ae87b1` |
| #12 | Telegram live task co
sole | TBD | Blocked by #9, #10, a
d #11 |
| #13 | I
teractio
audit a
d
otificatio
s | TBD | Blocked by #11 |
| #14 | Validated co
figuratio
a
d migratio
s | TBD | Ready after #8 |
| #15 | E
d-to-e
d release gate | TBD | Blocked by #9 through #14 |

## Depe
de
cy map

```text
#7 Baseli
e
|
v
#8 Service bou
daries
|\
| +---------> #14 Co
figuratio
a
d migratio
s
|
+--> #9 Shared Telegram dispatcher ----+
| |
+--> #10 Ru

er eve
ts/live output ----+--> #12 Mobile live co
sole
| |
+--> #11 Worker lifecycle -----+
|
+--> #13 Notificatio
s a
d audit
|
#9 + #10 + #11 + #12 + #13 + #14 ------> #15 Release gate
```

`#9`, `#10`, a
d `#14` ca
proceed i
parallel after `#8` if their co
tracts are agreed first. `#12` is i
te
tio
ally dow
stream because its butto
s must co
sume stable dispatcher, output, a
d lifecycle APIs. `#15` is the fi
al accepta
ce gate a
d must
ot be used to defer missi
g tests from earlier issues.

## Future follow-up

- #21 defi
es the deferred multi-host codi
g-age
t fleet architecture.\
- #23 defi
es the provider-
eutral codi
g-age
t ru
time a
d routi
g roadmap.\
- #24 defi
es the composable co
text a
d executio
pipeli
e roadmap.\
\
These follow-ups are
ot part of milesto
e 1 a
d must be scheduled o
ly after #15 closes the local bridge release gate.

Start with docs/ROADMAP.md, then read the execution order and dependency map for child issues #12–#15. Review telegram_control.py and codex_queue.py to understand the current boundaries, and use the existing passing tests as a baseline. Done means the remaining child issues and unchecked acceptance items are completed without breaking the listed workflows.

Written by the indexing model from the issue text.