fix(ui): name a queued turn's hold once, in the turn header (#21564)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A task's chat shows its run as a turn: a header line with the run's
state, then the turn body
> - #21405 and #21447 made a queued turn name why it waits: "Waiting for
Codie · …", "Waiting for PAP-5656 to finish", "Waiting to start"
> - On staging, the turn body repeated that label under the header
("Waiting for PAP-5656 to finish" twice). The tail used by other
adapters showed a fixed "Waiting to start..." even while the pill above
said "Working" or named a hold
> - #21447 removed the repeat only for the agent's waiting line
> - This pull request names every queued hold once, in the turn header
> - The benefit is one clear statement of why a task waits, with no
repeat and no contradicting line

## Linked Issues or Issue Description

Refs #21405, #21447

**What happened?**

On staging (revision 6b631dd47), a routine task waiting on the routine's
open execution showed "Waiting for PAP-5656 to finish · 31s" in the turn
header and "Waiting for PAP-5656 to finish" again in the turn body.
Other server holds (maintenance, agent setup, server restart, previous
run) and "Waiting to start" had the same repeat. For adapters other than
the Paperclip runner, the tail under the live run pill always said
"Waiting to start..." for a queued run, even while the pill said
"Working" (the 30-second startup feedback) or named a hold.

**Expected behavior**

A queued turn names its hold once, in the header. The turn body adds no
second line for it.

**Why does it matter?**

A repeated or contradicting line makes the waiting state harder to read.
DESIGN.md asks for one name per state.

## What Changed

- `TaskChatRunnerTurn`: a queued turn that has a run and a hold label
(agent queue, server hold, or "Waiting to start") no longer renders the
current-activity line under the header. Startup preparation before a run
exists ("Taking longer than usual…") keeps its slot, as DESIGN.md
requires.
- `TaskChatThread`: the live tail for other adapters no longer shows the
fixed "Waiting to start..." for a queued run. The live run pill above
names the wait.
- DESIGN.md: a queued turn's hold is named once, in the turn header.
- Storybook: the `WaitingForRoutine` story renders the full turn and
checks that the hold appears once.

## Verification

- Red/green: `TaskChatRunnerTurn.test.tsx`. The server-hold cases
(maintenance, agent setup, setup failed, server restart, previous run,
and the new routine hold) and the "Waiting to start" case now assert
that the label appears exactly once and that the turn body has no
current-activity line. Without the change, the 6 existing cases fail.
With it, all 52 pass. The preparation-label case still passes (its slot
stays).
- `vitest run` on `src/components/task-chat` and
`TaskChatThread.test.tsx`: 1,436 passed. The UI typechecks.
- The updated stories render in headless Chromium; the routine story
shows the hold once.
- After deploy: check on staging.

## Risks

- Low risk. This is a UI-only change. A queued turn with a hold shows
one line fewer. Running turns, terminal turns and pre-run preparation
are unchanged.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, headless browser).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-13 23:07:08 -06:00
1 parent 351b69941c
commit 6dd0349d52
5 files changed
+14 -8

No files matched your search

