Sprint 220: Reduce invocation visibility latency safely — merge feature/CODUX-220-reduce-invocation-visibility-latency-safely into dev

[numnx]

🚀 Sprint Completion: Sprint 220 · Reduce invocation visibility latency safely

Automated sprint completion PR opened by Code UX.

📋 Summary

Sprint: Sprint 220 · Reduce invocation visibility latency safely Tasks: 7/7 completed

🧭 Planning

Planning provider	Codex CLI
Planning model	gpt-5.6-luna

Metric	Value
Input tokens	271,568
Cached input tokens	3,729,152
Output tokens	21,378
Total tokens	4,022,098
Invocations	1
Tool calls	28
Active time	10m 23s

Included usage estimate (subscription/local login): $0.77

🎯 Original Sprint Prompt

Outcome

Make CLI coding invocations become visible in the server-backed Invocations surfaces as soon as the workflow has safely entered its cancellable preparation phase, while preserving honest provider telemetry and avoiding duplicate or frontend-only placeholder records. Also make the Stats → System invocation ledger refresh when execution state changes.

Investigation evidence

Recent local telemetry for 500 CLI task-coding runs showed:

• dispatch → execution invocation row: 17.1 s median, 36.7 s p95;
• workspace preparation alone: 15.9 s median, 33.4 s p95;
• execution invocation row → provider usage row: 56 ms median, 261 ms p95;
• execution invocation row → Docker launch: 1.1 s median, 3.6 s p95;
• the invocation-list REST query itself completes in roughly 8–11 ms locally.

The dominant delay is therefore lifecycle placement: CliWorkflowService finishes branch/worktree preparation before ProviderExecutionService creates execution_invocations. Chat → Invocations is already driven by the lightweight project.execution.updated channel, while Live uses an intentional heavier 5-second snapshot throttle and Stats → System currently has no realtime invalidation.

Required backend behavior

1. Persist exactly one server-backed CLI task-coding execution_invocations row earlier in the workflow, after the active dispatch cancellation handle is registered and before cli_prepare_started / executePrepareStage begins.
2. Populate the row with the durable project, sprint, task, sprint-run, dispatch, and task-run scope plus the resolved provider/model, agent preset where available, type, and invocation source.
3. Add a concise system transcript entry that truthfully describes the initial state, such as workspace/provider preparation. Do not claim that the provider process or Docker container has started before it actually has.
4. Thread the created invocation id through the CLI pipeline and into the existing ProviderExecutionService.executeProvider({ invocationId }) path. Provider execution must reuse that row, append/refresh its transcript, and link the real provider_invocations usage row when the provider slot is claimed.
5. Keep provider_invocations.started_at, concurrency accounting, and provider duration semantics anchored to the actual provider claim/run phase. Do not create fake provider usage rows during workspace preparation.
6. Preserve cancellation safety. A row must not become visible before its dispatch can be stopped. Cancelling during preparation must abort the active workflow, close the task/dispatch state consistently, mark the execution invocation cancelled once, and retain a useful audit message.
7. Finalize pre-provider failures honestly. Branch sync, agent resolution, memory/context construction, workspace preparation, Git, Docker-environment, and cancellation failures that occur after the row exists must leave it failed or cancelled with finishedAt, diagnostic fields, and a concise system transcript rather than stranded as running.
8. Preserve shutdown/startup recovery semantics. Do not overwrite rows intentionally left active for startup recovery, and ensure recovery can reconcile any new pre-provider running state.
9. Preserve resumed-workspace and recovered-provider-completion behavior. A retry that detects already-completed provider work must not invoke the provider again, create a duplicate provider usage row, or leave a misleading second running invocation. Record recovery truthfully if an execution audit row is appropriate.
10. Ensure all early creation/update/message writes continue scheduling project-scoped realtime refreshes through the repository boundary.

Required dashboard behavior

