charles/claude-hooks
1
0
Fork 0
Code Issues 10 Pull requests Projects Releases Packages 1 Wiki Activity Actions

B6 — Planner board: column header — queue depth + soft WIP limit #414

New issue
Closed
opened 2026-04-27 00:03:18 +00:00 by claude-desktop · 0 comments
claude-desktop commented 2026-04-27 00:03:18 +00:00
Collaborator
Copy link

As an operator,
I want each agent column to show queue depth and turn red when it exceeds a per-agent threshold,
so that I know when to spawn another instance instead of piling more on.

Each agent has a FIFO queue (docs/reviewer-instances.md); the operator finds out an agent is saturated by spawning extras in the agents tab. This story surfaces queue depth on the column header with a soft WIP threshold.

Acceptance criteria

Column header

  • Each agent column header shows running + queued / WIP (e.g. 3 / 4).
  • Header background turns bg-error/10 and the badge text turns text-error once running + queued > WIP.
  • Limit is soft — drops are not blocked, only the warning shows.
  • Tooltip on the badge lists the per-instance breakdown (reviewer-1: 2 in flight, reviewer-2: 1 queued). Use Tooltip from the existing component library.

Config

  • WIP limit configured per agent type in config/agents.json under a new optional wip_soft_limit?: number field.
  • Default 4 if absent.
  • No migration needed — schema is additive.

Backend — extend GET /board response per column

  • Each column gains wip_soft_limit: number (resolved from agents.json, default 4).
  • Each column gains in_flight: number and queued: number aggregates (sum across instances of that type).

Backend — new endpoint GET /board/agent-instances

  • Returns { <agent_type>: [{ login: string, in_flight: number, queued: number }] } for the WIP tooltip.
  • Reads from the existing per-instance task-history / queue state.
  • Cached for 5 s (matches /board cadence) so the tooltip is cheap to render.

Tests

  • board-column.test.tsx: header shows 2 / 4 given response with in_flight: 1, queued: 1, wip_soft_limit: 4.
  • board-column.test.tsx: header turns red once in_flight + queued > wip_soft_limit.
  • board-column.test.tsx: tooltip lists per-instance counts from /board/agent-instances.
  • Server test: /board response includes wip_soft_limit, in_flight, queued per column.
  • Server test: /board/agent-instances returns expected shape.

Out of scope

  • Per-instance columns (M18-7 deferral stands).
  • Hard WIP limits — soft only, drops always succeed.
  • Auto-spawning a new agent instance when over WIP (separate spec, may not be wanted).

References

  • Spec: docs/specs/board-rework.md §5 B6 + §6.
  • Reviewer pool: docs/reviewer-instances.md.
  • config/agents.json schema: apps/server/src/domain/agents/config.ts (or wherever the loader lives).

Dependencies

  • Lands after B5 — server response extension overlaps; do them in order to avoid two migrations of /board.

Suggested first commit

feat(board): WIP soft limit badge on agent columns + per-instance tooltip

