feat: resume support, summary extraction, and task state improvements

- Extend Resume to CANCELLED, FAILED, and BUDGET_EXCEEDED tasks
- Add summary extraction from agent stdout stream-json output
- Fix storage: persist stdout/stderr/artifact_dir paths in UpdateExecution
- Clear question_json on ResetTaskForRetry
- Resume BLOCKED tasks in preserved sandbox so Claude finds its session
- Add planning preamble: CLAUDOMATOR_SUMMARY_FILE env var + summary step
- Update ADR-002 with new state transitions
- UI style improvements

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

4 files changed, 125 insertions, 0 deletions

diff --git a/internal/executor/claude.go b/internal/executor/claude.go
index 0e29f7f..a58f1ad 100644
--- a/internal/executor/claude.go
+++ b/internal/executor/claude.go
@@ -150,6 +150,13 @@ func (r *ClaudeRunner) Run(ctx context.Context, t *task.Task, e *storage.Executi
 		return &BlockedError{QuestionJSON: strings.TrimSpace(string(data)), SessionID: e.SessionID, SandboxDir: sandboxDir}
 	}
 
+	// Read agent summary if written.
+	summaryFile := filepath.Join(logDir, "summary.txt")
+	if summaryData, readErr := os.ReadFile(summaryFile); readErr == nil {
+		os.Remove(summaryFile) // consumed
+		e.Summary = strings.TrimSpace(string(summaryData))
+	}
+
 	// Merge sandbox back to project_dir and clean up.
 	if sandboxDir != "" {
 		if mergeErr := teardownSandbox(projectDir, sandboxDir, r.Logger); mergeErr != nil {
@@ -261,6 +268,7 @@ func (r *ClaudeRunner) execOnce(ctx context.Context, args []string, workingDir s
 		"CLAUDOMATOR_API_URL="+r.APIURL,
 		"CLAUDOMATOR_TASK_ID="+e.TaskID,
 		"CLAUDOMATOR_QUESTION_FILE="+filepath.Join(e.ArtifactDir, "question.json"),
+		"CLAUDOMATOR_SUMMARY_FILE="+filepath.Join(e.ArtifactDir, "summary.txt"),
 	)
 	// Put the subprocess in its own process group so we can SIGKILL the entire
 	// group (MCP servers, bash children, etc.) on cancellation.
diff --git a/internal/executor/preamble.go b/internal/executor/preamble.go
index e50c16f..bc5c32c 100644
--- a/internal/executor/preamble.go
+++ b/internal/executor/preamble.go
@@ -46,6 +46,17 @@ The sandbox is rejected if there are any uncommitted modifications.
 
 ---
 
+## Final Summary (mandatory)
+
+Before exiting, write a brief summary paragraph (2–5 sentences) describing what you did
+and the outcome. Write it to the path in $CLAUDOMATOR_SUMMARY_FILE:
+
+  echo "Your summary here." > "$CLAUDOMATOR_SUMMARY_FILE"
+
+This summary is displayed in the task UI so the user knows what happened.
+
+---
+
 `
 
 func withPlanningPreamble(instructions string) string {
diff --git a/internal/executor/summary.go b/internal/executor/summary.go
new file mode 100644
index 0000000..a942de0
--- /dev/null
+++ b/internal/executor/summary.go
@@ -0,0 +1,57 @@
+package executor
+
+import (
+	"bufio"
+	"encoding/json"
+	"os"
+	"strings"
+)
+
+// extractSummary reads a stream-json stdout log and returns the text following
+// the last "## Summary" heading found in any assistant text block.
+// Returns empty string if the file cannot be read or no summary is found.
+func extractSummary(stdoutPath string) string {
+	f, err := os.Open(stdoutPath)
+	if err != nil {
+		return ""
+	}
+	defer f.Close()
+
+	var last string
+	scanner := bufio.NewScanner(f)
+	scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
+	for scanner.Scan() {
+		if text := summaryFromLine(scanner.Bytes()); text != "" {
+			last = text
+		}
+	}
+	return last
+}
+
+// summaryFromLine parses a single stream-json line and returns the text after
+// "## Summary" if the line is an assistant text block containing that heading.
+func summaryFromLine(line []byte) string {
+	var event struct {
+		Type    string `json:"type"`
+		Message struct {
+			Content []struct {
+				Type string `json:"type"`
+				Text string `json:"text"`
+			} `json:"content"`
+		} `json:"message"`
+	}
+	if err := json.Unmarshal(line, &event); err != nil || event.Type != "assistant" {
+		return ""
+	}
+	for _, block := range event.Message.Content {
+		if block.Type != "text" {
+			continue
+		}
+		idx := strings.Index(block.Text, "## Summary")
+		if idx == -1 {
+			continue
+		}
+		return strings.TrimSpace(block.Text[idx+len("## Summary"):])
+	}
+	return ""
+}
diff --git a/internal/executor/summary_test.go b/internal/executor/summary_test.go
new file mode 100644
index 0000000..4a73711
--- /dev/null
+++ b/internal/executor/summary_test.go
@@ -0,0 +1,49 @@
+package executor
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestExtractSummary_WithSummarySection(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "stdout.log")
+	content := streamLine(`{"type":"assistant","message":{"content":[{"type":"text","text":"## Summary\nThe task was completed successfully."}]}}`)
+	if err := os.WriteFile(path, []byte(content), 0600); err != nil {
+		t.Fatal(err)
+	}
+	got := extractSummary(path)
+	want := "The task was completed successfully."
+	if got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+}
+
+func TestExtractSummary_NoSummary(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "stdout.log")
+	content := streamLine(`{"type":"assistant","message":{"content":[{"type":"text","text":"All done, no summary heading."}]}}`)
+	if err := os.WriteFile(path, []byte(content), 0600); err != nil {
+		t.Fatal(err)
+	}
+	got := extractSummary(path)
+	if got != "" {
+		t.Errorf("expected empty string, got %q", got)
+	}
+}
+
+func TestExtractSummary_MultipleSections_PicksLast(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "stdout.log")
+	content := streamLine(`{"type":"assistant","message":{"content":[{"type":"text","text":"## Summary\nFirst summary."}]}}`) +
+		streamLine(`{"type":"assistant","message":{"content":[{"type":"text","text":"## Summary\nFinal summary."}]}}`)
+	if err := os.WriteFile(path, []byte(content), 0600); err != nil {
+		t.Fatal(err)
+	}
+	got := extractSummary(path)
+	want := "Final summary."
+	if got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+}