+2
View File
@@ -153,6 +153,8 @@ such as `Waiting for maintenance`, agent setup, or another open task of the same
routine, visible during admission. Admission normally starts a run within seconds,
so this startup feedback lasts at most 30 seconds: a turn still queued after that
with no named hold says `Waiting to start`, without spinner or shimmer.
A queued turn's hold is named once, in the turn header; the turn body adds no
second line for it.
A run that waits for one of its agent's concurrency slots is a hold too: show
`Waiting for <agent> · N slots max · P of Q in line · Configure` (the shared
`AgentQueueWait` component) with no spinner or elapsed timer, link Configure to the
+1 -1
View File
@@ -3552,7 +3552,7 @@ export function TaskChatThread(props: TaskChatThreadProps) {
items={tailItems}
emptyMessage={
tailStatus === "queued"
? "Waiting to start..."
? undefined
: (liveRun && liveRun.id === tailRunId
? liveRun.currentStatusMessage
: null) ||
@@ -99,6 +99,7 @@ describe("TaskChatRunnerTurn", () => {
["agent_setup_failed", "Agent setup needs attention"],
["server_restarting", "Waiting for server restart"],
["previous_run_settling", "Waiting for previous run to stop"],
["routine_execution_in_progress", "Waiting for PAP-5656 to finish"],
])("shows the server's %s wait while admission is held", (cause, label) => {
render([], "queued", "run-1", undefined, false, false, {
phase: "queued", label, cause,
@@ -107,7 +108,8 @@ describe("TaskChatRunnerTurn", () => {
permittedActions: ["inspect_run"], predecessorRunId: null, successorRunId: null,
});
expect(container.querySelector('[data-testid="task-chat-turn-status-header"]')?.textContent).toContain(label);
expect(container.querySelector('[data-testid="task-chat-current-activity-label"]')?.textContent).toBe(label);
expect(container.textContent?.split(label)).toHaveLength(2);
expect(container.querySelector('[data-testid="task-chat-current-activity"]')).toBeNull();
expect(container.textContent).not.toContain("Thinking");
});
@@ -123,7 +125,8 @@ describe("TaskChatRunnerTurn", () => {
expect(container.textContent).not.toContain("Waiting to start");
act(() => { vi.advanceTimersByTime(2_000); });
expect(container.querySelector('[data-testid="task-chat-turn-status-header"]')?.textContent).toContain("Waiting to start");
expect(container.querySelector('[data-testid="task-chat-current-activity-label"]')?.textContent).toBe("Waiting to start");
expect(container.textContent?.split("Waiting to start")).toHaveLength(2);
expect(container.querySelector('[data-testid="task-chat-current-activity"]')).toBeNull();
expect(container.textContent).not.toContain("Working");
} finally {
vi.useRealTimers();
@@ -338,8 +338,7 @@ export function TaskChatRunnerTurn({
/>
</div>
) : null}
{/* The header's waiting line already names the agent's queue; no second line. */}
{!final && currentActivityItems.length === 0 && !agentQueueWaitFor({ status, execution })
{!final && currentActivityItems.length === 0 && !(status === "queued" && runId && (waitingLabel || agentQueueWaitFor({ status, execution })))
? <RunnerCurrentActivityTail status={status} waitingLabel={waitingLabel} /> : null}
</div></ToolCallProgressRunProvider></TaskChatShimmerScope>
);
@@ -4,7 +4,7 @@ import { expect, within } from "storybook/test";
import { AgentQueueWait } from "@/components/AgentQueueWait";
import { InboxIssueMetaLeading } from "@/components/IssueColumns";
import { TaskChatLiveRunPill } from "@/components/task-chat/TaskChatLiveRunPill";
import { TaskChatRunnerHeader } from "@/components/task-chat/TaskChatRunnerTurn";
import { TaskChatRunnerHeader, TaskChatRunnerTurn } from "@/components/task-chat/TaskChatRunnerTurn";
const codieQueue: ExecutionAgentQueue = {
agentId: "8f14e45f-ceea-467a-9575-6f1d0b2c9a01",
@@ -117,9 +117,11 @@ export const WaitingToStart: Story = {
/** A routine task that waits for the routine's open execution. */
export const WaitingForRoutine: Story = {
render: () => <TaskChatRunnerHeader agentName="Test Gardener" status="queued" startedAtMs={Date.now() - 8 * 60_000} runId="run-1"
render: () => <TaskChatRunnerTurn agentName="Test Gardener" status="queued" startedAtMs={Date.now() - 8 * 60_000} runId="run-1" items={[]}
execution={{ ...waitingExecution, cause: "routine_execution_in_progress", label: "Waiting for PAP-3093 to finish", agentQueue: null }} />,
play: async ({ canvasElement }) => {
await expect(within(canvasElement).getByText(/Waiting for PAP-3093 to finish/)).toBeVisible();
const holds = within(canvasElement).getAllByText(/Waiting for PAP-3093 to finish/);
await expect(holds).toHaveLength(1);
await expect(holds[0]).toBeVisible();
},
};