stackbone limits

stackbone limits targets a running agent installation. With no --agent it runs against the local-dev installation linked to the current project, so stackbone dev must be running. See target resolution. Every verb accepts --json and emits the standard envelope.

Read and operate the concurrency limits your workspace declares under limits in stackbone.config.ts. A limit caps how many slots can be busy at once, and workflows take and give back slots with acquireSlot and releaseSlot. See Concurrency limits for the model. The Limits screen in Studio shows the same data and offers the same actions.

Command	Purpose
stackbone limits list	List every limit with its capacity, busy and waiting counts.
stackbone limits slots <name>	List the slots of one limit: busy first, then the queue.
stackbone limits release <slotId>	Give a busy slot back, so the next run in the queue gets it.
stackbone limits capacity <name> <n|reset>	Override the declared capacity, or clear the override.
stackbone limits max-hold <name> <duration|reset>	Override the declared maxHold, or clear the override.

Every verb takes one flag:

Flag	Type	Description
--agent	string	Installation id to target. Defaults to the local-dev install.

stackbone limits list

List every limit: busy slots over the capacity, the number of runs waiting, and the max hold. A capacity or max hold set in Studio or with the CLI shows as an override next to the declared value.

voice-calls  18/20 busy  0 waiting  maxHold 45m
partner-api  5/8 (override; declared 5) busy  3 waiting  maxHold 20m (override; declared 10m)

stackbone limits slots

stackbone limits slots <name>

List the slots of one limit. Each line is the slot id, its state, the run that took it, and its label. Held and granted slots come first, then the waiting runs in queue order.

State	Meaning
held	A run holds the slot. It stays busy until releaseSlot or maxHold.
granted	The box gave the slot to a waiting run, and the run has not confirmed.
waiting	The run is in the queue for a slot.

voice-calls  2/2 busy  1 waiting  maxHold 45m
6c1f0e1a-7d4b-4b8e-9a51-2f3c4d5e6f70  held     4c8d2e17-9a0b-4f3c-8e6d-7b5a1c2d3e4f  call-1
a90b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d  held     7f1e2d3c-4b5a-4c6d-9e8f-0a1b2c3d4e5f  call-2
0d9e8f7a-6b5c-4d3e-8f2a-1b0c9d8e7f6a  waiting  2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d  call-3

stackbone limits release

stackbone limits release <slotId> --yes

Give a busy slot back. The oldest waiting run gets it at once. Use it when the release got lost: the work the slot guarded ended, and no workflow called releaseSlot. Otherwise the box frees the slot on its own when maxHold passes.

The verb asks for --yes, because the run that holds the slot may still be using it. It is idempotent: a slot that is not busy (already released, or still waiting) prints a note and changes nothing.

stackbone limits release 6c1f0e1a-7d4b-4b8e-9a51-2f3c4d5e6f70 --yes

stackbone limits capacity

stackbone limits capacity <name> <n|reset>

Set the capacity the box enforces over the value in stackbone.config.ts, or pass reset to go back to it. The value is a whole number of at least 1.

stackbone limits capacity voice-calls 30      # waiting runs get the new slots at once
stackbone limits capacity voice-calls reset   # back to the declared capacity

Lowering the capacity takes no slot back. Busy slots stay busy, and the box hands out new ones only when the busy count drops below the new value.

stackbone limits max-hold

stackbone limits max-hold <name> <duration|reset>

Set how long one slot may stay busy over the maxHold in stackbone.config.ts, or pass reset to go back to it. The value takes the same forms as maxHold: 45m, 2h, 90s, 500ms, or plain digits as milliseconds, up to 30 days.

stackbone limits max-hold voice-calls 2h      # slots granted from now on get 2h
stackbone limits max-hold voice-calls reset   # back to the declared maxHold

The new value applies only to slots granted after the change. A slot that is already granted or held keeps the expiry it got when it was granted: lowering the max hold takes back no running work, and raising it does not extend a busy slot.