1. Keep Chat → Invocations server-authoritative. Do not reintroduce frontend-only optimistic invocation records, synthetic invocation ids, or records that cannot support cancel/restart/detail actions.
2. Update Stats → System so its current paginated/filter-aware invocation query refreshes on project.execution.updated and snapshot_required for the selected project.
3. Realtime refresh must preserve existing rows during background loading, respect AbortController/request ordering, deduplicate bursts, avoid polling storms, and retain the current page/filter/sort/search state.
4. Keep the Live page’s heavy 5-second snapshot throttle unless a narrowly scoped, measured lightweight execution-channel merge can be added without duplicating snapshots or increasing render/serialization churn. The main acceptance criterion is early persisted-row visibility and Stats realtime freshness, not removal of the Live performance guard.

Tests

Add focused deterministic coverage for:

• invocation creation ordering before workspace preparation and after cancellation registration;
• reuse of the pre-created invocation by ProviderExecutionService;
• later provider usage linkage without a duplicate execution row;
• preparation failure, cancellation, shutdown recovery, and recovered-provider-completion paths;
• project realtime notification on early creation and terminal updates;
• Chat remaining server-authoritative with no optimistic placeholder;
• Stats → System refetch on project.execution.updated and snapshot_required;
• burst deduplication, abort/request ordering, filter/pagination preservation, and no stale response overwrite.

Update integration coverage for success, validation/failure, and cancellation/error paths where contracts change. Keep tests deterministic and do not lower coverage thresholds.

Documentation and quality

• Read the relevant architecture and dashboard docs before implementation.
• Update canonical docs/architecture/execution-invocation-tracking.md, the affected dashboard/realtime documentation, and matching docs-web/ pages so the documented lifecycle matches code.
• Explain that execution invocation visibility can begin during preparation while provider usage timing begins only at the provider phase.
• Work from a feature branch based on dev; do not commit directly to dev or main.
• Use TypeScript only, strict types, focused modules, explicit exported return types, and existing Tailwind/Preact patterns.
• Do not add dependencies or lower quality/coverage gates.
• Validate at minimum with pnpm run lint, relevant backend and dashboard Vitest suites, and pnpm run build; run pnpm run ci when feasible.
• Keep the implementation reviewable and avoid unrelated refactors.

Acceptance criteria

• A normal CLI task-coding invocation is visible from a persisted server row before worktree preparation completes, with a target normal dispatch-to-visibility window near the existing dispatch/session setup time rather than the historical 17-second median.
• There is exactly one execution invocation and, when a provider actually runs, one correctly linked provider usage row per attempt.
• Early cancel/failure/recovery paths never strand a false running row.
• Chat, Live, and Stats show consistent server-backed data; Stats updates automatically after execution mutations.
• Provider concurrency, token accounting, provider duration, cancellation controls, restart/retry behavior, and startup recovery remain correct.
• Required tests, build, documentation, and repository quality gates pass.

✅ Task Checklist

• T01: Create early CLI execution audit rows — codex (PR)
• T02: Reuse execution rows for provider telemetry — codex (PR)
• T03: Settle preparation failures and recovery — codex (PR)
• T04: Refresh the Stats invocation ledger realtime — codex (PR)
• T05: Guard Chat against optimistic invocation records — codex (PR)
• T06: Document preparation-phase invocation visibility — codex (PR)
• T07: Add end-to-end invocation lifecycle acceptance — codex (PR)

👥 Provider Breakdown

7 by codex

⏱️ Sprint Timing

Started	2026-07-13 17:28:49 UTC
Finished	2026-07-13 19:23:52 UTC
Duration	1h 55m 4s

📊 Aggregate CLI Token Usage

Metric	Value
Input tokens	3,379,395
Cached input tokens	75,165,696
Output tokens	269,988
Total tokens	78,815,079
Invocations	30
Tool calls	843
Active time	2h 26m 27s

Included usage estimate (subscription/local login): $38.95

🕵️ QA Review Summary

Outcome: pass

Sprint-focused lifecycle tests, full dashboard tests, E2E, docs sync, lint, and build pass. The only broader backend failure is an unrelated Docker-dependent test blocked by spawn docker ENOENT.

🌿 Branch Info

Base: dev
Head: feature/CODUX-220-reduce-invocation-visibility-latency-safely

---

🤖 Generated by Code UX