Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ A review runs in the background by default, so you can start several and keep wo
default_run = "terminal" # or "background", the default
```

docket asks `claude` every fifteen seconds how each session is doing. The line under each running row shows claude's one-line summary of what the session is doing and how many agents it is running. When a session is waiting for you, that line turns red and says what the session needs, and `enter` opens the session so you can answer it. When claude has not updated its summary for ten minutes, the line says how long the session has been quiet, which is your cue to open it and look. When a session finishes, docket reads GitHub for what it left and moves the record on, the same way it does after a session you sat through. review-code ends a background review once it has posted the draft, often by asking whether to submit it, and the session then waits on you rather than finishing. When your draft is on GitHub, docket moves that row to Drafted anyway, so `s` submits it from the dashboard, and `enter` still opens the session if you would rather answer it there. If you open a drafted row's session and leave it working, docket cannot tell whether the session is changing the review, so the row goes back to Reviewing until the session ends its turn. `s` still submits the draft meanwhile, and submitting leaves a session that is still working running.
docket asks `claude` every fifteen seconds how each session is doing. The line under each running row shows claude's one-line summary of what the session is doing and how many agents it is running. When a session is waiting for you, because it asked a question or stopped to ask permission to run a tool, its row moves to a Waiting for you group at the top of the dashboard, the line turns red and says what the session needs, and `enter` opens the session so you can answer it. When claude has not updated its summary for ten minutes, the line says how long the session has been quiet, which is your cue to open it and look. When a session finishes, docket reads GitHub for what it left and moves the record on, the same way it does after a session you sat through. review-code ends a background review once it has posted the draft, often by asking whether to submit it, and the session then waits on you rather than finishing. When your draft is on GitHub, docket moves that row to Drafted anyway, so `s` submits it from the dashboard, and `enter` still opens the session if you would rather answer it there. If you open a drafted row's session and leave it working, docket cannot tell whether the session is changing the review, so the row goes back to Reviewing until the session ends its turn. `s` still submits the draft meanwhile, and submitting leaves a session that is still working running.

`claude` runs a background session only in a directory you have trusted, and it can ask that question only in a terminal. When it refuses a review for that reason, docket hands the terminal to `claude` in that directory. Pick "Yes, I trust this folder", and docket starts the review again. Tier-1 reviews share one directory, so this happens once for all of them. Each tier-2 review clones into a directory of its own, so it happens once for each. A review that still does not start waits under "Did not start" with claude's reason, and `enter` starts it again.

Expand Down
17 changes: 14 additions & 3 deletions internal/core/engine/background.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ type BGStatus struct {
// session is not working. The listing can say so just as a turn starts.
// Waiting, not Idle, is the test for an ended turn.
Idle bool
// Prompted reports that the session stopped partway through its turn until
// the user answers a prompt, such as a request to run a tool. The turn has
// not ended, so Waiting stays false and the poll reads nothing from GitHub.
Prompted bool
// Progress is what the agent says the session is doing, beyond the listing.
// The poll fills it in for a session that is still running.
Progress review.Progress
Expand All @@ -39,11 +43,18 @@ func (s BGStatus) Waiting() bool {
return s.Idle && !s.Progress.Active
}

// Need is what a waiting session needs from the user, when the agent named one.
// NeedsUser reports that the session makes no progress until the user answers
// it. Either it ended its turn, or it stopped at a prompt partway through one.
func (s BGStatus) NeedsUser() bool {
return s.Waiting() || s.Prompted
}

// Need is what the session needs from the user, when the agent named one.
// claude's own reading of the conversation can name a need while the session's
// reviewer agents still run. A session that is not waiting therefore has none.
// reviewer agents still run. A session that does not need the user therefore
// has none.
func (s BGStatus) Need() string {
if !s.Waiting() {
if !s.NeedsUser() {
return ""
}
return s.Progress.Needs
Expand Down
19 changes: 19 additions & 0 deletions internal/core/engine/background_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ func TestNeedIsNamedOnlyWhileTheSessionWaits(t *testing.T) {
{name: "waiting", status: BGStatus{Idle: true, Progress: needs}, want: "permission to run gh"},
{name: "working", status: BGStatus{Progress: needs}, want: ""},
{name: "starting", status: BGStatus{Idle: true, Progress: review.Progress{Active: true, Needs: needs.Needs}}, want: ""},
{name: "at a prompt", status: BGStatus{Prompted: true, Progress: needs}, want: "permission to run gh"},
}
for _, tc := range tests {
if got := tc.status.Need(); got != tc.want {
Expand All @@ -44,6 +45,24 @@ func TestNeedIsNamedOnlyWhileTheSessionWaits(t *testing.T) {
}
}

// A prompt stops a session partway through its turn. The session makes no
// progress until the user answers, but its turn has not ended.
func TestASessionAtAPromptNeedsTheUserWithoutEndingItsTurn(t *testing.T) {
prompted := BGStatus{Prompted: true, Progress: review.Progress{Active: true}}
if !prompted.NeedsUser() {
t.Error("a session at a prompt does not need the user")
}
if prompted.Waiting() {
t.Error("a session at a prompt read as having ended its turn")
}
if !(BGStatus{Idle: true}).NeedsUser() {
t.Error("a session that ended its turn does not need the user")
}
if (BGStatus{}).NeedsUser() {
t.Error("a working session needs the user")
}
}

func TestBackgroundNamePrefersTheOneAskedForAndFallsBackToOneWithABackgroundMode(t *testing.T) {
if got := BackgroundName("claude"); got != "claude" {
t.Errorf("BackgroundName(claude) = %q", got)
Expand Down
11 changes: 9 additions & 2 deletions internal/core/engine/claude_background.go
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,12 @@ const bgStateDone = "done"
// also reports it for a few seconds after launch, before the first turn starts.
const bgStatusIdle = "idle"

// bgStatusWaiting is the status claude reports for a session stopped partway
// through its turn at a permission prompt (verified on 2.1.318). The listing
// then reads state "blocked", and the status file reads tempo "blocked" with a
// need such as "approve Bash: <command>".
const bgStatusWaiting = "waiting"

// agentEntry is one element of `claude agents --json`. Interactive sessions
// appear too and carry no ID.
type agentEntry struct {
Expand Down Expand Up @@ -120,8 +126,9 @@ func (Claude) ParseStatus(res exec.Result) (map[string]BGStatus, error) {
// says. `claude stop` on a session still working leaves it as
// "stopped", which is not "done" and would otherwise be polled for
// ever, and the user can stop one from outside docket.
Done: entry.State == bgStateDone || entry.PID == 0,
Idle: entry.Status == bgStatusIdle,
Done: entry.State == bgStateDone || entry.PID == 0,
Idle: entry.Status == bgStatusIdle,
Prompted: entry.Status == bgStatusWaiting,
// claude keeps the process after the session's turn ends, and drops
// it once the session is stopped. That is the difference between a
// session that has to be attached and one a plain resume reopens.
Expand Down
19 changes: 19 additions & 0 deletions internal/core/engine/claude_background_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -346,6 +346,25 @@ func TestParseStatusReportsABlockedSession(t *testing.T) {
}
}

// A session stopped at a permission prompt partway through its turn reports
// waiting, which is neither idle nor busy (verified on 2.1.318). Its turn has not
// ended, so it does not read as idle, which is what makes the poll read GitHub.
func TestParseStatusReportsASessionStoppedAtAPrompt(t *testing.T) {
statuses, err := Claude{}.ParseStatus(exec.Result{
Stdout: `[{"id": "aaaaaaaa", "kind": "background", "state": "blocked", "status": "waiting", "pid": 5}]`,
})
if err != nil {
t.Fatalf("ParseStatus: %v", err)
}
got := statuses["aaaaaaaa"]
if !got.Prompted {
t.Error("a session stopped at a prompt did not read as prompted")
}
if got.Idle || got.Done {
t.Errorf("a session stopped at a prompt read as idle %v or done %v", got.Idle, got.Done)
}
}

// A session that ends its turn without asking anything keeps its process and
// its working state, and only the status says the turn is over. review-code's
// background runs end this way when the last message tells the user what to do
Expand Down
26 changes: 26 additions & 0 deletions internal/core/session/background_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -884,6 +884,32 @@ func TestSubmittingWhileTheSessionWorksLeavesTheSessionRunning(t *testing.T) {
}
}

// A session at a permission prompt is partway through its turn. Archiving after
// the submit stops only a session whose turn has ended, so this one keeps
// running with its clone.
func TestSubmittingWhileTheSessionWaitsAtAPromptLeavesTheSessionRunning(t *testing.T) {
ghc := &fakeGH{login: "haacked", info: prInfo()}
svc, _ := newService(t, ghc, newFakeGit())
runner := bgRunner("")
rec := reopenedWhileWorking(t, svc, ghc, runner)
runner.Results["agents"] = exec.Result{Stdout: bgEntry("6d681a76", bgSession, "blocked", "waiting", true)}

done, _, err := svc.Submit(context.Background(), rec, review.EventComment, "")
if err != nil {
t.Fatalf("Submit: %v", err)
}

if slices.ContainsFunc(runner.Lines(), func(l string) bool { return strings.Contains(l, "claude stop") }) {
t.Errorf("the submit stopped a session waiting at a prompt: %v", runner.Lines())
}
if _, err := os.Stat(rec.Dir); err != nil {
t.Errorf("the clone at %s was deleted under a session waiting at a prompt: %v", rec.Dir, err)
}
if !strings.Contains(done.Err, "still working") {
t.Errorf("the row does not say the session was left running: %q", done.Err)
}
}

// review-code ends its turn once the draft is posted, and claude goes on holding
// the session. Submitting from the dashboard is the usual end of that review.
func TestSubmittingADraftWhoseSessionEndedItsTurnStopsTheSession(t *testing.T) {
Expand Down
26 changes: 26 additions & 0 deletions internal/core/session/blocked_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,32 @@ func TestPollKeepsABlockedSessionWithNothingPostedRunning(t *testing.T) {
}
}

// A permission prompt stops a session partway through its turn, and claude lists
// it as waiting rather than idle. The turn has not ended, so the poll reads
// nothing from GitHub, even when a draft of mine is already there.
func TestPollReadsNothingFromGitHubForASessionAtAPermissionPrompt(t *testing.T) {
ghc := &fakeGH{login: "haacked", info: prInfo()}
svc, _ := newService(t, ghc, newFakeGit())
writeJobState(t, defaultJobs(t, svc), "6d681a76", `{"tempo": "blocked", "needs": "approve Bash: gh pr diff 7"}`)
rec := startedBackground(t, svc, bgRunner(bgEntry("6d681a76", bgSession, "blocked", "waiting", true)))
ghc.reviews = []review.GHReview{myPending()}
before := ghc.reads

records, statuses, err := svc.PollBackground(context.Background())
if err != nil {
t.Fatalf("PollBackground: %v", err)
}
if got := ghc.reads - before; got != 0 {
t.Errorf("read GitHub %d times for a session whose turn has not ended, want 0", got)
}
if records[0].State != review.StateReviewing {
t.Errorf("state = %q, want the review still running", records[0].State)
}
if status := statuses[rec.ID]; !status.Prompted || status.Need() != "approve Bash: gh pr diff 7" {
t.Errorf("status = %+v, want a session at a prompt that names it", status)
}
}

// A session stays blocked until the user answers it. Reading GitHub on every
// tick for that long would spend two API calls per session every 15 seconds.
func TestPollReadsGitHubOnceForEachStretchASessionIsBlocked(t *testing.T) {
Expand Down
2 changes: 1 addition & 1 deletion internal/mcp/mcp.go
Original file line number Diff line number Diff line change
Expand Up @@ -402,7 +402,7 @@ func view(rec review.Record, statuses map[string]engine.BGStatus) Review {
p := status.Progress
out.Progress = &Progress{
Detail: p.Detail,
Waiting: status.Waiting(),
Waiting: status.NeedsUser(),
Needs: status.Need(),
Agents: p.Agents,
UpdatedAt: p.UpdatedAt,
Expand Down
18 changes: 18 additions & 0 deletions internal/mcp/mcp_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -580,6 +580,24 @@ func TestListReviewsSaysWhatAWaitingSessionNeeds(t *testing.T) {
}
}

// A permission prompt stops the session partway through its turn, and claude's
// listing reports it as waiting rather than idle.
func TestListReviewsSaysASessionAtAPermissionPromptIsWaiting(t *testing.T) {
f := newFixture(t)
f.started(t)
f.agents("blocked", "waiting")
f.jobState(t, `{"tempo":"blocked","needs":"approve Bash: gh pr diff 7"}`)

got := f.listedOne(t)

if got.State != string(review.StateReviewing) || got.Progress == nil {
t.Fatalf("review = %+v, want reviewing with progress", got)
}
if p := *got.Progress; !p.Waiting || p.Needs != "approve Bash: gh pr diff 7" {
t.Errorf("progress = %+v, want waiting on the permission prompt", p)
}
}

// Nothing else moves a finished background session on while the TUI is closed.
// Listing therefore reads the agent and GitHub rather than the index alone.
func TestListReviewsMovesAFinishedSessionToDrafted(t *testing.T) {
Expand Down
12 changes: 5 additions & 7 deletions internal/tui/app.go
Original file line number Diff line number Diff line change
Expand Up @@ -1676,8 +1676,7 @@ func (a App) applyPoll(polled bgPolledMsg) (tea.Model, tea.Cmd) {
// change screens.
a.err = polled.err
if polled.records != nil {
a.dash = a.dash.SetRecords(polled.records)
a.dash.Background = polled.progress
a.dash = a.dash.SetRecords(polled.records).SetBackground(polled.progress)
}
return a.armPoll()
}
Expand Down Expand Up @@ -1708,16 +1707,15 @@ func (a App) pollBackground() tea.Cmd {
}

// progressFor hands each session's progress to the dashboard, which holds no
// engine to ask. A session that is Waiting is waiting for the user. The
// dashboard draws a row as waiting when the row names a need, so a waiting
// session always names one. A working session with no detail shows the agent's
// state.
// engine to ask. The dashboard draws a row as waiting when the row names a need,
// so a session that needs the user always names one. A working session with no
// detail shows the agent's state.
func progressFor(statuses map[string]engine.BGStatus) map[string]review.Progress {
progress := make(map[string]review.Progress, len(statuses))
for id, status := range statuses {
p := status.Progress
p.Needs = status.Need()
if status.Waiting() {
if status.NeedsUser() {
p.Needs = cmp.Or(p.Needs, "your input")
} else {
p.Detail = cmp.Or(p.Detail, status.State)
Expand Down
4 changes: 4 additions & 0 deletions internal/tui/app_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -370,6 +370,7 @@ func TestProgressForMarksOnlyASessionThatEndedItsTurnAsWaiting(t *testing.T) {
"named": {State: "blocked", Idle: true, Progress: review.Progress{Needs: "permission to run gh"}},
"busy": {State: "blocked", Progress: review.Progress{Needs: "results from 5 reviewers"}},
"starting": {State: "working", Idle: true, Progress: review.Progress{Detail: "starting…", Active: true}},
"prompted": {State: "blocked", Prompted: true, Progress: review.Progress{Detail: "starting…", Active: true}},
})
if got["bare"].Needs == "" {
t.Error("a session that ended its turn with no status file does not read as waiting")
Expand All @@ -386,6 +387,9 @@ func TestProgressForMarksOnlyASessionThatEndedItsTurnAsWaiting(t *testing.T) {
if got["starting"].Needs != "" {
t.Errorf("needs = %q, want none while the session starts", got["starting"].Needs)
}
if got["prompted"].Needs == "" {
t.Error("a session stopped at a permission prompt does not read as waiting")
}
}

// claude's status file can be missing or unreadable. The row still says
Expand Down
48 changes: 38 additions & 10 deletions internal/tui/screens/dashboard/dashboard.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,21 @@ type Styles struct {
Err lipgloss.Style
}

// groups is the order states appear in. Archived and abandoned records are in
// the last group, which stays hidden until the user asks for it.
var groups = []struct {
type group struct {
Title string
States []review.State
Closed bool
}{
// Waiting holds the rows whose session needs the user. Every other group
// leaves them out.
Waiting bool
Closed bool
}

// groups is the order states appear in. Archived and abandoned records are in
// the last group, which stays hidden until the user asks for it.
var groups = []group{
// A session that needs the user makes no progress until the user answers
// it, so its row goes above every other.
{Title: "Waiting for you", States: []review.State{review.StateReviewing}, Waiting: true},
{Title: "Reviewing", States: []review.State{review.StateReviewing, review.StatePreparing}},
{Title: "Did not start", States: []review.State{review.StateNotStarted}},
{Title: "Drafted", States: []review.State{review.StateDrafted}},
Expand Down Expand Up @@ -83,6 +91,19 @@ func New(styles Styles) Model {
func (m Model) SetRecords(records []review.Record) Model {
selected, had := m.Selected()
m.Records = records
return m.follow(selected, had)
}

// SetBackground replaces what each session is doing and keeps the cursor on the
// record it was on. A session that starts or stops needing the user moves its
// row between groups.
func (m Model) SetBackground(progress map[string]review.Progress) Model {
selected, had := m.Selected()
m.Background = progress
return m.follow(selected, had)
}

func (m Model) follow(selected review.Record, had bool) Model {
if had {
if i := slices.IndexFunc(m.rows(), func(r review.Record) bool { return r.ID == selected.ID }); i >= 0 {
m.Cursor = i
Expand Down Expand Up @@ -179,15 +200,15 @@ func (m Model) rows() []review.Record {
if group.Closed && !m.ShowArchived {
continue
}
rows = append(rows, m.inGroup(group.States)...)
rows = append(rows, m.inGroup(group)...)
}
return rows
}

func (m Model) inGroup(states []review.State) []review.Record {
func (m Model) inGroup(g group) []review.Record {
var out []review.Record
for _, rec := range m.Records {
if slices.Contains(states, rec.State) {
if slices.Contains(g.States, rec.State) && m.waiting(rec) == g.Waiting {
out = append(out, rec)
}
}
Expand All @@ -205,7 +226,7 @@ func (m Model) View() string {
if group.Closed && !m.ShowArchived {
continue
}
records := m.inGroup(group.States)
records := m.inGroup(group)
if len(records) == 0 {
continue
}
Expand Down Expand Up @@ -272,6 +293,13 @@ func (m Model) meta(rec review.Record) string {
return m.Styles.Dim.Render("· ") + m.Spinner.Render(note) + " " + meta
}

// waiting reports that the row's session needs the user. The root names a need
// for every session that needs the user.
func (m Model) waiting(rec review.Record) bool {
act, ok := m.Background[rec.ID]
return ok && rec.BackgroundRunning() && act.Needs != ""
}

// activity is the line under a running background row that says what its
// session is doing, and whether the session is waiting for the user. It is
// empty for any other row, and for a session the last poll said nothing about.
Expand All @@ -280,7 +308,7 @@ func (m Model) activity(rec review.Record) (string, bool) {
if !ok || !rec.BackgroundRunning() {
return "", false
}
if act.Needs != "" {
if m.waiting(rec) {
parts := []string{"waiting for you: " + act.Needs, "enter opens it"}
if act.Detail != "" {
parts = append(parts, act.Detail)
Expand Down
Loading