feat(loop): structured planning system — plan tool, protected state, restart resume, Telegram/WebUI surfaces

[jkyberneees]

Summary

Adds a structured planning layer to odek's ReAct loop and exposes it across surfaces. Design spec: docs/PLANNING.md (rewritten as reference documentation).

Core (33a8337)

• One built-in plan tool (create/update/complete/get) maintaining engine-held PlanState; wholesale create is replanning
• Plan state renders into a protected [Current plan: system message using the compaction-digest pattern: survives graduated trimming, survival trim, and process restarts (rides per-step session persistence; odek continue restores forward state via strict fail-closed transcript parsing)
• Safe-classified in classifyToolCall — never prompts; untrusted-wrapped with audit ingest recording; overflow renders with an omission marker for live context but is rejected on resume; corrupt persisted plans dropped fail-closed in both directions
• Config: planning.{enabled,max_steps,max_render_chars}, --no-planning, ODEK_PLANNING=false; project config may only lower caps; disabled ⇒ tool absent, zero plan logic

Surfaces (84e9b2e)

• Additive odek.event/v1 types plan_created/plan_updated (counts + version only — never titles/notes; pinned by whole-stream marshal-and-scan test)
• GET /api/sessions/{id}/plan — read-only, sibling auth/rate-limit path, GET-only enforced structurally
• Telegram /plan_status — chat-scoped structured-plan reply; MarkdownV2-literal escaping of model-derived fields; rune-safe truncation; coexists with markdown-file /plan
• WebUI plan panel — polls the endpoint while visible (runtime events relay to /api/events ring only; WS transport is a drop-in swap when it lands), textContent-only rendering pinned by an innerHTML tripwire test
• Emoji: plan → 📋 in both renderers; vestigial todo arm retired

Coverage (5902828)

• internal/loop/plan.go: 91.4% → 99.4% statements; every function ≥96.4%, most 100%. Remaining 2 blocks are provably unreachable defensive guards (documented)
• cmd/odek plan surface functions at 100%; ui/js/plan.js at 98.35%

How loop performance improves

• Decomposition survives trimming → late-run iterations stop re-deriving "what was I doing"
• Done-work stays visible after its turns compact away → less redundant re-execution
• Budget/iteration exhaustion + odek continue resume from an actionable queue instead of transcript archaeology (verified live: kill mid-run at exit 4, resume completed all remaining steps with zero rework)

Test plan

• 24 new Go tests (loop lifecycle/trim/survival/resume/events/extract), 19 JS tests (panel, XSS inertness, polling lifecycle), 407 lines of parser coverage tests
• go test ./... scoped suites green; -race clean on internal/loop; node --test 87/87
• Live E2E against a real model: plan lifecycle (v1→v7, collapse-on-done, single persisted message) and kill-and-resume (exit 4 → continue → completion) both verified
• Security regression bar extended: Safe classification, untrusted wrapping, project-config clamp pinned in security_report_validation_test.go

Out of scope (roadmap in docs/PLANNING.md)

Plan-aware stall-recovery suffix, blocked-step trigger + plan_blocked signal, exhaustion remaining-steps blocks, WS event relay for live panel updates.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	odek	5902828	Commit Preview URL Branch Preview URL	Aug 24 2026, 08:03 PM