Pixir — Roadmap (post-v0.1)

The v0.1 walking skeleton is implemented and verified live end-to-end (see AGENTS.md status). This roadmap tracks what's next: features the plan/grill consciously deferred (A), knobs still to tune (B), hardening gaps found while building the skeleton (C), and the open beta release gate (D). Rationale lives in docs/adr/; vocabulary in CONTEXT.md.

A. Deferred features (from PLAN-v0.1 / the grill)

B. Open knobs (decide/tune in code)

• Default build system prompt (basic one exists)
• Tool-loop iteration cap (currently 12)
• bash timeout — resolved: bash_timeout_ms (default 120s); stream-idle timeout still open
• Provider retries — max_retries (default 2, capped exponential backoff)
• Device-code / resume UX copy
• Model-channel truncation policy (currently 16 KB, ADR 0005)
• Model id — resolved: config :pixir, :model → PIXIR_MODEL → ~/.pixir/config.json → gpt-5.5

B2. Pi-inspired harness ergonomics

ADR 0017 locks the product boundary: Pixir should borrow Pi's useful minimal-core shape without moving interaction glue into the core Turn loop.

Near-term slices:

1. Presenter preflight for interactive commands. Keep /skill, prompt template expansion, model selection, and adapter UX outside the core unless they create canonical History.
2. Session tree projection. Expose a read-only tree/fork projection over Logs, parent-child Session ids, Subagent lifecycle events, and future branch summaries. Do not create a second message store.
3. Compaction and replay repair. Initial slice done (ADR 0018). Pixir records canonical history_compaction checkpoints, replays latest checkpoint plus tail, and reconciles pending tool_call Events before a new Turn or interrupt. The model-assisted compaction contract is in code as a short developer instruction plus strict schema, but networked/model-assisted compaction is still deferred alongside automatic thresholds and UX around compaction previews.
4. Installable practice boundary. Treat Skills, Workflow Templates, and PATCHMD patcher repos as the growth mechanism before considering package-catalog behavior.
5. Adapter safety rails. Put T3-specific doctors, repairs, and projection checks in the T3 adapter/patcher repo, not Pixir core.

D. Open beta scope

ADR 0016 locks the first open beta as terminal/ACP-first developer preview: source install remains the baseline, Hex is not a beta prerequisite, T3Code dogfood adapter is not upstreamed, telemetry is off by default, and the release gate focuses on first-run UX, diagnostics, docs, CI/CD, and honest Subagent/T3 limitations. ADR 0025 separately allows Hex only as a CLI/ACP distribution path.

C. Hardening gaps (found while building — beyond the formal plan)

What separates the walking skeleton from a daily-usable MVP:

1. Reasoning items not persisted/replayed. Done (2026-05-29, ADR 0007) — verified live. The encrypted reasoning item (rs_…) is now a canonical reasoning event, recorded before its paired tool_call (so seq keeps rs_<fc_) and re-injected as input by the Provider, dropping items captured under a different model (the model-guard mirrors Pi's isDifferentModel). Arrival-order capture preserves intra-turn interleaving for free. A live 2-Turn session persisted four rs_ items (with encrypted_content) and the Responses API accepted them on resume. Deferred: strict id-based fc_/rs_ pairing (Pixir sends no fc_ ids; order suffices today) and any encrypted_content staleness handling (no evidence it expires; resolve empirically if ever 400'd).
2. No retry/backoff. Done — Provider.stream retries network/:rate_limited/5xx with capped exponential backoff (max_retries); terminal errors aren't retried.
3. Stream-idle timeout still open. bash can hang Done — bash runs via a Port and is killed on bash_timeout_ms (default 120s).
4. Token refresh only stub-tested. Done (2026-05-29) — verified live. Forced a stale expires_at and ran a real Turn: Pixir.Auth refreshed against auth.openai.com, rotated both access and refresh tokens, and re-persisted the fresh credential (0600) before returning — closing the refresh-token-rotation hazard. A refresh failure no longer "kills the session": a rejected refresh token (4xx) is re-mapped to an actionable :not_authenticated ("run pixir login"); a transient failure keeps its retryable :network kind. Failure-path tests in auth_test.exs.
5. Missing edit tool. Done — Pixir.Tools.Edit (exact match, unique-unless replace_all, dry-run, atomic write).
6. bash + resume not yet verified live. Done (2026-05-29) — verified live end-to-end on gpt-5.3-codex-spark: a 2-Turn session (write+bash, then resume → edit+bash; the model correctly recalled the pre-edit value from folded History). Closing this surfaced and fixed a real bug: the Log type decoder used String.to_existing_atom, so every cold resume crashed (:unknown_event_type on user_message) because the writer's atoms weren't loaded in the fresh process — resume was in fact broken, not just unverified. Now validates against Event.canonical_types/0; CLI resume also folds start_session into its with so a bad fold prints a structured error instead of a MatchError. Regression tests in log_test.exs.
7. No CLI interrupt (Ctrl-C). Done — the escript traps SIGINT and routes it to Session.interrupt/1 through the CLI presenter path.
8. config.json reads only model. Done — ~/.pixir/config.json now covers model, compaction, timeout, permission, and transport-related knobs.
9. T3-visible Subagent lifecycle UX is not yet complete. Pixir can spawn and wait on supervised child Sessions, and Workflows can run structural dependency graphs, but a T3 user should eventually be able to launch long-running Subagents, keep the root Turn non-blocking, inspect live child status on demand, and retrieve durable terminal summaries after reconnect/reload. This is distinct from the assistant-message projection fix: the projection contract is now documented in ADR 0009; lifecycle UX needs its own implementation pass and may deserve a future ADR if it becomes a release contract.

Suggested order toward an MVP

1. Permission :ask gate (ADR 0006) — done (v1)
2. edit tool + retry/backoff + bash timeout — done
3. Close live verification of bash + resume — done (and fixed a resume-breaking bug; see C6)
4. Persist/replay reasoning items (correctness on multi-tool turns) — done (ADR 0007)
5. Conversational driver (Pixir.Conversation, ADR 0008) — done; CLI refactored onto it
6. Live token refresh hardening — done (C4)
7. Design the non-Elixir UI transport — done (ADR 0009): it's ACP, not a bespoke HTTP/WS tier. Any ACP client can drive Pixir over stdio; T3Code remains local dogfood.
8. Build the ACP agent (Piece A) — done (2026-05-30) — verified live. pixir acp: Pixir.ACP.{Server,Protocol,Translate} over Conversation. v1 minimal (initialize/session/new/session/prompt/session/cancel + session/update), :auto only. Verified live by piping JSON-RPC on stdin: full handshake, a real turn that wrote a file via the tool (executed internally, reported as tool_call/tool_call_update), mid-turn session/cancel → cancelled, unknown method → -32601, malformed JSON → -32700 without crashing. The adversarial pass caught + fixed a stdout-pollution bug (the OTP-28 Logger redirect was a no-op → logs leaked to stdout, corrupting ndjson) with a regression test that exercises the real escript. 162 tests green.
9. T3Code dogfood adapter — local adapter for ACP pressure testing; not upstreamed and not packaged. (Terminal REPL stays deferred — ACP keeps it a thin optional presenter.)