CCBot Re-Architecture For Codex tmux Operation

[iqdoctor]

Plan: CCBot Re-Architecture For Codex tmux Operation

Generated: 2026-04-02

Overview

Fork status:

• Source repo: https://github.com/six-ddc/ccbot
• Fork: https://github.com/strato-space/ccbot
• Local checkout: /home/tools/ccbot

Target outcome:

• Operate Codex from Telegram forum topics while keeping tmux as the live control surface.
• Support the core lane first: create, bind, monitor, send input, inspect history, resume.
• Keep voice, task, and ACP out of scope for feature work and explicitly guarded from regression.

Definitions

• Telegram topic: the user-facing control lane in Telegram.
• Binding: persisted association from topic to a live tmux window plus its runtime metadata.
• tmux window: the live terminal container.
• Codex process: the interactive codex CLI instance running inside a window.
• Codex thread: the persisted conversation identity that can be resumed later.
• Rollout log: the JSONL event stream on disk under ~/.codex/sessions/.../rollout-*.jsonl.
• Runtime adapter: the code layer that maps runtime-specific launch, identity, input, and event semantics into generic bot behavior.

Ontological Model

The plan uses this model and must not collapse these entities:

Telegram topic -> binding -> tmux window -> Codex process -> Codex thread -> rollout log

Constraints:

• A window is not a thread.
• A live process is not identical to its persisted thread.
• A rollout log is evidence emitted by a process/thread, not the process itself.
• The bot sends input to the live process through tmux, but reads history and notifications from normalized rollout log events.
• Resume binds a new or reused live process to an existing thread; it does not restore the old process.

Established Claims

• ccbot today is Claude-oriented in four hard ways:
  • launch semantics in tmux_manager.py
  • persisted state and session lookup in session.py
  • monitor offsets in monitor_state.py
  • hook-based registration in hook.py
• Codex local storage already distinguishes persisted threads and rollout files:
  • thread persistence docs in sdk/typescript/README.md
  • thread schema in Thread.ts
  • event taxonomy in ThreadItem.ts
  • local operator tooling in codex-tools/README.md

Working Hypotheses

• File-backed Codex integration using session_index.jsonl plus rollout JSONL files is sufficient for the first release.
• tmux pane inspection is sufficient for safe prompt detection in the core lane, but not yet proven for full remote approval control.
• Explicit launcher-side registration can replace the Claude SessionStart hook and should be the primary binding path.

Prerequisites

• Access to /home/tools/ccbot
• Working codex binary on target hosts
• tmux installed and stable
• Telegram bot with forum topics enabled
• Access to $HOME/.codex

Dependency Graph

T1 ──┬── T2 ──┬── T3 ──┬── T4 ──┬── T6 ──┬── T9 ──┬── T12 ──┐
     │        │        │        │        │        │         │
     │        │        │        │        │        └── T13 ──┼── T16
     │        │        │        │        │                  │
     │        │        │        │        └── T10 ──┬────────┤
     │        │        │        │                  │        │
     │        │        │        └── T7 ──┬── T8 ───┘        │
     │        │        │                 │                  │
     │        │        └── T5 ───────────┘                  │
     │        │                                             │
     │        └─────────────────────────────── T11 ─────────┤
     │                                                      │
     └──────────────────────────────────────── T14 ── T15 ──┘

Tasks

T1: Capture Real Codex Evidence And Non-Root Fixtures

• depends_on: []
• location: $HOME/.codex/, /home/tools/codex-tools/, /home/tools/ccbot/tests/fixtures/, /home/tools/ccbot/doc/
• description: Capture redacted fixtures for the actual Codex objects in scope: thread metadata, rollout logs, session index rows, tmux pane snapshots, and resume behavior. Use both root-owned and non-root-shaped paths in fixtures so the implementation does not accidentally hardcode /root/.codex.
• validation: Fixture corpus includes fresh thread, resumed thread, same-cwd multiple threads, stale index entry, missing rollout file, interrupted turn, reasoning, command execution, tool call/output, and at least one prompt snapshot.
• status: Not Completed
• log:
• files edited/created:

T2: Write The Runtime Ontology And Invariants Into The Fork

