311 — tp overview: answer a called story from its card (#311)

Why

A story whose agent has called shows on tp overview as a card flagged "blocked", and that is all the page does for it. To answer, the human finds the reason in the issue's comments on the forge, reads the story in another tab, goes to the story's worktree in a terminal for tp story answer, and then starts an agent there to carry on. The board is where the human learns they are needed; it should also be where they answer, and the answer should set the work going again.

What changes

  • tp overview, a blocked card: a link, "answer", to a page of that story.
  • tp overview, the answer page: the story, why it was called, a comment box, a button "answer" and a link "back" to the board. It also says that "answer" starts an agent in the story's worktree, and that a session left open there should be closed first.
  • "answer": does what tp story answer TEXT does, against the forge (the comment Answered: TEXT, then called taken off), then starts an agent on this machine in the story's worktree, as "interview" starts one in the checkout, and sends the browser to its session.
  • docs/overview.md: "Blocked" describes the page, the press and the note on open sessions; dir is needed to resume as well as to interview; "answer" joins "accept" and "to idea" as what writes to a forge.
  • docs/story.md: "Calling for a human" names the page as the other way to answer.

Acceptance

R is the repository, N the issue, story/<N>-<slug> the story's branch on the forge, and the worktree <dir>/R-<N>-<slug>, where tp idea story makes it.

The card

Card Has
flagged "blocked", in any column a link, "answer", to the answer page of that story; pressing it writes nothing
not blocked no such link

The page

Part The forge has Shown
the story the branch, and the story file on it the file rendered in full, and a link to it on the forge
the story no branch, or no story file on it that the story was not found, and a link to the issue; the call can still be answered
why it was called Called: comments, none Answered: every Called: comment, oldest first, each with its date
why it was called Called: comments after the last Answered: one those only; the issue is linked for the earlier ones
why it was called no Called: comment after the last Answered: that no reason was found, and a link to the issue
the comment box — empty
the note — "answer" starts an agent in the worktree; close a session left open there first
"back" — the board; nothing written
Issue N when the page is asked for The page
open, story, called as above
anything else, or not an issue of a level 3 repository of a forge of the user config says why there is nothing to answer, with a link back

The press

The issue is read again at the press. The forge is written in the order tp story answer writes: the comment, then the label. The agent is claude --remote-control in the worktree, its session named R #N, its first message: #N was called and is answered; read the answer on the issue, run tp story query, do what it says. The message is the same whether or not the story is defined.

The box Issue, read again The forge The agent The browser
text open, story, called Answered: TEXT commented; called off started; prints its session's address within a minute sent to the session
text open, story, called, not defined (a call -undefined) the same the same, the same first message the same
text open, story, called the same one started by an "answer" for this story from this tp overview is still running: no second a page saying the answer is recorded and that the running agent has not been told, with a link to its session
text open, story, called the same not started: the forge's dir not set a page: the answer is recorded; names the user config and the forge; a link back
text open, story, called the same not started: no branch on the forge, so no worktree known a page: the answer is recorded; says why; a link back
text open, story, called the same not started: the worktree absent, or not a directory a page: the answer is recorded; names the path; a link back
text open, story, called the same not started: claude not on the PATH a page: the answer is recorded; says so; a link back
text open, story, called the same ends, or prints no address within a minute and is stopped a page: the answer is recorded; the last line it printed; the worktree's path; a link back
empty, or blanks only any nothing written none the answer page again, saying an answer is needed
text open, story, not called nothing written none a page: it is answered already; a link back
text closed, or not story nothing written none a page saying why; a link back
text open, story, called, the forge refusing the comment nothing written none the answer page again, the forge's words above the box, the text still in it
text open, story, called, the comment written, the forge refusing the label the comment only none a page: the comment is on the issue and called still on, in the forge's words; names tp story answer with no text, in the worktree; a link back

After a press that takes called off, the card on the board is no longer blocked.

The guard

Request Outcome
the press without the secret tp overview made when it started refused; nothing written, no agent
the page or the press under a name other than this machine's own refused
the press for a repository below level 3, or of a forge not in the user config refused; nothing written, no agent

An agent started by "answer" lasts while tp overview runs and ends with it, as an interview does. Linux and macOS.

Out of scope

  • Detecting an agent in the worktree that this tp overview did not start: one left open in a terminal, or started by another tp overview. The agent that called has stopped by the flow's contract; the page's note asks the human to close a session left open. A second agent is started beside it.
  • Telling a running agent of the answer. tp overview cannot send a message into a session; the human tells it.
  • Answering with no text. tp story answer with no text, in the worktree, still takes called off without a comment.
  • Finishing a press the forge stopped between the comment and the label. tp story answer does it.
  • Accepting a story from the answer page. One called -undefined is rewritten by the agent, offered, and accepted from its card as any other.
  • Earlier calls and answers, review verdicts and the rest of the issue's thread on the page: the issue is linked.
  • Any change to tp story call or tp story answer, and the renaming of called to "blocked" (#281).

Decisions

None. The interview's choices are in the tables: the answer is recorded before the agent is started and stays recorded when the start fails; one first message serves a defined story and one not defined, because tp story query already gives the next step.

Done when

  • tests express the acceptance table and pass
  • spec updated
  • changelog entry
  • issue closed with a link to the release