Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(server): a session's queued follow-ups are capped at 16

lmlihengbdc1633d74b4
diff --git a/changelog/unreleased/2026-10-11-follow-up-queue-cap.md b/changelog/unreleased/2026-10-11-follow-up-queue-cap.md
new file mode 100644
index 00000000..f051ab90
--- /dev/null
+++ b/changelog/unreleased/2026-10-11-follow-up-queue-cap.md
@@ -0,0 +1,13 @@
+# A Session's follow-up queue holds at most 16 entries
+
+- **Date:** 2026-10-11
+- **Type:** fix
+- **Scope:** `server`
+
+[中文版](2026-10-11-follow-up-queue-cap.zh.md)
+
+Ported from upstream PenguinHarness (#853, commit `092a595c`).
+
+`POST /api/sessions/:sessionId/tasks` with `queueIfBusy` now refuses the seventeenth queued follow-up with `429 queue_full` instead of enqueuing without bound; the cap is `FOLLOW_UP_QUEUE_LIMIT` (16) per Session. The paths that always ask to queue — an organization's channel mention, or a calendar dispatch to a busy desk — record the refusal as `org_dispatch_failed` and move on (a periodic calendar event fires again at its next slot), so a mention storm or an @all fan-out no longer grows a desk's queue without limit and replays every entry as a model call. The `409 task_in_progress` answer without `queueIfBusy` is unchanged, and draining one entry frees one slot.
+
+One difference from upstream's entry: this fork has not ported #852 yet, so a **one-shot** calendar event whose dispatch is refused still consumes its slot rather than retrying — see `docs/FORK-PROGRESS.md`.
diff --git a/changelog/unreleased/2026-10-11-follow-up-queue-cap.zh.md b/changelog/unreleased/2026-10-11-follow-up-queue-cap.zh.md
new file mode 100644
index 00000000..7d3aecfa
--- /dev/null
+++ b/changelog/unreleased/2026-10-11-follow-up-queue-cap.zh.md
@@ -0,0 +1,13 @@
+# 一个 Session 的 follow-up 队列最多保留 16 条
+
+- **Date:** 2026-10-11
+- **Type:** fix
+- **Scope:** `server`
+
+[English](2026-10-11-follow-up-queue-cap.md)
+
+移植自上游 PenguinHarness(#853,提交 `092a595c`)。
+
+带 `queueIfBusy` 的 `POST /api/sessions/:sessionId/tasks` 现在对第 17 条排队的 follow-up 以 `429 queue_full` 拒绝,而不是无上限入队;上限为每个 Session 的 `FOLLOW_UP_QUEUE_LIMIT`(16)。总是要求排队的路径——组织频道的 @提及、日程向繁忙工位的派发——把拒绝记为 `org_dispatch_failed` 后继续(周期日程项在下一个槽位照常触发),因此一场提及风暴或一次 @all 扇出不再让工位队列无限增长、再把每一条都重放成一次模型调用。不带 `queueIfBusy` 时的 `409 task_in_progress` 不变;排出一条即空出一个位置。
+
+与上游那条的一处差别:本仓尚未移植 #852,因此派发被拒的**一次性**日程项仍会消耗它的时间槽、不会重试——见 `docs/FORK-PROGRESS.md`。
diff --git a/packages/server/src/runtime/session-manager.ts b/packages/server/src/runtime/session-manager.ts
index 0d5d4de8..cc0ae61a 100644
--- a/packages/server/src/runtime/session-manager.ts
+++ b/packages/server/src/runtime/session-manager.ts
@@ -582,6 +582,16 @@ interface RuntimeEntry {
const ENTRY_IDLE_MS = 30 * 60 * 1000;
const ENTRY_SWEEP_INTERVAL_MS = 60 * 1000;
+/**
+ * Queue depth cap per session. Every queued follow-up is a full model run waiting to
+ * happen, and the queue has no other brake: org triggers always ask to queue
+ * (queueIfBusy), so a mention storm or an @all fan-out against a busy desk would grow it
+ * without bound and then replay every entry as a model call. The cap refuses the overflow
+ * loudly instead (429 queue_full): the org trigger path records org_dispatch_failed, and
+ * the HTTP caller sees the refusal directly.
+ */
+export const FOLLOW_UP_QUEUE_LIMIT = 16;
+
/** Composite Agent key (used as a Set key, avoiding projectId/agentId concatenation ambiguity). */
function agentKey(projectId: string, agentId: string): string {
return `${projectId}\0${agentId}`;
@@ -1092,6 +1102,14 @@ export class SessionManager {
// Task starts now or waits in the queue (see SessionManagerDeps.onHumanInput).
if (isHumanInput(input)) this.deps.onHumanInput?.(sessionId);
if (entry.status !== "idle" && opts?.queueIfBusy) {
+ // The cap refuses the overflow rather than enqueuing it: see FOLLOW_UP_QUEUE_LIMIT.
+ if (entry.followUps.length >= FOLLOW_UP_QUEUE_LIMIT) {
+ throw new HttpError(
+ 429,
+ "queue_full",
+ `Session ${entry.sessionId} already has ${entry.followUps.length} queued follow-ups (cap ${FOLLOW_UP_QUEUE_LIMIT}); wait for the session to drain.`,
+ );
+ }
entry.followUps.push({
id: randomUUID(),
input,
diff --git a/packages/server/test/session-manager.test.ts b/packages/server/test/session-manager.test.ts
index d1200cfb..9808a9a3 100644
--- a/packages/server/test/session-manager.test.ts
+++ b/packages/server/test/session-manager.test.ts
@@ -80,7 +80,7 @@ import type { SessionRow } from "../src/db/repos/sessions.js";
import { ChannelHub } from "../src/runtime/channel.js";
import type { ChannelEvent } from "../src/runtime/channel.js";
import type { ErrorRecordArgs, ErrorSink } from "../src/runtime/error-recorder.js";
-import { SessionManager } from "../src/runtime/session-manager.js";
+import { SessionManager, FOLLOW_UP_QUEUE_LIMIT } from "../src/runtime/session-manager.js";
import type { RuntimeSession, SessionLoader } from "../src/runtime/session-manager.js";
import { SessionSources } from "../src/runtime/session-sources.js";
import type { TitleRequest } from "../src/runtime/title-generator.js";
@@ -811,6 +811,42 @@ describe("session-manager", () => {
expect(states[states.length - 1]).toMatchObject({ state: "idle", queued: 0 });
});
+ it("queueIfBusy: a full queue refuses with 429 instead of growing without bound", async () => {
+ const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
+ const first = await manager.startTask("session-1", [userText("task 1")]);
+ expect(first.queued).toBe(false);
+ await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
+
+ // Fill the queue to the cap; every entry still queues as before.
+ for (let i = 0; i < FOLLOW_UP_QUEUE_LIMIT; i++) {
+ const q = await manager.startTask("session-1", [userText(`follow-up ${i}`)], {
+ queueIfBusy: true,
+ });
+ expect(q.queued).toBe(true);
+ }
+ expect(manager.pendingFollowUpCount("session-1")).toBe(FOLLOW_UP_QUEUE_LIMIT);
+
+ // The next one is refused loudly — not queued, not started, nothing dropped silently.
+ const err = await manager
+ .startTask("session-1", [userText("overflow")], { queueIfBusy: true })
+ .catch((e: unknown) => e);
+ expect((err as HttpError).status).toBe(429);
+ expect((err as HttpError).code).toBe("queue_full");
+ expect(manager.pendingFollowUpCount("session-1")).toBe(FOLLOW_UP_QUEUE_LIMIT);
+ // Without queueIfBusy the 409 mutual exclusion is unchanged.
+ const conflict = await manager.startTask("session-1", [userText("x")]).catch((e: unknown) => e);
+ expect((conflict as HttpError).code).toBe("task_in_progress");
+
+ // Draining one frees a slot for exactly one more.
+ manager.abortTask("session-1");
+ await waitFor(() => manager.pendingFollowUpCount("session-1") === FOLLOW_UP_QUEUE_LIMIT - 1);
+ const refill = await manager.startTask("session-1", [userText("refill")], {
+ queueIfBusy: true,
+ });
+ expect(refill.queued).toBe(true);
+ expect(manager.pendingFollowUpCount("session-1")).toBe(FOLLOW_UP_QUEUE_LIMIT);
+ });
+
it("queueIfBusy during compaction: the queue drains once the compaction ends", async () => {
const runInputs: string[][] = [];
let releaseCompact: (() => void) | null = null;