• depends_on: [T1]
• location: /home/tools/ccbot/doc/, /home/tools/ccbot/README.md
• description: Add a maintainer note that defines binding, window, process, thread, and rollout log, and states the non-collapsing invariants. This becomes the contract every implementation task follows.
• validation: The note explicitly states what the bot writes to, what it reads from, and which equalities are forbidden.
• status: Not Completed
• log:
• files edited/created:

T3: Introduce Runtime-Neutral Core Types

• depends_on: [T2]
• location: /home/tools/ccbot/src/ccbot/session.py, /home/tools/ccbot/src/ccbot/session_monitor.py, /home/tools/ccbot/src/ccbot/transcript_parser.py, /home/tools/ccbot/src/ccbot/ (new runtime modules)
• description: Replace Claude-shaped implicit nouns with explicit runtime-neutral types: binding, live process descriptor, thread locator, rollout source, normalized event, and input action. The core must stop speaking of a single generic session where different entities are involved.
• validation: Core modules compile and tests pass with type names and APIs that distinguish window/process/thread/log concerns.
• status: Not Completed
• log:
• files edited/created:

T4: Version Persisted State And Define Migration/Cutover

• depends_on: [T3]
• location: /home/tools/ccbot/src/ccbot/config.py, /home/tools/ccbot/src/ccbot/session.py, /home/tools/ccbot/src/ccbot/monitor_state.py, /home/tools/ccbot/doc/, /home/tools/ccbot/tests/
• description: Add schema versioning and runtime_kind namespacing to bot state. Define the cutover path for existing Claude-era state.json, session_map.json, and monitor offsets: dual-read plus explicit rollback, or one-time migration plus reversible backup. The migration must preserve existing topic bindings until Codex binding has been validated.
• validation: Tests load pre-migration Claude state, migrated mixed-runtime state, and rollback artifacts without losing thread/topic bindings or replaying old messages.
• status: Not Completed
• log:
• files edited/created:

T5: Freeze And Test Out-Of-Scope Compatibility Surface

• depends_on: [T3]
• location: /home/tools/ccbot/src/ccbot/bot.py, /home/tools/ccbot/src/ccbot/transcribe.py, /home/tools/ccbot/src/ccbot/handlers/, /home/tools/ccbot/tests/
• description: Identify the existing flows that must not change while Codex support is added: voice handling, photo forwarding, topic close/rename cleanup, raw passthrough commands, and any task/ACP-adjacent branching that already exists. Convert them into non-regression tests before feature work lands in shared modules.
• validation: Compatibility tests fail if a Codex refactor changes behavior in preserved out-of-scope paths.
• status: Not Completed
• log:
• files edited/created:

T6: Build The Codex Thread Catalog Adapter

• depends_on: [T1, T3, T4]
• location: /home/tools/ccbot/src/ccbot/session.py, /home/tools/ccbot/src/ccbot/session_monitor.py, /home/tools/ccbot/src/ccbot/ (new codex_threads.py or equivalent), /home/tools/ccbot/tests/
• description: Implement the adapter that enumerates persisted Codex threads and their rollout files from session_index.jsonl and ~/.codex/sessions. Resolve exact thread identity without collapsing it into a live process or window.
• validation: The adapter exposes deterministic thread candidates with precedence rules: explicit thread id > explicit launcher registration > exact normalized cwd > user-visible disambiguation. It never silently auto-selects among ambiguous same-cwd threads.
• status: Not Completed
• log:
• files edited/created:

T7: Build The Codex Rollout Normalizer

• depends_on: [T1, T3]
• location: /home/tools/ccbot/src/ccbot/transcript_parser.py, /home/tools/ccbot/src/ccbot/session_monitor.py, /home/tools/ccbot/src/ccbot/ (new codex_rollout.py or equivalent), /home/tools/ccbot/tests/
• description: Normalize Codex rollout JSONL records into generic bot events. Preserve the distinction between user message, assistant message, commentary, reasoning, command execution, tool call, tool output, file change, and lifecycle marker.
• validation: Fixture tests cover partial writes, corrupted lines, truncation/reset, offset repair, repeated reads without duplicate emission, and mixed event turns.
• status: Not Completed
• log:
• files edited/created:

