paniolo queue
Serialize heavy local commands across worktree slots, agents, hooks, and terminals on one machine. This page covers the queue configuration, the request lifecycle, and every subcommand with its options, output, and refusal codes. For the overview, see host queues.
Ships as a component
paniolo queue routes to the standalone paniolo-queue component (renamed from paniolo-serialize). It is part of the native Harness packages and needs no account. If the component is missing, the dispatcher fails closed with exit 69 rather than running anything uncoordinated; paniolo queue --help shows what your install carries.
Platform support. Native supervision is qualified on Windows, where each command runs inside a supervised job object. Linux, macOS, and WSL-native invocations refuse with UnqualifiedSupervisor (exit 69) until their supervisors qualify; there is no silent fallback that runs the command anyway.
Enrollment is explicit. Before the first run on a machine, create the private host state with paniolo queue host enroll. Nothing invents an implicit queue when enrollment or configuration is missing.
Lanes, requests, grants, runners
A queue (a lane) is a named host resource declared in the harness paniolo.config.json. Every lane is scoped to one host and capped at one running command; the capacity is the contract, not a default.
A small local broker (the coordinator) arbitrates admission. It starts on demand when a command needs it, exits after ten idle seconds, and is never started by read-only inspection. Queue keys combine a verified host domain with the lane name, so the same lane name reaches the same line from every repository, worktree, and terminal on the machine.
A request is one submitted command. Its lifecycle is queued โ admitted โ running โ finished. While queued it can be cancelled or time out; after admission it runs to its own exit. If a connection drops mid-run the request enters reconciling and keeps occupying the lane until supervision proves the process tree is quiescent.
An admitted request holds a grant executed by a dedicated runner. The grant frees only after the runner and every descendant it spawned exits, so a build that outlives its launcher cannot leave the lane falsely idle.
| State | Meaning |
|---|---|
queued | Waiting in FIFO order. Cancellable, and bounded by --wait-timeout. |
admitted | Granted the lane; the runner is starting the child. |
running | The supervised process tree is live and holds the lane. |
reconciling | Connection lost mid-run; still occupies the lane until quiescence is confirmed. |
finished | Process tree exited; the grant is released. |
cancelled / timed out / disconnected | Terminal while still queued; no child ever launched. |
This is cooperative coordination among one user's processes on one host, including explicitly enrolled WSL guests. It is not a security boundary, and coordination across OS users or machines is out of scope.
The queue section
Declare lanes under a top-level queue section in the harness paniolo.config.json. The gitignored paniolo.config.local.json overlay can add or override values, and config effective reports which file supplied each one.
{
"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
}
}
}Queue fields
| Field | Required | Meaning and rules |
|---|---|---|
queues.<name> | yes | A lane, keyed by its stable name. Up to 64 per catalog. |
queues.<name>.description | yes | Plain-language guidance for when an agent should choose this lane (at most 1024 characters, no control characters). It is documentation, not executable policy: nothing classifies a workload automatically. |
queues.<name>.scope | yes | Must be "host". The lane covers every participating process on the machine. |
queues.<name>.maxConcurrent | yes | Must be 1. Any other value refuses before a child starts. |
operations.<op>.queue | no | Maps a named operation (letters, digits, hyphens; at most 64 characters; up to 128 mappings) onto a configured lane so integrations and hooks enter the same line without an agent decision. Unknown targets refuse. |
agentStatus.enabled | no | Lets agent status hooks surface compact queue snapshots at session start and on change. It controls notices only; enforcement is always on. |
Lane definitions never execute anything on their own. A caller still enters a lane with run, and an unknown lane name refuses rather than creating an uncoordinated one.
Flags every command shares
| Flag | Effect |
|---|---|
--json | Emit versioned JSON (schema version 1). For run, outcome events go to stderr so the child's stdout stays clean. |
--config <path> | Read a specific paniolo.config.json instead of searching upward from the working directory. The matching local overlay merges in. |
--host-state <dir> | Select an explicitly enrolled host state directory. Every participating repository on the machine must use the same one. |
paniolo queue list
Prints the effective configured lanes with their descriptions, without starting the broker. With --json the output includes the resolved catalog and per-pointer file provenance.
paniolo queue list
heavy-load: Use when an agent needs to run a process with heavy memory and/or CPU load. (host, capacity 1)paniolo queue config effective
Prints the resolved queue section: lanes, operation mappings, agentStatus, and whether each value came from the tracked config or the local overlay. Malformed definitions, unsupported limits, and mappings to absent lanes refuse before any command runs.
paniolo queue config effective --jsonpaniolo queue status [--queue <name>]
Queries the live broker for the active request and waiting requests on every lane, or on one named lane. The view shows the safe labels you passed (--label, --repository), elapsed wait, and queue position; it never invents a completion estimate and never carries command arguments.
An unavailable or expired broker reports unavailable. Status fails closed: an unknown lane is never assumed idle.
paniolo queue status --queue heavy-load --jsonpaniolo queue run --queue <name> -- <program> [args...]
Submits the argument vector for FIFO admission on <name>. On admission a dedicated runner executes it directly: no shell interpolation, and the child keeps its working directory, environment, stdin, stdout, stderr, and exit code. Waiting happens without starting the child, so a queued request reserves no build working set.
paniolo queue run --queue heavy-load --label pre-push --repository ranch-hand-slot-01 -- git pushOptions
| Option | Effect |
|---|---|
--queue <name> | Required. The lane to enter; unknown names refuse. |
--label <label> | Safe display label for status (default command). Never inferred from the arguments. |
--repository <repo> | Safe repository or worktree label for status (default local). |
--no-wait | Return Busy (exit 75) immediately if the lane is occupied, instead of waiting. Conflicts with --wait-timeout. |
--wait-timeout <ms|s|m> | Bound time spent waiting (for example 30s or 5m), refusing with WaitTimeout (exit 124) if not admitted. It never limits the child's runtime after admission. |
--quiet | Suppress progress output. Child streams and refusal diagnostics are unchanged. Conflicts with --json. |
When the child runs, the command exits with the child's own code. When the queue refuses, it exits with a distinct sysexits-style code from the refusal table, so scripts can tell "the build failed" from "never ran."
paniolo queue cancel <request-id>
Cancels a request that is still queued, using the private receipt issued at submission in the same configuration context. Cancellation before admission guarantees no child launched. Requests already admitted or running cannot be cancelled here; they run to their own exit.
paniolo queue host enroll
Creates a new private host state directory and domain ID, once per machine. On Windows it lives under local application data in Paniolo/queue. It never adopts an existing directory; pass the result (or the default) to every repository via --host-state when you use a non-default location.
paniolo queue host recover
Reconciles abandoned native jobs after a crash left an unclosed broker journal and no live broker is listening, then restarts supervision. It refuses while a healthy broker holds the authority, so run it only when status reports OwnershipUnresolved (exit 73).
Refusal and exit codes
A refusal means the queue decided before anything ran. Child failures come back as the child's own exit code, never rewritten.
| Exit code | Refusal reasons | Meaning |
|---|---|---|
69 | CoordinatorUnavailable, UnqualifiedSupervisor, IncompatibleProtocol | Host not enrolled, broker unreachable, missing component, or unsupported platform supervisor. |
73 | OwnershipUnresolved | Abandoned broker journal exists; inspect the host and run paniolo queue host recover. |
75 | Busy, QueueFull | Lane occupied (--no-wait) or waiting capacity reached. |
77 | PolicyConflict | Registered lane policy conflicts with your config; the refusal names the registered owner. |
78 | InvalidConfig, UnknownQueue, DuplicateRequest | Missing or invalid queue config, or an unknown --queue name. |
124 | WaitTimeout | Request waited longer than --wait-timeout without admission. |
126 | LaunchFailed | The admitted child executable failed to spawn. |
130 | Cancelled | The request was cancelled while waiting in line. |
Nested commands do not dead-end
A wrapped command can itself call run on the same lane: the nested request reuses the parent's verified grant after the broker confirms membership, instead of queuing behind itself. Requesting a different lane while holding one is refused; multi-resource scheduling is deferred. Ownership is proven by supervised job membership, never by an environment flag a caller could set itself.
Recovery and troubleshooting
| Symptom | What to do |
|---|---|
| Exit 69 on every command | Check enrollment (paniolo queue host enroll) and platform support, then the installed component. status makes the same check read-only. |
| Exit 73 after a crash or forced shutdown | An abandoned journal is blocking admission. Run paniolo queue host recover once the old broker is actually gone. |
| Exit 78 naming a lane | The config does not declare it. Check paniolo queue config effective for the merged catalog and provenance. |
| Exit 75 or 124 while a peer works | Expected admission refusals. Switch to lighter work and resubmit, or let the FIFO hold your place by waiting without a timeout. |
Never treat an unavailable status as an idle lane: resolve enrollment or recovery first, then act on what status actually reports.
A typical agent session
# 1. See which lanes exist and what they are for
paniolo queue list
# 2. Check whether the heavy lane is free before committing to a gate
paniolo queue status --queue heavy-load
# 3. Either run the gate through the lane...
paniolo queue run --queue heavy-load --label pre-push --repository slot-01 -- git push
# ...or probe it and switch to lighter work when it is busy
paniolo queue run --queue heavy-load --no-wait --label pre-push --repository slot-02 -- git pushThe productive pattern is to submit the heavy command and keep working in another worktree slot on bounded tasks, or to let the FIFO admit it automatically while you prepare the next change. With agentStatus.enabled, supported hooks can also show a compact snapshot of lane activity at session start and when it changes.
Through MCP
Agents connected to the Paniolo MCP server get two tools that delegate to the same component. The read-only queue tool runs list, status, and config; queue_write runs cancel against a waiting request's receipt. Running a wrapped command is deliberately CLI-only.
Rules worth giving your agents
The published paniolo-queue skill carries these, so agents load them on their own:
paniolo skills add paniolo-ai/skills --skill paniolo-queue- Check the lane before the build. Read
statusorlistbefore launching heavy work, and enter the configured lane withruninstead of running unwrapped in parallel. - Unknown is not idle. A
CoordinatorUnavailableorOwnershipUnresolvedresult means resolve enrollment or recovery, never "the lane is free." - Waiting time is not runtime.
--wait-timeoutbounds the line, never the child; do not use it as a kill switch for a hung build. - Admission is not validation. A granted request proves scheduling, not that tests passed or that artifacts are safe to publish.