CLI guide ยท Harness

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.

Availability

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.

Concepts

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.

StateMeaning
queuedWaiting in FIFO order. Cancellable, and bounded by --wait-timeout.
admittedGranted the lane; the runner is starting the child.
runningThe supervised process tree is live and holds the lane.
reconcilingConnection lost mid-run; still occupies the lane until quiescence is confirmed.
finishedProcess tree exited; the grant is released.
cancelled / timed out / disconnectedTerminal 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.

Configuration

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

FieldRequiredMeaning and rules
queues.<name>yesA lane, keyed by its stable name. Up to 64 per catalog.
queues.<name>.descriptionyesPlain-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>.scopeyesMust be "host". The lane covers every participating process on the machine.
queues.<name>.maxConcurrentyesMust be 1. Any other value refuses before a child starts.
operations.<op>.queuenoMaps 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.enablednoLets 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.

Common options

Flags every command shares

FlagEffect
--jsonEmit 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.
Command

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)
Command

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 --json
Command

paniolo 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 --json
Command

paniolo 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 push

Options

OptionEffect
--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-waitReturn 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.
--quietSuppress 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."

Command

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.

Command

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.

Command

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).

Reference

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 codeRefusal reasonsMeaning
69CoordinatorUnavailable, UnqualifiedSupervisor, IncompatibleProtocolHost not enrolled, broker unreachable, missing component, or unsupported platform supervisor.
73OwnershipUnresolvedAbandoned broker journal exists; inspect the host and run paniolo queue host recover.
75Busy, QueueFullLane occupied (--no-wait) or waiting capacity reached.
77PolicyConflictRegistered lane policy conflicts with your config; the refusal names the registered owner.
78InvalidConfig, UnknownQueue, DuplicateRequestMissing or invalid queue config, or an unknown --queue name.
124WaitTimeoutRequest waited longer than --wait-timeout without admission.
126LaunchFailedThe admitted child executable failed to spawn.
130CancelledThe request was cancelled while waiting in line.
Semantics

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.

Troubleshooting

Recovery and troubleshooting

SymptomWhat to do
Exit 69 on every commandCheck 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 shutdownAn abandoned journal is blocking admission. Run paniolo queue host recover once the old broker is actually gone.
Exit 78 naming a laneThe config does not declare it. Check paniolo queue config effective for the merged catalog and provenance.
Exit 75 or 124 while a peer worksExpected 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.

For coding agents

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 push

The 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 status or list before launching heavy work, and enter the configured lane with run instead of running unwrapped in parallel.
  • Unknown is not idle. A CoordinatorUnavailable or OwnershipUnresolved result means resolve enrollment or recovery, never "the lane is free."
  • Waiting time is not runtime. --wait-timeout bounds 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.