T8: Build The Runtime Input Driver

• depends_on: [T3]
• location: /home/tools/ccbot/src/ccbot/tmux_manager.py, /home/tools/ccbot/src/ccbot/session.py, /home/tools/ccbot/src/ccbot/bot.py, /home/tools/ccbot/src/ccbot/terminal_parser.py, /home/tools/ccbot/tests/
• description: Replace Claude-specific send semantics with a runtime input driver for Codex. This driver owns text submit timing, multiline paste, raw slash commands, Esc, arrows, and shell-mode transitions.
• validation: Tests prove the bot can drive a Codex process reliably, not merely launch one. Unsupported controls must degrade to no-op or hidden UI, never to a false-success action.
• status: Not Completed
• log:
• files edited/created:

T9: Replace Hook-Coupled Binding With Explicit Process Registration

• depends_on: [T4, T6, T8]
• location: /home/tools/ccbot/src/ccbot/hook.py, /home/tools/ccbot/src/ccbot/session.py, /home/tools/ccbot/src/ccbot/bot.py, /home/tools/ccbot/src/ccbot/ (new launcher/registration module), /home/tools/ccbot/tests/
• description: Remove Claude SessionStart as the source of truth for Codex binding. Introduce explicit launcher-side registration for the live process and attach it to a window first, then to a thread. Heuristics are fallback only and must fail closed on ambiguity.
• validation: Tests cover same-cwd parallel starts, delayed session index writes, stale historical threads, resume-vs-new races, and restart recovery without wrong-topic binding.
• status: Not Completed
• log:
• files edited/created:

T10: Rework Topic Browser And Resume UX Around Threads

• depends_on: [T6, T9]
• location: /home/tools/ccbot/src/ccbot/bot.py, /home/tools/ccbot/src/ccbot/handlers/directory_browser.py, /home/tools/ccbot/src/ccbot/handlers/callback_data.py, /home/tools/ccbot/tests/
• description: Make the Telegram browser and picker speak of Codex threads explicitly, not generic sessions. New window creation creates a live process; resume selects a persisted thread and binds a new or reused process to it.
• validation: The UI distinguishes fresh thread creation from thread resume, surfaces ambiguity instead of guessing, and binds the selected topic to the correct live window/process/thread chain.
• status: Not Completed
• log:
• files edited/created:

T11: Rebuild History And Notification Read Paths From Rollout Evidence

• depends_on: [T6, T7]
• location: /home/tools/ccbot/src/ccbot/session.py, /home/tools/ccbot/src/ccbot/handlers/history.py, /home/tools/ccbot/src/ccbot/handlers/response_builder.py, /home/tools/ccbot/src/ccbot/handlers/message_sender.py, /home/tools/ccbot/tests/
• description: Rebuild /history and outbound Telegram notifications so they read normalized rollout evidence, not a Claude-shaped transcript abstraction. History is about the thread’s persisted event trail; notification routing is about the currently bound live process/window.
• validation: Tests prove stable pagination, no duplicate notifications after restart, correct routing by current binding, and sensible summaries for commentary, reasoning, commands, and tool output.
• status: Not Completed
• log:
• files edited/created:

T12: Add Safe Prompt Detection For The Core Lane

• depends_on: [T1, T8, T11]
• location: /home/tools/ccbot/src/ccbot/terminal_parser.py, /home/tools/ccbot/src/ccbot/handlers/interactive_ui.py, /home/tools/ccbot/src/ccbot/handlers/status_polling.py, /home/tools/ccbot/tests/
• description: Detect Codex TUI states that are necessary for safe remote operation in the first release: input-ready, busy, blocked on visible prompt, and unknown. Unknown states must degrade to read-only visibility with no misleading actions.
• validation: Fixture tests cover positive and negative prompt detection. Unsupported states never expose active buttons.
• status: Not Completed
• log:
• files edited/created:

T13: Rationalize Telegram Command Surface Around The Core Lane

