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

diff --git a/internal/executor/channel.go b/internal/executor/channel.go
index 30d826c..ef64ede 100644
--- a/internal/executor/channel.go
+++ b/internal/executor/channel.go
@@ -2,12 +2,15 @@ package executor
 
 import (
 	"context"
+	"database/sql"
 	"encoding/json"
+	"errors"
 	"sync"
 	"time"
 
 	"github.com/thepeterstone/claudomator/internal/agentchannel"
 	"github.com/thepeterstone/claudomator/internal/event"
+	"github.com/thepeterstone/claudomator/internal/story"
 	"github.com/thepeterstone/claudomator/internal/task"
 	"github.com/google/uuid"
 )
@@ -29,12 +32,24 @@ type AgentChannel = agentchannel.AgentChannel
 type SubtaskSpec = agentchannel.SubtaskSpec
 type BlockedError = agentchannel.BlockedError
 
+// EpicProposal is the Phase 7c sibling of SubtaskSpec above: an alias so
+// existing code that refers to executor.EpicProposal (agentmcp.go, tests)
+// compiles against the same type agentchannel.AgentChannel.ProposeEpic uses.
+type EpicProposal = agentchannel.EpicProposal
+
 var ErrAgentBlocked = agentchannel.ErrAgentBlocked
 
 // channelStore is the subset of storage the default channel needs.
 type channelStore interface {
 	CreateTask(t *task.Task) error
 	CreateEvent(e *event.Event) error
+	// CreateEpic, GetEpicByName, GetStory, and UpdateStory back
+	// storeChannel.ProposeEpic (Phase 7c): matching an existing epic by exact
+	// name (or creating a new one), then attaching the given stories to it.
+	CreateEpic(e *story.Epic) error
+	GetEpicByName(name string) (*story.Epic, error)
+	GetStory(id string) (*story.Story, error)
+	UpdateStory(st *story.Story) error
 }
 
 // pendingAsker is implemented by channels that buffer an ask_user call so the
@@ -153,4 +168,59 @@ func (c *storeChannel) RecordProgress(_ context.Context, message string) error {
 		Actor:   event.ActorAgent,
 		Payload: payload,
 	})
+}
+
+// ProposeEpic groups spec.StoryIDs under a new or existing epic, matched by
+// exact spec.Name — the simplest reasonable de-dup; a fuzzy-matching pass is
+// left to a later phase if it turns out to matter. Story IDs that don't
+// resolve are skipped (not fatal to the call): one bad ID shouldn't prevent
+// grouping the rest. The event is attached to the epic's own ID, matching
+// the story orchestrator's convention (KindEvalVerdict/KindArbitrationDecided)
+// of attaching planning-layer ceremony events to the entity they're about
+// rather than to a task ID — events.task_id has no enforced FK, so this is
+// exactly the tolerance already built in for that.
+func (c *storeChannel) ProposeEpic(_ context.Context, spec agentchannel.EpicProposal) (string, error) {
+	epic, err := c.store.GetEpicByName(spec.Name)
+	if err != nil {
+		if !errors.Is(err, sql.ErrNoRows) {
+			return "", err
+		}
+		epic = &story.Epic{
+			ID:              uuid.NewString(),
+			Name:            spec.Name,
+			Description:     spec.Description,
+			DiscoverySource: "agent",
+		}
+		if err := c.store.CreateEpic(epic); err != nil {
+			return "", err
+		}
+	}
+
+	grouped := make([]string, 0, len(spec.StoryIDs))
+	for _, sid := range spec.StoryIDs {
+		st, err := c.store.GetStory(sid)
+		if err != nil {
+			continue // unresolved story ID: skip, don't fail the whole call
+		}
+		st.EpicID = epic.ID
+		if err := c.store.UpdateStory(st); err != nil {
+			continue
+		}
+		grouped = append(grouped, sid)
+	}
+
+	payload, _ := json.Marshal(struct {
+		EpicID   string   `json:"epic_id"`
+		Name     string   `json:"name"`
+		StoryIDs []string `json:"story_ids"`
+	}{EpicID: epic.ID, Name: epic.Name, StoryIDs: grouped})
+	if err := c.store.CreateEvent(&event.Event{
+		TaskID:  epic.ID,
+		Kind:    event.KindEpicProposed,
+		Actor:   event.ActorAgent,
+		Payload: payload,
+	}); err != nil {
+		return epic.ID, err
+	}
+	return epic.ID, nil
 }
\ No newline at end of file