@ferris1225/pi-subagents 4.2.8 → 4.2.12

package/LICENSE

@@ -1,23 +1,23 @@
-MIT License
-
-Copyright (c) 2025 ferris1225
-Portions of agents/cleaner.md adapted from reclaim-code-entropy:
-Copyright (c) 2026 Yevanchen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 ferris1225
+Portions of agents/cleaner.md adapted from reclaim-code-entropy:
+Copyright (c) 2026 Yevanchen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -62,6 +62,8 @@ Every child is an isolated leaf pi process with its own context window and no
 memory of your conversation, so the brief is its only input. A good brief carries
 the goal, exact paths, constraints, and expected output — which is what the
 injected delegation guidance produces when the main agent dispatches for you.
+A named defect is not yet a change: confirm it on current code before fixing
+or briefing a fix. The executor re-reads before it edits.
 
 ```text
 You
@@ -207,13 +209,16 @@ still working?" without opening the widget or asking:
 subagents 2 running · 1 repo lane · 3 done
 ```
 
-It is count-only, keeps the same wait vocabulary as the widget, disappears when
-nothing is active, and works in RPC hosts as well as the TUI.
+It is count-only, keeps the same wait vocabulary as the widget, and works in
+RPC hosts as well as the TUI. Settled counts stay on the line only while a
+sibling is still live (`2 running · 3 done`); the line disappears once nothing
+is active.
 
 Completions resume the main agent on their own, with a compact block of at most 40
 lines by default; longer output lands unchanged in a Markdown artifact whose path
 comes with the message, stated as how much was actually cut (`40 of 137 lines
-shown`) and conditioned on the shown lines being insufficient, so the same
+shown`, or a 200-character clip when a short result has a long line) and
+conditioned on the shown lines being insufficient, so the same
 content does not enter the main context twice. Roles write result-only handoffs — outcome, paths,
 verification, unresolved blockers — and the main agent is told to add its
 conclusion rather than restate what you already read. A failed run adds its
@@ -363,13 +368,30 @@ beats an age rule.
 ```bash
 npm install
 npm run check