**As an** operator, **I want** each agent column to show queue depth and turn red when it exceeds a per-agent threshold, **so that** I know when to spawn another instance instead of piling more on. Each agent has a FIFO queue (`docs/reviewer-instances.md`); the operator finds out an agent is saturated by spawning extras in the agents tab. This story surfaces queue depth on the column header with a soft WIP threshold. ## Acceptance criteria ### Column header - [ ] Each agent column header shows `running + queued / WIP` (e.g. `3 / 4`). - [ ] Header background turns `bg-error/10` and the badge text turns `text-error` once `running + queued > WIP`. - [ ] Limit is **soft** — drops are not blocked, only the warning shows. - [ ] Tooltip on the badge lists the per-instance breakdown (`reviewer-1: 2 in flight, reviewer-2: 1 queued`). Use `Tooltip` from the existing component library. ### Config - [ ] WIP limit configured per agent type in `config/agents.json` under a new optional `wip_soft_limit?: number` field. - [ ] Default 4 if absent. - [ ] No migration needed — schema is additive. ### Backend — extend `GET /board` response per column - [ ] Each column gains `wip_soft_limit: number` (resolved from `agents.json`, default 4). - [ ] Each column gains `in_flight: number` and `queued: number` aggregates (sum across instances of that type). ### Backend — new endpoint `GET /board/agent-instances` - [ ] Returns `{ <agent_type>: [{ login: string, in_flight: number, queued: number }] }` for the WIP tooltip. - [ ] Reads from the existing per-instance task-history / queue state. - [ ] Cached for 5 s (matches `/board` cadence) so the tooltip is cheap to render. ### Tests - [ ] `board-column.test.tsx`: header shows `2 / 4` given response with `in_flight: 1, queued: 1, wip_soft_limit: 4`. - [ ] `board-column.test.tsx`: header turns red once `in_flight + queued > wip_soft_limit`. - [ ] `board-column.test.tsx`: tooltip lists per-instance counts from `/board/agent-instances`. - [ ] Server test: `/board` response includes `wip_soft_limit`, `in_flight`, `queued` per column. - [ ] Server test: `/board/agent-instances` returns expected shape. ## Out of scope - **Per-instance columns** (M18-7 deferral stands). - **Hard WIP limits** — soft only, drops always succeed. - Auto-spawning a new agent instance when over WIP (separate spec, may not be wanted). ## References - Spec: `docs/specs/board-rework.md` §5 B6 + §6. - Reviewer pool: `docs/reviewer-instances.md`. - `config/agents.json` schema: `apps/server/src/domain/agents/config.ts` (or wherever the loader lives). ## Dependencies - Lands after **B5** — server response extension overlaps; do them in order to avoid two migrations of `/board`. ## Suggested first commit `feat(board): WIP soft limit badge on agent columns + per-instance tooltip`
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
chore/sync-pre-push-from-forge-base
fix/flows-yaml-dispatch-identity
feat/board-tap-to-assign
dev/1107
code-lead/1106
code-lead/1108
dev/1104
code-lead/1103
code-lead/1080
dev/1087
feat/flows-yaml-ci-events
chore/board-drop-stalled-and-density-controls
fix/flows-yaml-routes-always-register
flows-yaml/api-defaults
dev/1023
fix/event-log-history-bleed
fix/janitor-fix-ci-logs-and-cap
dev/1022
fix/board-card-provider
code-lead/1036
dev/1025
code-lead/1020
dev/1017
code-lead/1026
feat/web-shortcut-registry-1018
dev/1015
code-lead/1009
code-lead/1008
dev/975
dev/969
dev/973
dev/967
code-lead/968
code-lead/953
dev/970
dev/976
code-lead/966
code-lead/956
code-lead/951
dev/962
dev/963
dev/977
dev/955
dev/983
dev/961
dev/974
code-lead/950
code-lead/939
dev/941
dev/940
dev/937
dev/938
dev/936
dev/935
feat/web-i18n-fr-locale
feat/spec-editor-ui-polish
chore/drop-legacy-compat
fix/skills-drop-preview-pane
fix/882-skills-safety-rail
dev/911
dev/909
dev/923
dev/917
dev/915
feat/879-sr11-m2-drop-legacy-skill
code-lead/873
dev/881
code-lead/869
dev/867
code-lead/845
code-lead/843
code-lead/844
dev/837
dev/861
dev/849
code-lead/837
code-lead/842
fix/dedup-rebase-inflight
dev/838
code-lead/847
dev/833
code-lead/848
pr/838
code-lead/841
feat/settings-save-bar/836
code-lead/840
dev/846
code-lead/839
dev/832
fix/board-sse-stale-cache
dev/834
dev/835
feat/settings-breadcrumbs
feat/forge-oauth-credentials
refactor/service-config-consolidation
feat/agent-tokens-to-secrets
feat/gitlab-oauth-to-db
feat/authelia-rip-and-voice-fixes
fix/rebase-storm-and-dead-letter
code-lead/797
code-lead/796
dev/811
code-lead/798
dev/810
code-lead/795
dev/808
code-lead/794
dev/805
dev/802
dev/803
feat/avatar-menu-settings-entry
feat/per-agent-token-tracking
dev/793
dev/747
dev/752
code-lead/790
code-lead/759
dev/756
dev/760
dev/741
dev/767
dev/740
dev/709
dev/644
dev/637
boss/614
dev/600
dev/611
dev/585
fix/login-bonus-fixes
boss/544
dev/542
refactor/api-prefix-and-session-gate
dev/489
boss/531
boss/518
dev/499
boss/516
dev/530
dev/517
dev/519
dev/515
dev/522
dev/503
dev/471
boss/329
dev/417
dev/418
dev/402
boss/327
dev/334
dev/332
boss/326
boss/325
dev/331
boss/324
boss/323
boss/322
dev/294
test/s11-task-analytics
dev/262
boss/270
dev/268
foreman/ui-consolidation-spec
dev/234
boss/196
boss/176
boss/164
fix/124-session-persist-bind
boss/52
dev/87
boss/73
dev/77
dev/81
dev/82
boss/79
dev/42
dev/35
boss/7
No results found.
Labels
Clear labels   
area:agents
Agent types, pool scheduling, per-instance config

  
area:dashboard
Dashboard UI and observability surfaces

  
area:database
DB layer — schema, migrations, ORM, raw SQL

  
area:design
UI/UX mockup work — routes to designer agent

  
area:design-review
Design review dispatch — routes to design-reviewer agent

  
area:flows
Flow runner — YAML loader, executor, op registry, expression eval

  
area:infra
Deployment, isolation, containers, systemd units

  
area:meta
Tracking, scaffolding, project setup

  
area:security
Security — routes to reviewer-security (opus)

  
area:sessions
Session-id store, Claude SDK resume logic

  
area:webhook
Forgejo webhook routing and handlers

  
area:workdir
Clone cache, worktrees, git identity

  
security
Security-sensitive issue

  
type:bug
Bug

  
type:chore
Chore

  
type:meta
Tracking or decisions, not implementation work

  
type:user-story
User story

No labels
area:agents
area:dashboard
area:database
area:design
area:design-review
area:flows
area:infra
area:meta
area:security
area:sessions
area:webhook
area:workdir
security
type:bug
type:chore
type:meta
type:user-story
Milestone
Clear milestone
No items
No milestone
v1-board-rework
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
dev
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
charles/claude-hooks#414
No description provided.