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
10 changes: 5 additions & 5 deletions docs/harnesses.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,13 @@ row, and its name in the `harness-names` lane. No other package names it.
## Launch lines and tiers

They live only in the operator's `hosts.toml`. `{model}` and `{effort}`
come from the task's tier; `{name}` is `<repo>-<task>`.
come from the task's tier; `{name}` is `<repo>-<task>`; `{title}` is the
title the apps show.

```toml
[harness.claude]
max_sessions = 8 # across all hosts: a budget lever
launch = "{bin} --permission-mode auto --model {model} --effort {effort} -n {name} --remote-control {name}"
launch = "{bin} --permission-mode auto --model {model} --effort {effort} -n {title} --remote-control {title}"
tiers.deep = { model = "claude-opus-5-5", effort = "high" }
tiers.standard = { model = "claude-sonnet-5-5", effort = "high" }
tiers.light = { model = "claude-haiku-5-5", effort = "medium" }
Expand All @@ -52,10 +53,9 @@ tiers.light = { model = "gpt-6-luna", effort = "medium" }
Rules for the lines:

- **Claude:** keep `--permission-mode auto`, whose classifier decides most
actions without a prompt, and `-n {name} --remote-control {name}`, which
name the session in the apps.
actions without a prompt, and `-n {title} --remote-control {title}`.
- **Codex:** keep the `workspace-write` sandbox with auto-review deciding
what crosses it (never `approval_policy = "never"`, which leaves it nothing
to review), and keep network access, for `gh` and `git push`. Set no
writable root and no `--add-dir`: a joined session refuses both, so such a
line keeps every session embedded, and `spawn` warns.
line keeps sessions embedded, and `spawn` warns.
4 changes: 2 additions & 2 deletions docs/hosts-and-sessions.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,8 @@ An attempt is the session registry: the server's record of a task's or plan's
session (host, harness, run ID, tmux window, state; `engine attempt list`).
`engine ps`, `engine attach` and the dashboard resolve a session through it.

A session is named `<repo>-<task>` on every surface: the tmux window, the
remote-control name and part of the branch.
A session is named `<repo>-<task>` in its tmux window, run ID and branch;
the harness apps show its title, `t<n> · <title>` (`p<n>` for a planner).

## Starting a session

Expand Down
2 changes: 1 addition & 1 deletion internal/controlrun/coordinator_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,7 @@ func TestPlannerDispatchAndInvalidPlanBlock(t *testing.T) {
}
pass(t, c)
for _, req := range h.launches {
if req.Spawn.Tier != "deep" || req.Spawn.Task != control.Number(plan.ID) {
if req.Spawn.Tier != "deep" || req.Spawn.Task != control.Number(plan.ID) || req.Spawn.Title != plan.ID+" · Feature" {
t.Fatal(req)
}
}
Expand Down
3 changes: 2 additions & 1 deletion internal/controlrun/dispatch.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import (
"github.com/dinoderek/engine/internal/hosts"
"github.com/dinoderek/engine/internal/reconcile"
"github.com/dinoderek/engine/internal/remote"
"github.com/dinoderek/engine/internal/session"
)

// dispatch reserves an attempt for a's item, at its version in st, and
Expand Down Expand Up @@ -53,7 +54,7 @@ func (c *Coordinator) launch(st control.State, at control.Attempt, credential st
}
repo := st.Items[item.Repo]
req := hostops.ControlRequest{URL: c.URL, Credential: credential, Attempt: at.ID, Remote: repo.Remote,
Spawn: hostops.SpawnRequest{Repo: repo.Slug, Task: control.Number(item.ID), Feature: item.Plan, Mode: hostops.HandsOff,
Spawn: hostops.SpawnRequest{Repo: repo.Slug, Task: control.Number(item.ID), Feature: item.Plan, Title: session.Title(item.ID, item.Title), Mode: hostops.HandsOff,
Harness: at.Harness, Tier: tier, Model: model.Model, Effort: model.Effort, RunID: at.RunID, Heavy: cfg.Heavy(item.Requires),
Resume: resume, Kickoff: kickoff(item, at, reviewer.Model)}}
spawned, err := remote.ControlSpawn(c.Client(cfg.Hosts[at.Host]), req)
Expand Down
25 changes: 25 additions & 0 deletions internal/harness/claude/agents_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -71,3 +71,28 @@ func TestAgentState(t *testing.T) {
}
}
}

// A run's session is the one its launch named, by the window's name or the
// run's title, else the one in its worktree: the apps can rename a session.
func TestFindAgent(t *testing.T) {
run := session.Run{Record: session.Record{Name: "r-7", Title: "t7 · Fix it", Worktree: "/w/r-7"}}
tests := []struct {
name string
run session.Run
agents []Agent
want int // the PID found; 0 is none
}{
{"by the window's name", run, []Agent{{PID: 1, Name: "other"}, {PID: 2, Name: "r-7"}}, 2},
{"by the run's title", run, []Agent{{PID: 1, Name: "t7 · Fix it", CWD: "/elsewhere"}}, 1},
{"renamed, by its worktree", run, []Agent{{PID: 1, Name: "Renamed", CWD: "/w/other"}, {PID: 2, Name: "Renamed", CWD: "/w/r-7/"}}, 2},
{"a name beats another session's worktree", run, []Agent{{PID: 1, CWD: "/w/r-7"}, {PID: 2, Name: "t7 · Fix it"}}, 2},
{"no title matches no unnamed session", session.Run{Record: session.Record{Name: "r-7"}}, []Agent{{PID: 1}}, 0},
{"none", run, []Agent{{PID: 1, Name: "r-70", CWD: "/w/r-70"}}, 0},
}
for _, tt := range tests {
ag, ok := findAgent(tt.run.Record.Name, tt.run, tt.agents)
if got := map[bool]int{true: ag.PID}[ok]; got != tt.want {
t.Errorf("%s: found %d, want %d", tt.name, got, tt.want)
}
}
}
32 changes: 23 additions & 9 deletions internal/harness/claude/claude.go
Original file line number Diff line number Diff line change
Expand Up @@ -135,26 +135,40 @@ func (a Adapter) Observe(_ context.Context, host hosts.Host, runs map[string]ses
}

// probe is the state of the window called name, whose newest run is r: the
// state of the session of that name, unless a limit marker makes a live,
// state of the run's session (findAgent), unless a limit marker makes a live,
// non-busy session limited.
func probe(name string, r session.Run, agents []Agent) (harness.State, bool) {
var st harness.State
for _, ag := range agents {
if ag.Name == name {
st.State = AgentState(ag)
if st.State == session.StateWaiting {
st.WaitingFor = ag.WaitingFor
}
st.Background = st.State == session.StateWorking && turnEnded(r.Dir, ag.SessionID)
break
if ag, ok := findAgent(name, r, agents); ok {
st.State = AgentState(ag)
if st.State == session.StateWaiting {
st.WaitingFor = ag.WaitingFor
}
st.Background = st.State == session.StateWorking && turnEnded(r.Dir, ag.SessionID)
}
if l, ok := ReadLimit(r.Dir); ok && st.State != session.StateWorking {
st = harness.State{State: session.StateLimited, ResetsAt: l.ResetsAt}
}
return st, st.State != ""
}

// findAgent is the run's session: the one the launch line named, by the
// window's name or the run's title, else the one in the run's worktree, which
// still finds a session renamed in the apps.
func findAgent(name string, r session.Run, agents []Agent) (Agent, bool) {
for _, ag := range agents {
if ag.Name == name || ag.Name != "" && ag.Name == r.Record.Title {
return ag, true
}
}
for _, ag := range agents {
if r.Record.Worktree != "" && filepath.Clean(ag.CWD) == filepath.Clean(r.Record.Worktree) {
return ag, true
}
}
return Agent{}, false
}

// turnEnded reports whether a session that Claude Code lists as busy has
// ended its last turn: the newest hook event in its run's state file is a
// Stop, from the same session when both name one. Claude Code stays busy
Expand Down
17 changes: 1 addition & 16 deletions internal/harness/codex/label.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@ import (
"fmt"
"os"
"path/filepath"
"strconv"
"strings"
"time"

Expand Down Expand Up @@ -77,20 +76,6 @@ func LabelPending(runDir string, now time.Time) bool {
// filed the project for.
const projectKey = "engine_repo"

// ThreadTitle is the title of a task's thread: "<plan> > <task>", or the
// task alone when it belongs to no plan. Runs name them by their server IDs
// (p12, t34).
func ThreadTitle(rec session.Record) string {
task := rec.Task
if t, err := session.ParseRef(rec.Task); err == nil {
task = "t" + strconv.Itoa(t.Number)
}
if rec.Feature == "" {
return task
}
return rec.Feature + " > " + task
}

// LabelThread titles a joined run's thread and files it under its repo's
// project, through engine's daemon, and records the outcome in LabelFile. It
// does nothing once the thread is labelled, after the last attempt, or while
Expand Down Expand Up @@ -143,7 +128,7 @@ func labelFor(home string, rec session.Record, threadID string) (LabelRequest, e
if err != nil {
return LabelRequest{}, err
}
return LabelRequest{ThreadID: threadID, Title: ThreadTitle(rec), Project: repo.Name, Repo: repo.String(), Root: root}, nil
return LabelRequest{ThreadID: threadID, Title: rec.DisplayTitle(), Project: repo.Name, Repo: repo.String(), Root: root}, nil
}

func (a Adapter) sendLabel(req LabelRequest) error {
Expand Down
20 changes: 10 additions & 10 deletions internal/harness/codex/label_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,19 +17,19 @@ import (
"github.com/dinoderek/engine/internal/session"
)

func TestThreadTitle(t *testing.T) {
func TestLabelTitleIsTheRunsTitle(t *testing.T) {
tests := []struct {
name string
rec session.Record
want string
}{
{"a server task in a plan", session.Record{Control: true, Repo: "o/engine", Task: "o/engine#" + "34", Feature: "p12"}, "p12 > t34"},
{"a server task in no plan", session.Record{Control: true, Repo: "o/engine", Task: "o/engine#" + "34"}, "t34"},
{"an unparsable task stays as recorded", session.Record{Control: true, Repo: "o/engine", Task: "odd"}, "odd"},
{"a run with a title", session.Record{Name: "engine-34", Title: "t34 · Fix it"}, "t34 · Fix it"},
{"a run spawned without one shows its name", session.Record{Name: "engine-34"}, "engine-34"},
}
for _, tt := range tests {
if got := ThreadTitle(tt.rec); got != tt.want {
t.Errorf("%s: %q, want %q", tt.name, got, tt.want)
req, err := labelFor(t.TempDir(), session.Record{Repo: "o/engine", Name: tt.rec.Name, Title: tt.rec.Title}, "th1")
if err != nil || req.Title != tt.want {
t.Errorf("%s: title %q (err %v), want %q", tt.name, req.Title, err, tt.want)
}
}
}
Expand Down Expand Up @@ -238,13 +238,13 @@ func readLabel(t *testing.T, dir string) labelRecord {
func TestLabelCodexThreadStopsOnceLabelled(t *testing.T) {
d, reqs, where := labelDeps(t, nil)
dir := t.TempDir()
rec := session.Record{Repo: "o/engine", Task: "o/engine#" + "138", Feature: "p12"}
rec := session.Record{Repo: "o/engine", Task: "o/engine#" + "138", Feature: "p12", Title: "t138 · Label threads"}
for range 2 {
if err := d.LabelThread(dir, rec, "th1"); err != nil {
t.Fatal(err)
}
}
want := LabelRequest{ThreadID: "th1", Title: "p12 > t138", Project: "engine", Repo: "o/engine",
want := LabelRequest{ThreadID: "th1", Title: "t138 · Label threads", Project: "engine", Repo: "o/engine",
Root: filepath.Join(d.Home, filepath.FromSlash(session.ReposDir), "o", "engine")}
if !reflect.DeepEqual(*reqs, []LabelRequest{want}) {
t.Errorf("requests %+v, want one %+v", *reqs, want)
Expand All @@ -266,7 +266,7 @@ func TestLabelCodexThreadStopsOnceLabelled(t *testing.T) {
func TestLabelCodexThreadRetriesAFailureAFewTimes(t *testing.T) {
d, reqs, _ := labelDeps(t, errors.New("daemon down"))
dir := t.TempDir()
rec := session.Record{Control: true, Repo: "o/engine", Task: "o/engine#" + "34", Feature: "p12"}
rec := session.Record{Control: true, Repo: "o/engine", Task: "o/engine#" + "34", Feature: "p12", Title: "t34 · Fix it"}
now := fixedNow()
d.Now = func() time.Time { return now }
for i := range labelAttempts {
Expand All @@ -287,7 +287,7 @@ func TestLabelCodexThreadRetriesAFailureAFewTimes(t *testing.T) {
t.Errorf("after the last attempt: err %v, %d requests, want %d", err, len(*reqs), labelAttempts)
}
got := readLabel(t, dir)
if got.Error != "daemon down" || got.Attempts != labelAttempts || got.Title != "p12 > t34" ||
if got.Error != "daemon down" || got.Attempts != labelAttempts || got.Title != "t34 · Fix it" ||
got.Root != filepath.Join(d.Home, filepath.FromSlash(session.ControlReposDir), "o", "engine") {
t.Errorf("record %+v", got)
}
Expand Down
2 changes: 1 addition & 1 deletion internal/hostops/fixture_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ reserve_gb = 8

[harness.claude]
max_sessions = 8
launch = "{bin} --permission-mode auto --model {model} --effort {effort} -n {name} --remote-control {name}"
launch = "{bin} --permission-mode auto --model {model} --effort {effort} -n {title} --remote-control {title}"
tiers.deep = { model = "opus-x", effort = "high" }
tiers.standard = { model = "sonnet-x", effort = "high" }
tiers.light = { model = "haiku-x", effort = "medium" }
Expand Down
10 changes: 7 additions & 3 deletions internal/hostops/spawn.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,10 @@ type SpawnRequest struct {
Repo string // owner/name
Task int
Feature string // owner/repo#n, or empty
Mode string
// Title is how the harness apps show the session (session.Title); empty
// shows its name. It is omitted when empty, like Resume.
Title string `json:",omitempty"`
Mode string
// Harness names an adapter; empty is the default.
Harness string
Tier string
Expand Down Expand Up @@ -94,7 +97,7 @@ func Spawn(d Deps, r SpawnRequest) (Spawned, error) {
"git -C %s worktree remove --force %s && git -C %s branch -D %s",
hosts.ShellWord(clone.Path), hosts.ShellWord(wt.Path), hosts.ShellWord(clone.Path), wt.Branch)
line, err := s.cfg.LaunchLine(s.host, hosts.Launch{
Harness: s.h.Name(), Name: s.name, Clone: clone.Path, Home: d.Home,
Harness: s.h.Name(), Name: s.name, Title: s.Title, Clone: clone.Path, Home: d.Home,
Model: hosts.TierModel{Model: s.Model, Effort: s.Effort},
})
if err != nil {
Expand Down Expand Up @@ -209,6 +212,7 @@ func (s *spawn) checkRequest(home string) error {
}
}
s.name = session.TaskName(s.repo, s.Task)
s.Title = session.CleanTitle(s.Title)
if s.runDir, err = session.RunDir(home, s.RunID); err != nil {
problems = append(problems, err.Error())
} else if !strings.HasPrefix(s.RunID, s.name+"-") {
Expand All @@ -228,7 +232,7 @@ func (s spawn) record(wt session.Worktree, window, log string, d Deps) session.R
Schema: session.RecordSchema, RunID: s.RunID, Repo: s.repo.String(),
Task: session.Ref{Repo: s.repo.String(), Number: s.Task}.String(), Feature: s.Feature,
Host: s.host.Name, Harness: s.h.Name(), Tier: s.Tier, Model: s.Model, Effort: s.Effort,
Mode: s.Mode, Heavy: s.Heavy, Name: s.name, Tmux: session.Name + ":" + window,
Mode: s.Mode, Heavy: s.Heavy, Name: s.name, Title: s.Title, Tmux: session.Name + ":" + window,
Branch: wt.Branch, Worktree: wt.Path, PaneLog: log, Spawned: d.Now().UTC(),
}
}
8 changes: 7 additions & 1 deletion internal/hostops/spawn_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ func TestSpawn(t *testing.T) {
tm := &tmuxFake{windows: []string{"@1 %1 0 other"}}
req := request()
req.Heavy = true
req.Title = "t7 · Fix\nthe tab" // the host cleans what it is sent
got, err := Spawn(spawnDeps(t, h, git.run, tm, nil), req)
if err != nil {
t.Fatal(err)
Expand All @@ -54,11 +55,16 @@ func TestSpawn(t *testing.T) {
t.Fatalf("run.json: %s, %v", data, err)
}
wantRec := session.Record{Schema: 1, RunID: "r-7-20260102T030405Z", Repo: "o/r", Task: ref(7), Feature: ref(3), Host: "mac",
Harness: "claude", Tier: "deep", Model: "opus-x", Effort: "high", Mode: HandsOff, Heavy: true, Name: "r-7", Tmux: "engine:@9",
Harness: "claude", Tier: "deep", Model: "opus-x", Effort: "high", Mode: HandsOff, Heavy: true, Name: "r-7", Title: "t7 · Fix the tab", Tmux: "engine:@9",
Branch: "task/r-7", Worktree: worktree, PaneLog: filepath.Join(runDir, session.PaneLog), Spawned: fixedNow()}
if rec != wantRec {
t.Errorf("run.json\n got %+v\nwant %+v", rec, wantRec)
}
// The window's command quotes the launch line once more.
title := hosts.ShellWord("t7 · Fix the tab")
if want := strings.ReplaceAll("-n "+title+" --remote-control "+title, "'", `'\''`); !strings.Contains(tm.command, want) {
t.Errorf("the launch does not title the session: %s", tm.command)
}
if trust, _ := os.ReadFile(filepath.Join(h.dir, ".claude.json")); !strings.Contains(string(trust), worktree) {
t.Errorf("the worktree is not trusted: %s", trust)
}
Expand Down
2 changes: 1 addition & 1 deletion internal/hosts/decode.go
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ func decode(root *node) (*Config, *Error) {
}

// launchPlaceholders are the {words} a launch line may use.
var launchPlaceholders = []string{"bin", "model", "effort", "name", "clone"}
var launchPlaceholders = []string{"bin", "model", "effort", "name", "title", "clone"}

var placeholder = regexp.MustCompile(`\{([A-Za-z_]+)\}`)

Expand Down
4 changes: 2 additions & 2 deletions internal/hosts/hosts.go
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ type TierModel struct {
type Harness struct {
// MaxSessions caps the harness across all hosts.
MaxSessions int
// Launch is the launch line, with {bin}, {model}, {effort}, {name} and
// {clone} placeholders.
// Launch is the launch line, with {bin}, {model}, {effort}, {name},
// {title} and {clone} placeholders.
Launch string
Tiers map[Tier]TierModel
}
Expand Down
4 changes: 4 additions & 0 deletions internal/hosts/launch.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package hosts

import (
"cmp"
"fmt"
"path/filepath"
"regexp"
Expand All @@ -14,6 +15,8 @@ type Launch struct {
Tier Tier
// Name is the session name, <repo>-<task>.
Name string
// Title is how the harness apps show the session; empty is Name.
Title string
// Clone is engine's clone of the task's repo.
Clone string
// Home expands a bin path that starts with ~/.
Expand Down Expand Up @@ -75,6 +78,7 @@ func (c *Config) LaunchLine(h Host, l Launch) (string, error) {
"{model}", ShellWord(model.Model),
"{effort}", ShellWord(model.Effort),
"{name}", ShellWord(l.Name),
"{title}", ShellWord(cmp.Or(l.Title, l.Name)),
"{clone}", ShellWord(l.Clone),
)
return r.Replace(harness.Launch), nil
Expand Down
10 changes: 8 additions & 2 deletions internal/hosts/launch_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,20 @@ func TestLaunchLineExpandsEveryPlaceholder(t *testing.T) {
t.Fatal(err)
}
mac := c.Hosts["mac"]
got, err := c.LaunchLine(mac, Launch{Harness: "claude", Tier: Deep, Name: "boga3-412", Clone: "/c/o/boga3", Home: "/home/me"})
got, err := c.LaunchLine(mac, Launch{Harness: "claude", Tier: Deep, Name: "boga3-412", Title: "t412 · Fix Bob's tab", Clone: "/c/o/boga3", Home: "/home/me"})
if err != nil {
t.Fatal(err)
}
want := "/home/me/.local/bin/claude --permission-mode auto --model claude-opus-5-5 --effort high -n boga3-412 --remote-control boga3-412"
title := `'t412 · Fix Bob'\''s tab'`
want := "/home/me/.local/bin/claude --permission-mode auto --model claude-opus-5-5 --effort high -n " + title + " --remote-control " + title
if got != want {
t.Errorf("claude:\n got %s\nwant %s", got, want)
}
// A run without a title shows its name.
got, err = c.LaunchLine(mac, Launch{Harness: "claude", Tier: Deep, Name: "boga3-412", Home: "/home/me"})
if err != nil || !strings.HasSuffix(got, " -n boga3-412 --remote-control boga3-412") {
t.Errorf("claude without a title: %s, %v", got, err)
}
got, err = c.LaunchLine(mac, Launch{Harness: "codex", Tier: Light, Name: "r-1", Clone: "/c/o/r", Home: "/home/me"})
if err != nil {
t.Fatal(err)
Expand Down
8 changes: 6 additions & 2 deletions internal/session/record.go
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,12 @@ type Record struct {
// Heavy is true when the task's card requires a heavy capability: the
// run takes one of its host's heavy slots.
Heavy bool `json:"heavy"`
// Name is the session name: the tmux window and the Remote Control name.
Name string `json:"name"`
// Name is the session name: the tmux window, and the stem of the branch
// and the run ID.
Name string `json:"name"`
// Title is how the harness apps show the session (Title); a run spawned
// without one shows its Name.
Title string `json:"title,omitempty"`
Tmux string `json:"tmux"` // the window's target, such as engine:@3
Branch string `json:"branch"`
Worktree string `json:"worktree"`
Expand Down
Loading
Loading