320 — tp overview: a story's agent in a terminal on the page (#320)

Roadmap: #317

Why

tp overview shows a story as "In development" and does nothing more for it: the agent that builds it is started by hand, in a terminal or an editor window found some other way, and the board cannot say whether one is running at all. The agents the board does start, for an interview and for an answer, are shown on claude.ai/code, die with tp overview, and cannot be reached from a terminal.

#317 wants the board to be the control point for the agents working on stories. This is its first step: an accepted story's agent started from its card, and its terminal seen and typed into on a page of the board.

What changes

  • tp overview, a card in "In development": a button, "develop", when the story has no agent session, and a link, "terminal", when it has.
  • "develop": starts claude in the story's worktree, in a tmux session of the story's own, and sends the browser to its terminal page.
  • tp overview, the terminal page: the session's terminal, live; keys typed on the page go to it. It names the tmux command that attaches to the same session from a terminal, and links back to the board.
  • The session is tmux's, not tp overview's: it outlasts the page and tp overview, and a tp overview started later finds it.
  • ROADMAP.md: a new epic, "Development cycle harness": tp overview as the harness of the development cycle, the agents that interview, build and review stories started, seen and steered from the board. #317 is placed in it by tp idea roadmap once this story has landed the heading.
  • docs/overview.md: "In development" describes the button, the page and the session; dir is needed to develop as well; tmux is named as what "develop" needs.

Acceptance

R is the repository's name, N the issue, story/<N>-<slug> the story's branch on the forge, the worktree <dir>/R-<N>-<slug>, where tp idea story makes it, and the session the tmux session named R-N, a character tmux does not take in a name replaced by -.

The card

Card Session R-N Has
in "In development", blocked or not none a button, "develop"
in "In development", blocked or not exists a link, "terminal", to the terminal page; no button
in any other column either neither
any, tmux not on the PATH — the button, as with no session

Whether a session exists is read when the forges are, on a load and on each refresh.

The press

The agent is claude, without --remote-control, in the worktree, its first message: build story #N; run tp story query and do what it says. The press writes nothing to a forge.

The forge's dir The worktree tmux, claude Session R-N "develop"
set a directory both on the PATH none the session started, claude in it; the browser sent to the terminal page
set a directory both on the PATH exists none started; the browser sent to the terminal page
not set — — — nothing started; the page names the user config and the forge
set no branch on the forge, so none known — — nothing started; the page says why
set absent, or not a directory — — nothing started; the page names the path
set a directory tmux not on the PATH — nothing started; the page says so
set a directory claude not on the PATH — nothing started; the page says so
set a directory both, tmux refusing the session none nothing started; the page gives tmux's words

The story is read again at the press: one no longer open, story and defined starts nothing, and the page says why.

The terminal page

Session R-N The page
exists its terminal as it now stands, then live: what the agent prints appears as it is printed; keys typed on the page reach the agent
exists, the page resized the terminal takes the page's size
exists, open on two pages, or on a page and in a terminal each shows it; keys from either reach the agent
exists, the page closed the session and its agent carry on; opened again, the terminal as it then stands
ends while the page is open (the agent has ended) the page says the session has ended; what it last showed stays; a link back
none when the page is asked for says no agent is running for the story; a link back

The page also has the repository and the issue, linked to the forge, the command tmux attach -t R-N, and "back" to the board. What draws the terminal is served by tp overview itself: nothing is fetched from elsewhere.

The session

Event The session
tp overview stops carries on, its agent with it
a tp overview started later finds it: the card links "terminal", and the page shows it
tmux attach -t R-N in a terminal the same session as the page shows
the agent ends ends; the card has "develop" again

The guard

Request Outcome
the press without the secret tp overview made when it started refused; nothing started
the terminal's connection without the secret, or opened by a page that tp overview did not serve refused; nothing shown, no key taken
the page, the press or the connection under a name other than this machine's own refused
the press or the page for a repository below level 3, or of a forge not in the user config refused

Linux and macOS.

Out of scope

  • "interview" and "answer": they start their agents as they do now, under --remote-control and ending with tp overview. Moving them to a session and a terminal page of this kind is a later story.
  • An agent in the worktree that is not in session R-N: one in an editor or another terminal is not seen, and "develop" starts a second beside it.
  • Ending a session from the board. The agent is ended in its terminal, or tmux kill-session -t R-N.
  • A reviewer's agent for a card in "In review", and any agent for a story not yet defined.
  • Telling an agent anything from the board other than by typing in its terminal; one session that talks to the board (#317).
  • Two repositories of the same name on two forges: they share the session name.
  • Showing on the card what the agent is doing, or that it waits for input.
  • A page reached from another machine.

Decisions

The session is tmux's rather than a terminal tp overview holds, as it holds an interview's: a story is built over a longer time than tp overview is left running, and the same session can then be reached from a terminal. It costs a dependency, tmux, that the press names when it is missing. An ADR if the fork is thought worth one.

Done when

  • tests express the acceptance table and pass
  • spec updated
  • the epic's heading in ROADMAP.md; #317 stays open, this being its first step
  • changelog entry
  • issue closed with a link to the release