feat(story,scheduler): add epic-proposal tool + AskUser-timeout escalation (Phase 7c)

Two independent pieces, completing Phase 7.

Epic-proposal tool: AgentChannel gains a 5th method, ProposeEpic(ctx,
EpicProposal{Name, Description, StoryIDs}) (epicID, err), implemented on
storeChannel -- matches an existing epic by exact name or creates one
(DiscoverySource: "agent"), sets epic_id on each resolvable story (skips,
doesn't fail, on an unresolved ID), emits KindEpicProposed attached to the
epic's own ID with payload {epic_id, name, story_ids}. Wired into both
transports exactly like Phase 6 wired role into spawn_subtask: a new
propose_epic tool in the native tool-use loop (internal/agentloop/tools.go)
and the MCP transport (internal/executor/agentmcp.go). This is the mechanism
for a discovery/planner-role agent to act on its own judgment that several
stories it's been given form one cohesive initiative -- the judgment itself
lives in the calling agent's instructions/model, not in this code.

AskUser-timeout escalation: extends the existing Scheduler (Phase 5's
retry-then-escalate watcher) rather than adding a new component, since
"stuck task needs escalation" is exactly what it already does. Finds
role-typed BLOCKED tasks whose question has been outstanding longer than
SchedulerConfig.AskUserTimeoutSeconds (default 10 minutes) using
task.UpdatedAt as the outstanding-since timestamp -- no new column needed,
since UpdateTaskQuestion already stamps it the instant a question is
recorded and nothing else touches the row while BLOCKED. Resolves the next
ladder tier from the latest execution's EscalationRung, records the
system-authored fallback answer as an audit-trail task.Interaction, clears
the question, sets the new tasks.needs_review flag, emits KindEscalated
(now carrying a trigger field: "failure" vs "ask_user_timeout" for the
existing failure-retry path vs this one), and resumes via Pool.SubmitResume
at the escalated tier -- degrading to same-tier resume with final:true if
the ladder's exhausted or no role config exists, since unblocking the task
takes priority over having somewhere higher to escalate to.
GET /api/tasks?needs_review=true surfaces auto-decided tasks for human
review.

go build/vet/test -race -count=1 all pass, full suite (20 packages), run
twice to rule out flakiness in the new tests. (One pre-existing, unrelated
test -- TestHandleRunTask_CascadesRetryToFailedDeps, a tempdir-cleanup race
-- appeared once under full-suite load per the implementing agent's report
and did not reproduce in this verification's runs either; not a regression
from this work.)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs

1 files changed, 58 insertions, 0 deletions

diff --git a/internal/api/server_test.go b/internal/api/server_test.go
index 24e1d30..460c669 100644
--- a/internal/api/server_test.go
+++ b/internal/api/server_test.go
@@ -518,6 +518,64 @@ func TestListTasks_WithTasks(t *testing.T) {
 	}
 }
 
+// TestListTasks_NeedsReviewFilter proves GET /api/tasks?needs_review=true
+// only returns tasks flagged needs_review (set by
+// internal/scheduler.Scheduler's ask-user-timeout escalation).
+func TestListTasks_NeedsReviewFilter(t *testing.T) {
+	srv, store := testServer(t)
+
+	flagged := &task.Task{
+		ID: "nr-1", Name: "flagged",
+		RepositoryURL: "https://github.com/user/repo",
+		Agent:         task.AgentConfig{Type: "claude", Instructions: "x"}, Priority: task.PriorityNormal,
+		Retry: task.RetryConfig{MaxAttempts: 1, Backoff: "linear"},
+		Tags:  []string{}, DependsOn: []string{}, State: task.StatePending,
+	}
+	if err := store.CreateTask(flagged); err != nil {
+		t.Fatalf("CreateTask flagged: %v", err)
+	}
+	if err := store.UpdateTaskNeedsReview(flagged.ID, true); err != nil {
+		t.Fatalf("UpdateTaskNeedsReview: %v", err)
+	}
+
+	notFlagged := &task.Task{
+		ID: "nr-2", Name: "not flagged",
+		RepositoryURL: "https://github.com/user/repo",
+		Agent:         task.AgentConfig{Type: "claude", Instructions: "x"}, Priority: task.PriorityNormal,
+		Retry: task.RetryConfig{MaxAttempts: 1, Backoff: "linear"},
+		Tags:  []string{}, DependsOn: []string{}, State: task.StatePending,
+	}
+	if err := store.CreateTask(notFlagged); err != nil {
+		t.Fatalf("CreateTask notFlagged: %v", err)
+	}
+
+	req := httptest.NewRequest("GET", "/api/tasks?needs_review=true", nil)
+	w := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status: want 200, got %d; body: %s", w.Code, w.Body.String())
+	}
+	var tasks []task.Task
+	if err := json.NewDecoder(w.Body).Decode(&tasks); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(tasks) != 1 {
+		t.Fatalf("want 1 needs_review task, got %d: %+v", len(tasks), tasks)
+	}
+	if tasks[0].ID != "nr-1" || !tasks[0].NeedsReview {
+		t.Errorf("expected flagged task nr-1 with NeedsReview=true, got %+v", tasks[0])
+	}
+
+	// Sanity check: an invalid needs_review value is a 400, not a silent no-op.
+	req2 := httptest.NewRequest("GET", "/api/tasks?needs_review=notabool", nil)
+	w2 := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(w2, req2)
+	if w2.Code != http.StatusBadRequest {
+		t.Errorf("invalid needs_review: want 400, got %d", w2.Code)
+	}
+}
+
 // stateWalkPaths defines the sequence of intermediate states needed to reach each target state.
 var stateWalkPaths = map[task.State][]task.State{
 	task.StatePending:        {},