(CODUX-222) Wire ETA guidance into MCP planning

[numnx]

🧩 Task: Wire ETA guidance into MCP planning

Automated task PR opened by Code UX for T02.

📋 Summary

Sprint: Sprint 222 · Improve planning ETA guidance · Task: T02

Give dashboard-assigned agents immediate, machine-readable planning ETA guidance, enforce one-minute in-progress rechecks without duplicate planning or settings changes, preserve terminal scheduler wakeups, and document the complete asynchronous lifecycle.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-13 19:27:44 UTC
Finished	2026-07-13 19:36:27 UTC
Duration	8m 43s

📊 Token Usage

Metric	Value
Input tokens	141,944
Cached input tokens	3,238,144
Output tokens	19,731
Total tokens	3,399,819
Invocations	1
Tool calls	38
Active time	8m 6s

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

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Integrate the shared planning guidance into direct MCP planning acknowledgements and sprint status reads without changing the existing detached planning or scheduler lifecycle.

## Scope
- Edit `src/mcp/management/sprint-actions.ts`
- Edit the `listExecutionInvocations` parameter contract in `src/repositories/execution-repository.ts`
- Edit the `manage_sprints` description in `src/contracts/mcp-tool-definitions.ts`
- Update `tests/backend/mcp/management-sprint-actions.test.ts`
- Update focused invocation query coverage in `tests/backend/repositories/execution-repository.test.ts`
- Consume `McpPlanningGuidance` and duration selection from T01

## Implementation Requirements
1. Before `startPlanSprint`, calculate the project ETA from recent completed planning invocations and add an additive `planningGuidance` object to the existing `status: "started"`, `message`, `projectId`, and `sprintId` acknowledgement; keep the response immediate while the planning promise remains unsettled.
2. Track the active planning promise per project and sprint inside `SprintActions`. A repeated `plan` call for the same in-flight request must return `status: "in_progress"` plus one-minute guidance without starting another provider request, attaching another terminal callback, or creating another scheduler entry.
3. Enhance `manage_sprints` `get` additively: preserve the sprint record fields, and include `planningGuidance` when an in-memory request or latest sprint-linked planning invocation exists. Prefer the active promise over a prematurely completed audit row, and otherwise derive durable running or terminal state through `ExecutionRepository.listExecutionInvocations({ projectId, sprintId, ... })`.
4. Remove active tracking only when the same promise settles. Map completed invocations to success and failed, cancelled, or paused invocations to terminal guidance with surfaced error details and no further check time.
5. Preserve the existing scheduler producer exactly: one due-now, non-recurring, same-agent/same-thread `agent_wakeup` after the original planning promise succeeds or fails; standalone calls still skip wakeup creation, and status polling must not create backend scheduler entries.
6. Keep synchronous project, sprint, and replan precondition failures on the existing management error path rather than returning an in-progress acknowledgement.

## Constraints
- Do not change REST planning routes, scheduled sprint planning, quicksprints, or `import_issues` with `planAfterImport`.
- Do not mutate routing, provider, model, or project settings in response to slow planning.
- Preserve current auto-start, task persistence, cancellation, logging, agent/thread identity, and scheduler target metadata.
- Keep the existing acknowledgement fields backward compatible; `planningGuidance` is additive.
- Prevent stale promise cleanup from deleting a newer active request for the same sprint.

## Verification
- Run `pnpm exec vitest run tests/backend/mcp/management-sprint-actions.test.ts tests/backend/repositories/execution-repository.test.ts`.
- Run `pnpm run lint` and `pnpm run build`.
- Confirm an unresolved request returns immediately with ETA, duplicate planning is suppressed, `get` advances one minute while running, terminal states stop polling, and exactly one existing-style terminal wakeup is queued.

🌿 Branch Info

Base: feature/CODUX-222-improve-planning-eta-guidance
Head: task/feature-codux-22-t02-codex-43eb4ce9-mrjm6y9l

---

🤖 Generated by Code UX