Commit Graph
3 Commits
Author SHA1 Message Date
DottaandClaude Opus 5.5 4da6902cb3 fix(dispatch): start work on a task tree a person created in the person tier (#21916)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The heartbeat queue chooses which queued run starts when an agent at
its concurrency limit frees a slot
> - The queue puts runs a person asked for in a "person" tier ahead of
agent "work"
> - Subtasks of a person's task, and the parent's resume after its
children complete, ranked as agent work
> - Under load these runs started only through the 60-minute oldest-run
share, so a half-finished task waited about 55 minutes per step behind
newer tasks
> - This pull request puts every non-recovery run on a task tree a
person created in the person tier
> - The benefit is that a person's started work finishes before newer
work starts, and the fairness bounds stay in place

## Linked Issues or Issue Description

**What existing behavior does this improve?**
The order in which an agent at its concurrency limit starts queued runs.

**Subsystem affected**
Server heartbeat queue:
`server/src/services/heartbeat/queued-run-dispatch-order.ts` and
`queued-run-line.ts`.

**Current behavior**
A board user's new assignment ranks as person work. An agent's subtask
of that person's task, and the parent's `issue_children_completed`
resume, rank as agent work. In a restart chaos run with agents at
capacity, the median queue wait of a parent resume was about 1,640 s.
The median wait of a new assignment was about 190 to 290 s. One parent
waited while 14 newer tasks started first. Subtasks and parent resumes
started only near the 60-minute aging bound.

**Proposed behavior**
A non-recovery run on a task tree that a person created goes in the
person tier. A task is in such a tree when the task, or any task above
it, has `createdByUserId`. In the tier, runs keep the existing order:
readiness, then priority, then age (oldest first).

**Reason and benefit**
A person waits on the whole tree, not only on the top task. Work that a
person started now finishes before newer tasks take its slots.

**Breaking changes**
None. There is no schema or API change.

## What Changed

- `queuedRunDispatchClass` puts a run with `personTask` in the person
tier. System recovery stays in the recovery tiers, also on a person's
tree.
- `personTask` now means "the task, or a task above it, was created by a
person". The existing `createdByUserId` marker is the source.
- New `listPersonTreeIssueIds`: one recursive query per dispatch pass.
It walks each queued task's parent chain through the `(company_id, id)`
unique index. It stops at the first person-created task, at most 32
levels. It runs only when the agent has more than one queued run. The
start-history read uses the same query in place of its old direct
`createdByUserId` read, so the query count does not change there.
- Recovery's 1-in-4 share is held only while a run a person asked for
(`isPersonRequestedRun`) is ready, not for the rest of a person's tree.
So a deep tree cannot hold recovery indefinitely. The dispatcher and the
place-in-line replay use the same rule.
- The claim backoff for a declined claim keeps the short person backoff
only for runs a person asked for (unchanged behavior for tree runs).
- `doc/heartbeat-internals.md`: new "Queued run dispatch order" section
with the tiers, the order and the fairness bounds.

Fairness bound: the oldest-run share is unchanged. Every 4th start goes
to the longest-waiting ready run past 60 minutes, preferring runs people
wait on. So another person's new task starts within 60 minutes plus 4 x
(aged person-tier runs queued before it + 1) starts, even while a deep
tree keeps adding in-progress or higher-priority work. A newer tree run
never passes an older, equally ranked person task. Queues are per agent,
and an agent belongs to one company, so no agent or company gets ahead
of another.

## Verification

- Red on master, green with this change:
- `queued-run-dispatch-order.test.ts`: an older parent resume
(`issue_children_completed`, person tree) starts before a newer person
assignment. The place-in-line replay agrees.
- `queued-run-dispatch-order.test.ts`: an older subtask of a person's
task starts before a newer person assignment.
- `queued-run-dispatch-order.test.ts`: fairness simulation. A deep tree
adds two in-progress, higher-priority runs per start. Another person's
new task starts within `QUEUED_RUN_AGING_MS` + `OLDEST_DISPATCH_SHARE`
starts.
- `execution-projection-agent-queue.test.ts` (embedded Postgres, real
SQL): line is subtask (grandchild of a person's task), parent resume,
newer person assignment, then work on an agent-created tree. Master
gives the person assignment first and the tree runs last.
- Negative and guard tests (green on both): work on an agent-created
tree stays in the work tier behind a newer person assignment; system
recovery on a person's tree stays in the recovery tier; newer tree work
does not pass an older equally ranked person task; recovery still gets
its share while only tree work waits.
- Query plan on embedded Postgres with 300,000 issues and 200 queued
tasks six levels deep: every step is an index scan on
`issues_company_id_uq`, 1.5 ms execution.
- `pnpm verify` exited 2 (a doc is a global CI input). Focused run:
`queued-run-dispatch-order`, `queued-run-line`,
`execution-projection-agent-queue`, `fresh-continuation-retry-delivery`,
`assigned-work-stalled-queued-run`, `automatic-run-start-gate`,
`automatic-run-brake-recovery-passes`,
`heartbeat-stale-queue-invalidation`: 8 files, 173 tests passed. `tsc
--noEmit` for the server passed.

## Risks

- Behavior shift: in a company where people create most top-level tasks,
most issue runs are now person tier. The "work" tier then holds
agent-started trees, routines and runs without a task. Recovery keeps
its share because only runs a person asked for hold it.
- An in-progress run on a person's tree now ranks ahead of a new person
task that is not in progress (readiness rank). The oldest-run share
bounds that wait at about 60 minutes plus a few starts, the same bound
agent work had before.
- A tree deeper than 32 levels above a queued task is treated as not a
person tree. It falls back to the work tier and the aging share.
- The extra query runs only when an agent has more than one queued run,
and only for queued tasks without `createdByUserId`.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through Claude
Code with tool use and code execution.

## 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
- [x] 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>
2026-11-16 10:35:42 -06:00
DottaandClaude Opus 5.5 833689a3fc fix(queue): say a long-queued turn is waiting to start, and name the routine execution that holds it (#21447)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - #21405 made a task that waits for its agent's concurrency limit show
"Waiting for <agent> · N slots max · P of Q in line · Configure"
> - On hosted staging, after that deploy, a routine task stayed queued
for 8 minutes while its agent had 19 free slots. Its chat said "Working
for 7m · Thinking", and the server label was a plain "Queued"
> - The real cause was the routine's one-execution-at-a-time rule: the
previous execution of the same routine was still open with its run. That
is correct scheduling, but the UI did not say it
> - A queued turn also kept the startup feedback ("Working") for as long
as it stayed queued, with no limit
> - This pull request names the routine hold and limits the startup
feedback to 30 seconds
> - The benefit is that a queued task always says that it waits, and why
when the server knows

## Linked Issues or Issue Description

Refs #21405

**What happened?**

On staging, one routine task's continuation run was queued at 17:39:03Z
and claimed at 17:47:10Z. The agent ran 1 of 20 runs. The chat showed
"Working for 7m · Thinking". The run's projection label was "Queued"
with no cause.

**Why did it happen?**

1. The routine allows one open execution with a run at a time (unique
index `issues_open_routine_execution_uq`). The previous execution of the
same routine was still open and held its run until 17:47:10.172Z. The
waiting run was claimed 345 ms after that task closed. The claim was
refused with "Another execution for this routine is already in progress"
until then. This is the routine's intended policy, not a scheduling bug.
2. The execution projection did not name that hold, so the server label
was "Queued".
3. The task chat keeps the startup feedback ("Working" and "Thinking")
for a queued turn with no named hold (a DESIGN.md rule). That rule had
no time limit.

**Expected behavior**

A routine task that waits for the routine's open execution says "Waiting
for <task> to finish". A queued turn that has no named hold says
"Waiting to start" after a short grace period.

## What Changed

- Server: `executionProjectionsForRuns` reads, in one query per batch,
whether another open task of the same routine holds the routine's
execution. For a never-started queued run that waits on it, the
projection sets the cause `routine_execution_in_progress`, the label
"Waiting for <task identifier> to finish", and a next action. This check
comes before the agent-limit check, because a free slot would not start
the run.
- UI: a new hook, `useWaitingToStart`, keeps the startup feedback for 30
seconds. After that, a queued turn with no named hold shows "Waiting to
start": an hourglass, no spinner, no shimmer. The task chat's runner
header, its current-activity tail and the live run pill use it. The hook
uses one timer at the threshold and no per-second ticks.
- DESIGN.md: the startup-feedback rule now has the 30-second limit and
the routine hold.
- Storybook: `WaitingToStart` and `WaitingForRoutine` stories, with play
checks.

**Why 30 seconds:** DESIGN.md keeps "Working" from message submission
through admission, so that a normal start does not flicker. On staging,
runs that were not held started 3 to 8 seconds after they were queued
(from the company's run list between 17:30 and 17:48Z). 30 seconds is
several times that, and shorter than any real wait the user should be
told about.

## Verification

- Red/green server test (embedded Postgres),
`execution-projection-agent-queue.test.ts`: a routine task waits while
another open task of the same routine holds a run. The test checks the
label "Waiting for Q-3093 to finish" and the cause. It checks that the
holder is not marked as waiting on itself, and that the label returns to
plain "Queued" when the holder closes. It fails without the server
change.
- Red/green UI tests: `TaskChatRunnerTurn.test.tsx` (startup feedback
until the threshold, then "Waiting to start" in the header and the tail;
a running turn is never called waiting) and
`TaskChatLiveRunPill.test.tsx` (the label changes, with no spinner or
shimmer). Both fail without the UI change.
- `vitest run` on the four `execution-projection-*` server suites (36
tests) and all `task-chat` and `TaskChatThread` UI suites (1,414 tests).
UI and server typecheck.
- The new stories render in headless Chromium.
- On staging, before this change, the #21405 waiting line was confirmed
with a temporary 1-slot agent: "Waiting for Queue Check (temp) · 1 slot
max · 2 of 2 in line · Configure". The temporary tasks and agent were
cancelled and terminated.
- After deploy: confirm the new labels on staging.

## Risks

- Low risk. There is no schema change.
- One extra query per projection batch that includes a never-started
queued run on a routine task. It is a join on the company's
routine-execution tasks through the existing `issues_company_origin_idx`
index.
- A queued turn that is admitted after 30 seconds, for a reason the
server does not name, now says "Waiting to start" instead of "Working".
This is the intended change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, Chrome for staging checks).

## 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>
2026-11-13 20:22:07 -06:00
DottaandClaude Opus 5.5 e7e28ba241 feat(queue): show tasks waiting for an agent's slot as waiting, with their place in line (#21405)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Each agent runs at most `runtimeConfig.heartbeat.maxConcurrentRuns`
tasks at once. Other runs wait in the agent's queue with status `queued`
> - On hosted staging, one agent had all 20 slots full and 295 queued
runs. Some tasks waited 3 to 7 hours and never started
> - The UI showed these tasks as live or working: a pulsing "Live" badge
in the task header and in task rows, a spinning "Working … for 4 hours"
in the task chat, and "N live" counts that included every queued run
> - People could not tell that work was waiting, why it waited, or what
to change
> - This pull request makes a deep queue an honest, visible state:
"Waiting for Codie · 20 slots max · 41 of 295 in line · Configure"
> - The benefit is that operators see the real state and the one setting
that changes it

## Linked Issues or Issue Description

Refs #21391, #21349, #21242

**What happened?**

A queued run that never started looked the same as a running run. The
task header, the task rows in lists and the inbox, the task chat and the
sidebar counts all showed queued runs as live or working.

**Expected behavior**

A run that waits for one of its agent's concurrency slots shows that it
waits. It names the agent, the agent's limit and the run's place in
line, and it links to where the limit is set. The place in line is the
order in which the server starts the agent's queued runs.

**Why does it matter?**

With a deep queue, the UI said "working" for hours while nothing ran.
Operators could not see the cause or the fix.

## What Changed

- Server: a new module
`server/src/services/heartbeat/queued-run-line.ts` now holds the facts
that the queued-run dispatcher orders by (`queuedRunDispatchFacts`). The
dispatch path in `queue.ts` and the new "place in line" read use this
one builder, so the line the UI shows is the dispatch order. The logic
moved without change, including the recovery-share fix from #21391.
- Server: `executionProjectionsForRuns` adds `agentQueue` (agent, limit,
running count, position, queued count) and the label "Waiting for
<agent>" with cause `agent_at_capacity` to a queued, never-started run
when its agent has no free slot. It reads one batch of agents and
running counts. Then it builds one line per full agent (at most 8 agents
per read), using only the three context keys that ordering needs. No new
polling.
- Server: the place in line uses `queuedRunDispatchLine`, an O(n log n)
replay of the dispatcher. The plain replay rescans the queue after each
step, which is quadratic (measured: 3.6 ms at 300 runs, 76 ms at 3,000,
600 ms at 10,000, all on the event loop). Dispatch itself is unchanged:
it stops after the free slots. Each agent's line is memoized for 5 s and
shared by concurrent reads. In a preview worktree, the line applies the
same creation-time cutoff as dispatch.
- Server: the task list summary adds `runningDescendantCount`
(descendants whose run started) next to `liveDescendantCount`.
`liveDescendantCount` still decides whether a blocked parent is covered.
The "n live below" chip uses the new count.
- Shared: the new `ExecutionAgentQueue` type and the optional field
`ExecutionProjection.agentQueue`.
- Server: `/companies/:companyId/live-runs` lists running runs before
queued runs, so a deep queue cannot push running work out of the 50-row
limit.
- UI: a new `AgentQueueWait` component shows "Waiting for Codie · 20
slots max · 41 of 295 in line · Configure", with no spinner and no
elapsed timer. Configure opens the agent's Advanced view, where the run
policy (`maxConcurrentRuns`) is edited. The task chat (both renderers),
the run ledger and the Storybook story use it.
- UI: the task header and the task rows (task list, inbox, legacy views)
show a quiet "Waiting" instead of the pulsing "Live" when every live run
of the task has not started. The full sentence shows on hover. "n live
below" counts only started sub-tasks. A waiting sub-task still covers
its blocked parent.
- UI: the sidebar "N live" counts (Dashboard, agents) count only started
runs.
- UI: the task chat pill now names other server holds on a queued run
(for example "Waiting for maintenance") instead of "Working".
- Docs: DESIGN.md records the waiting-for-slot hold.
- Storybook: `runs-agent-queue-wait` stories (full line, task chat, task
row, one slot, mobile), with play checks.

## Verification

- Red/green server test:
`server/src/services/execution-projection-agent-queue.test.ts` (embedded
Postgres). Before this change, the projection has no `agentQueue`. Now
it checks the agent name, limit, running count, positions 1 to 4 in
dispatch order (a person's retry first, then priority, not creation
order), no wait while a slot is free, and isolation from other
companies' runs. It also checks that the positions equal the line that
the dispatch builder produces.
- `pnpm exec vitest run` on the new test, `queued-run-dispatch-order`,
`recovery-wake-herd`, `heartbeat-queued-run-claim-isolation` and
`agent-live-run-routes` in `server/`.
- Runtime cost (rule `runtime-dependency-boundaries`): the assumption is
that the line stays cheap for a deep queue. `queued-run-line.test.ts`
checks that `queuedRunDispatchLine` equals the dispatcher's
claim-every-run order over 400 random queues (ages around the aging
boundary, recovery and person runs, blocked runs, deferred share runs,
all share counters). It also orders 10,000 runs in under 250 ms (the
quadratic replay takes about 600 ms). The DB test projects a 300-run
queue end to end with correct positions 1 to 300. Remaining limit: the
line is up to 5 s stale.
- Red/green: `issue-list-assignee-filter-routes.test.ts` now asserts
`runningDescendantCount: 0` for a parent whose only live descendant is
queued and never started.
- UI tests: `liveIssueIds.test.ts` (waiting tasks, started runs keep
"Live", no "running below" count for waiting sub-tasks) and
`TaskChatLiveRunPill.test.tsx` (waiting line with no spinner and the
Configure link, other holds named). The suites for the run ledger,
sidebar, sidebar agents, task detail, task columns and task chat also
pass.
- The Storybook stories render in headless Chromium and their play
checks pass.
- After deploy: open a queued task on staging and confirm the waiting
state.

## Risks

- Cost on read: a projection read that includes a queued run of a full
agent now reads that agent's queued runs (only small columns) and the
dispatch facts. This is at most one line per full agent every 5 s, for
at most 8 agents per read. Reads with no queued, never-started runs do
no more work.
- The place in line is the server's prediction of dispatch order. A
claim that is refused at start time (a gate, a blocker) can let the next
run start first. The position updates on the next refresh.
- The process-local "declined aged claim" hint that the dispatcher uses
is not visible to other servers, so the projection does not use it. This
can change only the aged-oldest share step.
- Configure opens the agent's Advanced view (the YAML run policy). The
agent's Runtime tab hides the run-policy fields today.
- Low risk otherwise: no schema change and no migration.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, headless browser) and subagents for the UI survey.

## 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>
2026-11-13 10:24:20 -06:00