• depends_on: [T5, T8, T10, T11, T12]
• location: /home/tools/ccbot/src/ccbot/bot.py, /home/tools/ccbot/README.md, /home/tools/ccbot/doc/telegram-bot-features.md, /home/tools/ccbot/tests/
• description: Rebuild the bot command/menu surface so it truthfully advertises only the Codex-supported core lane. Remove or runtime-gate Claude-only assumptions and preserve raw passthrough only where it remains semantically valid for Codex.
• validation: Registered commands, help text, and forwarding behavior align with the actual supported Codex workflow and do not imply unsupported remote controls.
• status: Not Completed
• log:
• files edited/created:

T14: Optional Lane For Remote Prompt/Approval Control

• depends_on: [T12]
• location: /home/tools/ccbot/src/ccbot/handlers/interactive_ui.py, /home/tools/ccbot/src/ccbot/terminal_parser.py, /home/tools/ccbot/tests/
• description: If needed after the core lane is stable, add remote prompt/approval actions for positively identified Codex states. This lane is explicitly optional and must not block shipping create/bind/monitor/send/history/resume.
• validation: Only positively identified supported prompts expose controls; all other states remain read-only.
• status: Not Completed
• log:
• files edited/created:

T15: Package Strato Ops Docs, Cutover Notes, And Rollback Procedure

• depends_on: [T4, T5, T13]
• location: /home/tools/ccbot/README.md, /home/tools/ccbot/README_RU.md, /home/tools/ccbot/doc/, /home/tools/ccbot/scripts/
• description: Document the Strato operating path: config vars, $HOME/.codex expectations, tmux policy, launcher behavior, migration steps, rollback path, and the corrected operator tooling path /home/tools/codex-tools/codex-session-scout. State explicitly that voice, task, and ACP are not part of this release scope.
• validation: A new operator can install, migrate, launch, and roll back using docs only.
• status: Not Completed
• log:
• files edited/created:

T16: Live End-To-End Smoke And Release Gate

• depends_on: [T9, T10, T11, T13, T15]
• location: /home/tools/ccbot/tests/integration/, /home/tools/ccbot/doc/, manual smoke checklist
• description: Run the release gate for the core lane: create topic, pick directory, start Codex process in tmux, receive output, send follow-up input, inspect history, resume an existing thread, restart the bot, verify bindings/offsets survive, and verify preserved out-of-scope flows still behave unchanged.
• validation: Core lane smoke passes on a live host. Optional prompt-control smoke runs only if T14 is completed.
• status: Not Completed
• log:
• files edited/created:

Parallel Execution Groups

Wave	Tasks	Can Start When
1	T1	Immediately
2	T2, T3	T1 complete for T2; T2 complete for T3
3	T4, T5, T7, T8	Their direct dependencies complete
4	T6	T1, T3, T4 complete
5	T9, T11	Their direct dependencies complete
6	T10, T12	Their direct dependencies complete
7	T13, T14	Their direct dependencies complete
8	T15	T4, T5, T13 complete
9	T16	T9, T10, T11, T13, T15 complete

Testing Strategy

• Build the release on fixture evidence first, not on live manual testing.
• Keep three test layers separate:
• ontology/state tests for binding/process/thread/log separation
• rollout normalization and history tests
• Telegram/tmux integration tests
• Treat out-of-scope compatibility as a hard gate, not as a final sanity check.
• Run live smoke only after migration, binding, and read-path semantics are green in automation.

Risks & Mitigations

• Risk: The plan regresses into conflating thread, process, and rollout log.

• Mitigation: Keep the ontology note in-repo and require every adapter API to name which entity it operates on.

• Risk: Session index and rollout files disagree or lag.

• Mitigation: Use explicit launcher registration as primary truth for live binding and fail closed on ambiguous thread resolution.

• Risk: tmux pane heuristics are mistaken for authoritative runtime state.

• Mitigation: Use pane parsing only for UI hints and safe prompt classification, never as the sole identity source.

• Risk: Cutover breaks existing Claude-era bindings and unread offsets.

• Mitigation: Version state, add rollback, and keep migration explicit and test-covered.

• Risk: Shared-module refactors accidentally alter voice, task, or ACP-adjacent behavior.

• Mitigation: Freeze those paths under non-regression tests before Codex feature work lands.