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, 21 insertions, 0 deletions

diff --git a/internal/agentchannel/agentchannel.go b/internal/agentchannel/agentchannel.go
index 42eacbc..83c5f8d 100644
--- a/internal/agentchannel/agentchannel.go
+++ b/internal/agentchannel/agentchannel.go
@@ -44,6 +44,20 @@ type SubtaskSpec struct {
 	Role string
 }
 
+// EpicProposal describes an epic a discovery/planner-role agent wants to
+// group one or more stories under (internal/story.Epic/Story — the planning
+// layer above the flat task tree). Matching an existing epic is by exact
+// Name (see storeChannel.ProposeEpic in internal/executor/channel.go) — the
+// simplest reasonable de-dup, not fuzzy matching.
+type EpicProposal struct {
+	Name        string
+	Description string
+	// StoryIDs are the story IDs to group under this epic. An ID that
+	// doesn't resolve to an existing story is skipped rather than failing
+	// the whole call — one bad ID shouldn't block grouping the rest.
+	StoryIDs []string
+}
+
 // AgentChannel is how a Runner reports agent-originated signals to the rest of
 // the system. Implementations translate these into stored artifacts and events.
 // The transport by which a Runner detects these signals — post-exit files
@@ -59,6 +73,13 @@ type AgentChannel interface {
 	SpawnSubtask(ctx context.Context, spec SubtaskSpec) (taskID string, err error)
 	// RecordProgress records a free-form progress note from the agent.
 	RecordProgress(ctx context.Context, message string) error
+	// ProposeEpic groups spec.StoryIDs under a new or existing epic (matched
+	// by name), returning the epic's ID. Called by a discovery/planner-role
+	// agent that has independently judged a set of stories to form a
+	// cohesive initiative — the judgment itself is the calling agent's job
+	// (via its instructions/model); this just gives it a mechanism to act on
+	// it.
+	ProposeEpic(ctx context.Context, spec EpicProposal) (epicID string, err error)
 }
 
 // BlockedError is returned by Run when the agent asked the user a question and