Paniolo Harness · Host queues

Heavy work takes turns.

Worktree slots isolate source and build caches, but every slot still shares one CPU, one SSD, and one pool of RAM. paniolo queue runs a command only after its named host lane admits it, in arrival order, so gates stop colliding on the machine.

# Enroll this machine once paniolo queue host enroll # Send a heavy gate through the shared lane paniolo queue run --queue heavy-load --label pre-push --repository slot-01 -- git push # Who is running, who is waiting paniolo queue status --queue heavy-load
The contention tax

Two builds, one machine.

Parallel agents look free until the hardware binds. Two heavy gates on one workstation oversubscribe the CPU, the memory, and the disk at the same time, and both get slower together.

~2x at the median

Overlapping heavy gates versus solo runs in our Ranch Hand gate logs, across 1,511 runs on one Rust workspace.

1.38x vs 1.16x

Simulated session speedup from halving tool time versus halving model generation, across roughly 12,000 real agent sessions. Tool time is where sessions are won.

Nearly 1:1

Model calls to tool executions per session across 13 million GitHub Copilot sessions. Every additional concurrent agent multiplies tool-side load roughly linearly.

Our gate numbers are observational data from daily development, not a controlled benchmark; a gate that runs longer for any reason is more likely to overlap. The external figures are the authors' own, digested in our research index.

How it works

Request. Wait. Run. Release.

A small local broker arbitrates each configured lane. Queues are host-scoped and capacity one by design, so every caller that matters reaches the same line.

Request

An argv vector, never a shell string

You name the queue and pass the command after --. Arguments run with no shell interpolation, and safe labels (--label, --repository) are what status shows; command text never enters shared state.

Wait

FIFO, with honest waiting

Requests admit in arrival order. --no-wait returns a busy outcome so you can switch to lighter work, and --wait-timeout bounds the wait without ever imposing a runtime limit on the child.

Run

Supervised until the tree exits

A dedicated runner holds the lane's grant until the process and every descendant exits, so a surviving compiler child cannot free the lane early. Nested calls on the same queue reuse the verified grant instead of deadlocking.

Release

The next request starts itself

When the grant frees, the broker admits the next waiter automatically. If the broker or a runner dies mid-run, the lane stays occupied until recovery proves the work is quiescent.

Deterministic, not advisory

The machine decides who runs.

A prompt that asks agents not to overlap builds works until a hook, a child subagent, or a second terminal launches one anyway. The queue enforces the same rule for every caller.

Honest status

An unavailable or expired broker reports unavailable. Status never assumes a lane is idle because it failed to look.

Cooperative by design

The queue coordinates one user's processes on one host, including enrolled WSL guests. It is a scheduling contract, not a security boundary.

No replay

Waiting commands are never persisted for automatic replay. A request cancelled before admission is a guarantee that no child launched.

Private cancellation

Cancelling a waiting request needs its private receipt in the same configuration context. Only the owner can pull a request out of line.

Capacity stays one

Configuration cannot raise a lane's limit or create a private fallback. A conflicting scope or limit refuses and names the registered owner.

Qualified, or refused

Native supervision is qualified on Windows. Other platforms refuse rather than silently running an uncoordinated fallback.

Configure once

Name the lanes in your harness.

Queues live in the harness paniolo.config.json under a top-level queue section. The description tells an agent when to choose the lane; operation mappings wire known hooks to it. Neither one runs anything by itself.

"queue": { "queues": { "heavy-load": { "description": "Use when an agent needs to run a process with heavy memory and/or CPU load.", "scope": "host", "maxConcurrent": 1 } }, "operations": { "pre-push-gate": { "queue": "heavy-load" }, "release": { "queue": "heavy-load" } }, "agentStatus": { "enabled": true } }

paniolo queue config effective --json shows the resolved catalog with the tracked-versus-local provenance of every value, so an agent can see which file set each rule.

The research behind the lane

Why the lane is one wide.

The evidence for serializing heavy local work is old and consistent. Microsoft's C++ build-throughput investigation documented the oversubscription curve from the vendor side: parallel builds speed up only until CPU, memory, or the filesystem binds, and a script that spawned a quadratic number of compiler processes paged the machine into a two-to-three-times slowdown. Ranch Hand gates hit the same walls with linkers instead of cl.exe.

Microsoft C++ team, Nov 2021 — devblogs.microsoft.com/cppblog/cpp-build-throughput-investigation-and-tune-up

On the agent-workload side, the session-level FreeInference analysis (roughly 12,000 sessions, 1.19 million model requests, 1.21 million tool calls across 13 agent harnesses) puts tool execution at 21.7% of session time and user idle at 50.3%. Halving tool time produced a simulated 1.38x speedup, against 1.16x for decode. Faster models buy less than faster tools.

Nixon, Tian, Zheng, Yang, Gunawi — FreeInference, 2026, systems.seas.harvard.edu/blog/agentic-traces-freeinference · dataset 10.5281/zenodo.23903440

At production scale, the Copilot characterization found model calls coupled to tool executions nearly one to one. Multiply concurrent agents and you multiply tool-side load by about the same factor, which is what a host lane exists to bound.

Liu, Qiu, Goiri, Fonseca, Bianchini, Choukse — arXiv 2026, arxiv.org/abs/2608.00101

The queue pairs naturally with worktree slots: slots keep source and caches apart, the lane keeps the machine for one gate at a time. The case for testing the merged state before either branch lands goes back to Brun, Holmes, Ernst, and Notkin's FSE 2011 study, where a third of the 399 merges version control called clean still broke the build or the tests. Rebase once, then spend one gate.

Brun, Holmes, Ernst, Notkin — FSE 2011, dl.acm.org/doi/10.1145/2025113.2025139

More of the research behind the Harness lives on the harness research page, and every digested paper is listed in the paper index.

Honest answers

Before you ask

Who uses the queue: agents or humans?
Both. Anything that can run a command enters the same lane: an agent wrapping a gate, a Git hook, a terminal command, a background worker. Agents connected to the Paniolo MCP server also get queue (list, status, config) and queue_write (cancel) tools; running a wrapped command stays CLI-only.
Does it work on Windows?
Windows native is the qualified platform, supervised through job objects so the lane stays claimed until the whole process tree exits. Enrollment is explicit: paniolo queue host enroll once per machine. Linux and macOS refuse until their supervisors qualify rather than running uncoordinated.
Does my command go through a shell?
No. Everything after -- runs as an argument vector with no shell interpolation, keeping its working directory, environment, stdio, and exit code.
What happens if the agent or broker dies mid-gate?
The lane moves to reconciling and stays occupied until the supervisor proves the process tree is quiescent. A crash left behind an abandoned journal, paniolo queue host recover reconciles it explicitly; nothing grants overlapping work because a timeout elapsed.
Can I get two lanes or a capacity of two?
You can declare as many named queues as you need; each is independent and fixed at capacity one for this release. A config that tries to raise the limit or a caller that tries to override registered policy is refused.
Does it replace worktree slots?
No, it completes them. Slots isolate files, branches, and build caches; the queue serializes the shared hardware underneath them. Use worktree slots to give each agent its own checkout and paniolo queue to keep their heavy gates from colliding.
What does it cost?
Host queues are part of the Paniolo CLI and need no account. See pricing for the Harness plans.

Keep the machine for one gate at a time.

paniolo queue run --queue heavy-load -- <command>

Read the docs