-npm test
 ```
 
 There are no bundled runtime dependencies; pi and TypeBox are peers. The source is
 split by responsibility: dispatch policy, thread lifecycle, RPC
 transport, worktree integration, completion delivery, tools, and TUI status.
 
+## Release
+
+Merging to `main` publishes `@ferris1225/pi-subagents` when `package.json`
+carries a version npm does not have yet, then opens a matching GitHub Release.
+Do not `npm publish` from a laptop.
+
+One-time setup — pick one:
+
+1. **Trusted publisher (preferred):** on the
+   [npm package page](https://www.npmjs.com/package/@ferris1225/pi-subagents)
+   add a GitHub Actions trusted publisher for `MCapricorns/pi-subagents` with
+   workflow filename `publish.yml` (no path, environment left blank).
+2. **Token:** create an npm automation token and store it as the repository
+   Actions secret `NPM_TOKEN`.
+
+If the first run fails because neither is configured, add the publisher or
+secret and re-run the **Publish** workflow from the Actions tab.
+
 ## License
 
 MIT

package/agents/executor.md

@@ -13,8 +13,9 @@ Repository instructions (AGENTS.md) and any skills available in this session app
 
 1. **Context.** Read the brief fully, plus referenced files and images, before acting. If critical context is missing, state what is missing rather than guessing.
 2. **Plan.** Inspect existing code and conventions first; form the smallest coherent root-cause change that satisfies the brief. Prefer the design that deletes complexity over one that rearranges it. No unrelated refactors or standalone docs work unless the brief asks.
-3. **Implement.** Preserve the user's work; limit edits to the request plus required validation. Follow the project's error handling, naming, and style. Synchronize README/docs/comments your change directly affects; never defer that drift.
-4. **Verify.** Run the project's format/build/tests when they exist. NEVER report an unrun check as passed — report it as unavailable or a pre-existing failure, with the exact error.
+3. **Confirm.** A finding is not a change. Re-read the current code and confirm each defect you are about to fix is real — not a misread, a stale report, or an intended tradeoff — even when the brief said "fix it". A false positive means zero edits and a note.
+4. **Implement.** Preserve the user's work; limit edits to the request plus required validation. Follow the project's error handling, naming, and style. Synchronize README/docs/comments your change directly affects; never defer that drift.
+5. **Verify.** Run the project's format/build/tests when they exist. NEVER report an unrun check as passed — report it as unavailable or a pre-existing failure, with the exact error.
 
 ## Conditional playbooks
 
@@ -44,7 +45,7 @@ What was done, in a few lines.
 
 ## Verification
 
-Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
+Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean). State explicitly anything you could not run and why.
 
 ## Notes (only when material)
 

package/agents/explorer.md

@@ -1,37 +1,37 @@
----
-name: explorer
-description: Fast read-only reconnaissance for broad or multi-file search in unfamiliar areas; returns exact paths and compressed findings as retrieval leads.
-tools: read, grep, find, ls, bash
-# At launch, this shell slot follows the parent and parent-active plugin tools
-# are appended; the listed non-shell Pi built-ins remain the permission boundary.
-thinking: low
----
-
-You are an explorer agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings so another agent does not repeat the whole search. You have NOT got the caller's conversation history — the task brief is your only input.
-
-## Hard constraints
-
-- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands. Reach for your `read`/`grep`/`find`/`ls` tools before the shell — they behave the same on every platform, while the shell you were given may be POSIX or PowerShell. Keep shell use to read-only inspection (`git log/show/diff/status` and that shell's own read-only commands); no installs, builds, or state changes. Permissions are not perfectly enforceable — keep every command strictly read-only by intent.
-- Every finding is a retrieval lead, never sufficient proof for deletion, security claims, public/API compatibility, persistence, or other load-bearing decisions. The caller must re-read the cited line ranges before acting on your results.
-
-## Workflow
-
-1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
-2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
-3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
-4. Record exact paths and line ranges so the caller can jump straight in.
-5. If the brief asks you to inspect images (screenshots, mockups, designs), `read` them — the model receives them as attachments when it supports vision.
-
-Thoroughness scales with the task (default medium): quick = targeted lookups in key files; medium = follow imports and callers, read critical sections; thorough = trace dependencies across modules, check tests and types.
-
-## Final response
-
-Return only retrieval results, one bare bullet per finding — a single line: path, the fact, nothing else:
-
-```text
-- `path/to/file.ts:10-50` — the fact
-Start here: `path/to/file.ts` — entry symbol and why (only when the caller could not guess it)
-Gaps: unresolved uncertainty (only when real)
-```
-
-No preamble or closing summary. Do not repeat the task brief, inventory every file opened, paste nonessential code, or narrate the search; every line must carry a path with a fact or name a gap — delete anything else. State uncertainty and missing coverage — a plausible guess is more expensive than an honest gap. Stay under 15 lines by default; go longer only when the brief genuinely demands a wide survey — the 40-line delivery cap truncates your tail (usually the Gaps) and the caller pays for every line.
+---
+name: explorer
+description: Fast read-only reconnaissance for broad or multi-file search in unfamiliar areas; returns exact paths and compressed findings as retrieval leads.
+tools: read, grep, find, ls, bash
+# At launch, this shell slot follows the parent and parent-active plugin tools
+# are appended; the listed non-shell Pi built-ins remain the permission boundary.
+thinking: low
+---
+
+You are an explorer agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings so another agent does not repeat the whole search. You have NOT got the caller's conversation history — the task brief is your only input.
+
+## Hard constraints
+
+- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands. Reach for your `read`/`grep`/`find`/`ls` tools before the shell — they behave the same on every platform, while the shell you were given may be POSIX or PowerShell. Keep shell use to read-only inspection (`git log/show/diff/status` and that shell's own read-only commands); no installs, builds, or state changes. Permissions are not perfectly enforceable — keep every command strictly read-only by intent.
+- Every finding is a retrieval lead, never sufficient proof for deletion, security claims, public/API compatibility, persistence, or other load-bearing decisions. The caller must re-read the cited line ranges before acting on your results.
+
+## Workflow
+
+1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
+2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
+3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
+4. Record exact paths and line ranges so the caller can jump straight in.
+5. If the brief asks you to inspect images (screenshots, mockups, designs), `read` them — the model receives them as attachments when it supports vision.
+
+Thoroughness scales with the task (default medium): quick = targeted lookups in key files; medium = follow imports and callers, read critical sections; thorough = trace dependencies across modules, check tests and types.
+
+## Final response
+
+Return only retrieval results, one bare bullet per finding — a single line: path, the fact, nothing else:
+
+```text
+- `path/to/file.ts:10-50` — the fact
+Start here: `path/to/file.ts` — entry symbol and why (only when the caller could not guess it)
+Gaps: unresolved uncertainty (only when real)
+```
+
+No preamble or closing summary. Do not repeat the task brief, inventory every file opened, paste nonessential code, or narrate the search; every line must carry a path with a fact or name a gap — delete anything else. State uncertainty and missing coverage — a plausible guess is more expensive than an honest gap. Stay under 15 lines by default; go longer only when the brief genuinely demands a wide survey — the 40-line delivery cap truncates your tail (usually the Gaps) and the caller pays for every line.

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.2.8",
+  "version": "4.2.12",
   "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MCapricorns/pi-subagents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MCapricorns/pi-subagents/issues"
+  },
+  "homepage": "https://github.com/MCapricorns/pi-subagents#readme",
   "publishConfig": {
     "access": "public"
   },

package/src/background.ts

@@ -1,205 +1,205 @@
-/**
- * Bounded background task scheduler.
- *
- * Tasks get their own AbortSignal rather than inheriting the foreground agent
- * turn's signal. The owning extension cancels all work only on session teardown.
- *
- * Task exceptions are never swallowed: the per-task onError callback receives
- * them (unless the task was cancelled) so callers can surface the failure to
- * the user and the main agent instead of it vanishing into the queue.
- */
-
-import { cpus } from "node:os";
-
-export type BackgroundTask = (signal: AbortSignal, controller: AbortController) => Promise<void>;
-
-interface PendingTask {
-	task: BackgroundTask;
-	controller: AbortController;
-	complete: () => void;
-	/** Called when a queued task is aborted before its body ever runs (drain skips
-	 * an already-aborted entry; cancelAll aborts every pending entry), so the
-	 * task body never produces a result. Callers that resolve waiters on a run id
-	 * must register a synthetic result here (or via a stop path) — otherwise a
-	 * waiter resolves via a "removed before its result was recorded" note. Never
-	 * called for a task whose body already started; that path owns its result. */
-	onCancelled?: () => void;
-	/** Invoked when the task throws and was not cancelled (cancellation is not a
-	 * failure — e.g. session shutdown races must never be reported as errors). */
-	onError?: (error: unknown) => void | Promise<void>;
-}
-
-/** How many sub-agent processes may run at once, derived from the host instead
- * of being fixed: children wait on model I/O far more than on CPU, so the pool
- * scales with cores while the bounds keep tiny machines usable and huge ones
- * from fanning out into an API-rate-limit wall. Pacing only — the queue never
- * rejects work; a wider parallel `subagent` call simply waits for a slot. */
-export function resolveSubagentConcurrency(cpuCount: number = cpus().length): number {
-	return Math.min(16, Math.max(4, Math.floor(cpuCount / 2)));
-}
-
-export class BackgroundTaskQueue {
-	private concurrency: number;
-	private readonly pending: PendingTask[] = [];
-	private readonly active = new Set<AbortController>();
-	/** Active tasks that no longer count toward the concurrency limit. They keep
-	 * every other guarantee: abortable, awaited by waitForTask/waitForIdle. */
-	private readonly suspended = new Set<AbortController>();
-	private readonly completions = new WeakMap<AbortController, Promise<void>>();
-	private readonly idleWaiters = new Set<() => void>();
-	private stopped = false;
-
-	constructor(concurrency: number) {
-		this.concurrency = Math.max(1, concurrency);
-	}
-
-	enqueue(task: BackgroundTask, onCancelled?: () => void, onError?: (error: unknown) => void | Promise<void>): AbortController {
-		const controller = new AbortController();
-		let complete!: () => void;
-		const completion = new Promise<void>((resolve) => {
-			complete = resolve;
-		});
-		this.completions.set(controller, completion);
-		if (this.stopped) {
-			controller.abort();
-			this.runCancelled(onCancelled);
-			complete();
-			return controller;
-		}
-
-		this.pending.push({ task, controller, complete, onCancelled, onError });
-		this.drain();
-		return controller;
-	}
-
-	/** Resolve after this exact task has left the pending/active sets. This is
-	 * stronger than waiting for its task body: callers may safely reuse a
-	 * concurrency slot or the task's persisted checkpoint after it resolves. */
-	waitForTask(controller: AbortController | undefined): Promise<void> {
-		if (!controller) return Promise.resolve();
-		return this.completions.get(controller) ?? Promise.resolve();
-	}
-
-	/** Slot count, exposed so dispatch/status output can state the real pacing
-	 * limit instead of leaving queued work looking like an unexplained cap. */
-	get capacity(): number {
-		return this.concurrency;
-	}
-
-	/** Tasks still waiting for a free slot (never started). */
-	get pendingCount(): number {
-		return this.pending.length;
-	}
-
-	/** Tasks currently holding a slot. Suspended tasks (lane waits, managed
-	 * workflow continuations) hold none and are excluded. */
-	get activeCount(): number {
-		return this.active.size;
-	}
-
-	/** Stop counting a running task toward the concurrency limit. Its body keeps
-	 * running under the same abort signal; completion still releases everything
-	 * waitForTask/waitForIdle promise. Frees a slot for queued work immediately.
-	 *
-	 * Used by tasks whose execution is serialized elsewhere anyway (managed
-	 * workflow continuations, shared-checkout writers waiting on the repository
-	 * lane): letting such a task also hold a global slot would let waiters
-	 * starve independent work that could start right away. The controller is
-	 * handed to the task body directly, so a task can always suspend itself
-	 * without racing the enqueue() caller's assignment. */
-	suspend(controller: AbortController | undefined): void {
-		if (!controller || this.stopped) return;
-		if (!this.active.delete(controller)) return;
-		this.suspended.add(controller);
-		this.drain();
-	}
-
-	/** Cancel one queued/running task. Queued entries are removed immediately;
-	 * active entries resolve waitForTask only after their body and error handler
-	 * have quiesced and the concurrency slot has been released. */
-	cancel(controller: AbortController | undefined): void {
-		if (!controller) return;
-		controller.abort();
-		const index = this.pending.findIndex((entry) => entry.controller === controller);
-		if (index !== -1) {
-			const [entry] = this.pending.splice(index, 1);
-			this.runCancelled(entry.onCancelled);
-			entry.complete();
-			this.drain();
-			this.resolveIdleWaiters();
-		}
-	}
-
-	/** Resolve once no queued or running task remains. */
-	waitForIdle(): Promise<void> {
-		if (this.pending.length === 0 && this.active.size === 0 && this.suspended.size === 0) return Promise.resolve();
-		return new Promise<void>((resolve) => this.idleWaiters.add(resolve));
-	}
-
-	/** Stop queued work and request cancellation for running work. */
-	cancelAll(): void {
-		if (this.stopped) return;
-		this.stopped = true;
-
-		for (const entry of this.pending.splice(0)) {
-			entry.controller.abort();
-			this.runCancelled(entry.onCancelled);
-			entry.complete();
-		}
-		for (const controller of this.active) controller.abort();
-		for (const controller of this.suspended) controller.abort();
-		this.resolveIdleWaiters();
-	}
-
-	/** Cancellation callbacks are user-supplied: a throw must never break the queue
-	 * (mirrors the try/catch around onError in drain). */
-	private runCancelled(callback: (() => void) | undefined): void {
-		if (!callback) return;
-		try {
-			callback();
-		} catch {
-			/* cancellation callbacks must never break the queue */
-		}
-	}
-
-	private drain(): void {
-		while (!this.stopped && this.active.size < this.concurrency) {
-			const entry = this.pending.shift();
-			if (!entry) {
-				this.resolveIdleWaiters();
-				return;
-			}
-			if (entry.controller.signal.aborted) {
-				this.runCancelled(entry.onCancelled);
-				entry.complete();
-				continue;
-			}
-
-			this.active.add(entry.controller);
-			void entry.task(entry.controller.signal, entry.controller)
-				.catch(async (error: unknown) => {
-					// Cancellation is not a failure: aborted work (e.g. session
-					// shutdown) must never be reported as an exception.
-					if (entry.controller.signal.aborted) return;
-					try {
-						await entry.onError?.(error);
-					} catch {
-						/* error reporting must never break the queue */
-					}
-				})
-				.finally(() => {
-					this.active.delete(entry.controller);
-					this.suspended.delete(entry.controller);
-					entry.complete();
-					this.drain();
-					this.resolveIdleWaiters();
-				});
-		}
-	}
-
-	private resolveIdleWaiters(): void {
-		if (this.pending.length > 0 || this.active.size > 0 || this.suspended.size > 0) return;
-		for (const resolve of this.idleWaiters) resolve();
-		this.idleWaiters.clear();
-	}
-}
+/**
+ * Bounded background task scheduler.
+ *
+ * Tasks get their own AbortSignal rather than inheriting the foreground agent
+ * turn's signal. The owning extension cancels all work only on session teardown.
+ *
+ * Task exceptions are never swallowed: the per-task onError callback receives
+ * them (unless the task was cancelled) so callers can surface the failure to
+ * the user and the main agent instead of it vanishing into the queue.
+ */
+
+import { cpus } from "node:os";
+
+export type BackgroundTask = (signal: AbortSignal, controller: AbortController) => Promise<void>;
+
+interface PendingTask {
+	task: BackgroundTask;
+	controller: AbortController;
+	complete: () => void;
+	/** Called when a queued task is aborted before its body ever runs (drain skips
+	 * an already-aborted entry; cancelAll aborts every pending entry), so the
+	 * task body never produces a result. Callers that resolve waiters on a run id
+	 * must register a synthetic result here (or via a stop path) — otherwise a
+	 * waiter resolves via a "removed before its result was recorded" note. Never
+	 * called for a task whose body already started; that path owns its result. */
+	onCancelled?: () => void;
+	/** Invoked when the task throws and was not cancelled (cancellation is not a
+	 * failure — e.g. session shutdown races must never be reported as errors). */
+	onError?: (error: unknown) => void | Promise<void>;
+}
+
+/** How many sub-agent processes may run at once, derived from the host instead
+ * of being fixed: children wait on model I/O far more than on CPU, so the pool
+ * scales with cores while the bounds keep tiny machines usable and huge ones
+ * from fanning out into an API-rate-limit wall. Pacing only — the queue never
+ * rejects work; a wider parallel `subagent` call simply waits for a slot. */
+export function resolveSubagentConcurrency(cpuCount: number = cpus().length): number {
+	return Math.min(16, Math.max(4, Math.floor(cpuCount / 2)));
+}
+
+export class BackgroundTaskQueue {
+	private concurrency: number;
+	private readonly pending: PendingTask[] = [];
+	private readonly active = new Set<AbortController>();
+	/** Active tasks that no longer count toward the concurrency limit. They keep
+	 * every other guarantee: abortable, awaited by waitForTask/waitForIdle. */
+	private readonly suspended = new Set<AbortController>();
+	private readonly completions = new WeakMap<AbortController, Promise<void>>();
+	private readonly idleWaiters = new Set<() => void>();
+	private stopped = false;
+
+	constructor(concurrency: number) {
+		this.concurrency = Math.max(1, concurrency);
+	}
+
+	enqueue(task: BackgroundTask, onCancelled?: () => void, onError?: (error: unknown) => void | Promise<void>): AbortController {
+		const controller = new AbortController();
+		let complete!: () => void;
+		const completion = new Promise<void>((resolve) => {
+			complete = resolve;
+		});
+		this.completions.set(controller, completion);
+		if (this.stopped) {
+			controller.abort();
+			this.runCancelled(onCancelled);
+			complete();
+			return controller;
+		}
+
+		this.pending.push({ task, controller, complete, onCancelled, onError });
+		this.drain();
+		return controller;
+	}
+
+	/** Resolve after this exact task has left the pending/active sets. This is
+	 * stronger than waiting for its task body: callers may safely reuse a
+	 * concurrency slot or the task's persisted checkpoint after it resolves. */
+	waitForTask(controller: AbortController | undefined): Promise<void> {
+		if (!controller) return Promise.resolve();
+		return this.completions.get(controller) ?? Promise.resolve();
+	}
+
+	/** Slot count, exposed so dispatch/status output can state the real pacing
+	 * limit instead of leaving queued work looking like an unexplained cap. */
+	get capacity(): number {
+		return this.concurrency;
+	}
+
+	/** Tasks still waiting for a free slot (never started). */
+	get pendingCount(): number {
+		return this.pending.length;
+	}
+
+	/** Tasks currently holding a slot. Suspended tasks (lane waits, managed
+	 * workflow continuations) hold none and are excluded. */
+	get activeCount(): number {
+		return this.active.size;
+	}
+
+	/** Stop counting a running task toward the concurrency limit. Its body keeps
+	 * running under the same abort signal; completion still releases everything
+	 * waitForTask/waitForIdle promise. Frees a slot for queued work immediately.
+	 *
+	 * Used by tasks whose execution is serialized elsewhere anyway (managed
+	 * workflow continuations, shared-checkout writers waiting on the repository
+	 * lane): letting such a task also hold a global slot would let waiters
+	 * starve independent work that could start right away. The controller is
+	 * handed to the task body directly, so a task can always suspend itself
+	 * without racing the enqueue() caller's assignment. */
+	suspend(controller: AbortController | undefined): void {
+		if (!controller || this.stopped) return;
+		if (!this.active.delete(controller)) return;
+		this.suspended.add(controller);
+		this.drain();
+	}
+
+	/** Cancel one queued/running task. Queued entries are removed immediately;
+	 * active entries resolve waitForTask only after their body and error handler
+	 * have quiesced and the concurrency slot has been released. */
+	cancel(controller: AbortController | undefined): void {
+		if (!controller) return;
+		controller.abort();
+		const index = this.pending.findIndex((entry) => entry.controller === controller);
+		if (index !== -1) {
+			const [entry] = this.pending.splice(index, 1);
+			this.runCancelled(entry.onCancelled);
+			entry.complete();
+			this.drain();
+			this.resolveIdleWaiters();
+		}
+	}
+
+	/** Resolve once no queued or running task remains. */
+	waitForIdle(): Promise<void> {
+		if (this.pending.length === 0 && this.active.size === 0 && this.suspended.size === 0) return Promise.resolve();
+		return new Promise<void>((resolve) => this.idleWaiters.add(resolve));
+	}
+
+	/** Stop queued work and request cancellation for running work. */
+	cancelAll(): void {
+		if (this.stopped) return;
+		this.stopped = true;
+
+		for (const entry of this.pending.splice(0)) {
+			entry.controller.abort();
+			this.runCancelled(entry.onCancelled);
+			entry.complete();
+		}
+		for (const controller of this.active) controller.abort();
+		for (const controller of this.suspended) controller.abort();
+		this.resolveIdleWaiters();
+	}
+
+	/** Cancellation callbacks are user-supplied: a throw must never break the queue
+	 * (mirrors the try/catch around onError in drain). */
+	private runCancelled(callback: (() => void) | undefined): void {
+		if (!callback) return;
+		try {
+			callback();
+		} catch {
+			/* cancellation callbacks must never break the queue */
+		}
+	}
+
+	private drain(): void {
+		while (!this.stopped && this.active.size < this.concurrency) {
+			const entry = this.pending.shift();
+			if (!entry) {
+				this.resolveIdleWaiters();
+				return;
+			}
+			if (entry.controller.signal.aborted) {
+				this.runCancelled(entry.onCancelled);
+				entry.complete();
+				continue;
+			}
+
+			this.active.add(entry.controller);
+			void entry.task(entry.controller.signal, entry.controller)
+				.catch(async (error: unknown) => {
+					// Cancellation is not a failure: aborted work (e.g. session
+					// shutdown) must never be reported as an exception.
+					if (entry.controller.signal.aborted) return;
+					try {
+						await entry.onError?.(error);
+					} catch {
+						/* error reporting must never break the queue */
+					}
+				})
+				.finally(() => {
+					this.active.delete(entry.controller);
+					this.suspended.delete(entry.controller);
+					entry.complete();
+					this.drain();
+					this.resolveIdleWaiters();
+				});
+		}
+	}
+
+	private resolveIdleWaiters(): void {
+		if (this.pending.length > 0 || this.active.size > 0 || this.suspended.size > 0) return;
+		for (const resolve of this.idleWaiters) resolve();
+		this.idleWaiters.clear();
+	}
+}