Operator interventions

These verbs mutate runtime state. Most require confirmation; PHYSICAL-danger verbs also require --reason "...". Read the --reason and danger levels section in the overview before running any of these in anger.

Execution-level

orca execution pause   <id>                  # pause every non-terminal thread
orca execution resume  <id>                  # resume manually-paused threads
orca execution close   <id>                  # ACCEPTING → DRAINING
orca execution stop    <id>                  # pause + arm abort (first call)
orca execution stop    <id> --confirm        # abort (second call)
orca execution remove  <id>                  # remove a terminal exec from the registry

pause

Pauses every non-terminal thread. Threads in error-pause stay error-paused. Already-paused threads are a no-op.

resume

Resumes manually-paused threads. Does NOT resume error-paused threads — those need thread recover with a decision.

close an execution

Transitions ACCEPTING → DRAINING. No new submissions can join (via JOIN_EXISTING); running threads finish normally.

$ orca execution close 7a3f1c0e
execution 7a3f1c0e: accepting → draining (3 threads still active)

Use this when you want to wind an execution down cleanly. The execution becomes terminal once every thread finishes.

stop an execution

Two calls, confirmed abort. The first call (no --confirm) pauses the execution immediately and ARMS the abort; it is fully recoverable with execution resume. A second call with --confirm performs the abort: cancels threads, releases reservations, marks the execution aborted. A single stray --confirm on a not-yet-armed execution never aborts — it pauses and arms, same as the first call.

$ orca execution stop 7a3f1c0e
execution 7a3f1c0e paused and abort armed; run `orca execution stop 7a3f1c0e --confirm` to abort, or `orca execution resume 7a3f1c0e` to disarm

$ orca execution stop 7a3f1c0e --confirm
execution 7a3f1c0e aborted (phase=...)

On abort, reservations release IMMEDIATELY; in-flight transporter moves are signaled to cancel but may take a few seconds to settle.

Pitfalls:

• stop --confirm is a hard abort. Plates in transit may end up in an indeterminate physical location. After it you usually want to follow with labware where for every plate in the execution, then labware edit-location to reconcile the system view with reality.
• The first stop is recoverable — it only pauses and arms. Use execution resume to disarm if you change your mind.
• To wind down without aborting, use close instead.

remove

Drops a terminal execution from the registry. Doesn't touch the events archive (that's append-only — see forensics).

Thread-level surgery

Thread surgery only works on paused threads. If the thread is running, pause the execution or the thread first.

orca execution thread pause          <exec> <tid>
orca execution thread spawn          <exec> <template-name>
orca execution thread skip-method    <exec> <tid> --method-name <name> --reason "..."
orca execution thread abort-method   <exec> <tid> --method-name <name> --reason "..."
orca execution thread insert-method  <exec> <tid> --where <head|tail|before|after> [--anchor <name>] (--template <name> | --from-file <path>) --reason "..."
orca execution thread replace-method <exec> <tid> <target-method> (--template <name> | --from-file <path>) --reason "..."
orca execution thread skip-action    <exec> <tid> (--action-command <cmd> | --action-id <id>) --reason "..."
orca execution thread insert-action  <exec> <tid> <action-file.py> --where <head|tail|before|after> [--anchor <name>] --reason "..."
orca execution thread replace-action <exec> <tid> <target-command> <action-file.py> --reason "..."

Methods are targeted by NAME (--method-name), not by index. skip-method targets the first pending match; re-run for later occurrences. --reason is required on every surgery verb (skip-method, abort-method, insert-method, replace-method, skip-action, insert-action, replace-action); it becomes the audit-trail entry. Inserts require --where (one of head, tail, before, after); before/after also need --anchor. Method inserts/replacements take exactly one of --template (an already-registered method template) or --from-file (a .py file with a single @orca.method). Action inserts/replacements always read a .py file with a single @orca.action positional argument (action templates have no global registry).

pause a single thread

$ orca execution thread pause 7a3f1c0e tid-2
thread tid-2: paused (was running shake_step.shake)

skip-method

Skip a PENDING method named by --method-name. The thread resumes at the next method. Reservations the skipped method would have acquired are never taken. Skip targets the first match by name; re-run for a later occurrence. For a method that has already started, use abort-method.

abort-method

Abort the IN_PROGRESS method named by --method-name: aborts the running action and skips the rest of the method. Use this when a method is wedged and skip-method can't help because the method already started.

insert-method / insert-action

Insert a method or action into a paused thread's lane. Placement is set by --where (head, tail, before, after); before/after require --anchor <name>. insert-method takes one of --template / --from-file; insert-action takes a .py file path positionally.

replace-method / replace-action

Replace a method or action with a substitute. A PENDING target is spliced in place (skip + insert). If the target is the method/action this thread is error-paused ON, the replacement is STAGED to run next, and you must then run execution thread recover with abort-method / abort-action (after making the cell physically safe) to drop the failed step.

spawn

Spawn an extra thread off an existing template, attached to the execution. The template name is a positional argument. Used for one-off "I need another sample plate in this run" scenarios.

$ orca execution thread spawn 7a3f1c0e sample_journey
spawned thread tid-9 (sample_journey) status=...

Variables (live overrides)

orca var set    <key> <value> --execution <id>   # per-execution override
orca var set-global <key> <value>                # default for every future exec
orca var unset  <key> --execution <id>           # remove override; fall back to global/default

The variable name and value are positional; the execution is a --execution flag (id or prefix). set-global takes no execution.

A variable read inside a running thread sees the per-execution override first, then the global, then the workflow's VariableDefinition default. Setting mid-flight takes effect on the NEXT read; it does not retroactively change a value the thread already cached.

$ orca var set shake_speed 600 --execution 7a3f1c0e
shake_speed = 600  (execution 7a3f1c0e)

Cancel a reservation

orca reservation cancel <reservation-id> --execution <id> --reason "..."

The reservation id is positional; the execution is a --execution flag. Forces release of a held reservation. The thread that held it gets a typed error and pauses with an incident. --reason is required (audit trail). Use this only for actual stuck-reservation situations (hung driver, manual intervention requiring the device). List a held reservation's id first with orca reservation list --execution <id>.

Manual steps

When action code calls ctx.manual_step(...), the thread parks until an operator confirms. These verbs list the outstanding pauses and release them.

orca manual-step list [--execution <id>] [--all]   # emitted-but-unconfirmed manual steps
orca manual-step confirm <step-id> --execution <id> # release the parked thread

list scopes to one --execution (or --all across executions). confirm takes the step id positionally and the execution as a flag; it is a SAFE verb (no confirmation prompt, no --reason). Works against both backends.

Labware overrides

edit-location, reset-location, and set-volume are PHYSICAL and require --reason. edit-barcode and register are OPERATOR-level. get-volumes is a read.

# PHYSICAL — silently changes what active workflows think is true
orca labware edit-location  <id> <location> --reason "..."
orca labware reset-location <id> <location> --reason "..."
orca labware set-volume     <id> --well A1=100 --well B1=50 --reason "..."

# OPERATOR — recoverable
orca labware edit-barcode   <id> <barcode>              # or: --barcode <barcode>
orca labware register       <template> [--barcode <bc>] [--location <loc>]

# read
orca labware get-volumes    <id>

Verb	When to use
edit-location	The runtime thinks a plate is at X but it's physically at Y. The location is a positional argument. Correct the runtime view; the next move uses the corrected location.
reset-location	Used after a stop or manual reconciliation. Clears location history and sets a new starting location (positional), no audit-trail link to any prior move.
edit-barcode	The runtime-recorded barcode is wrong (scanner mis-read, manual relabel). The new barcode is positional or --barcode; conflicting values are rejected.
register	Add a new labware instance to the runtime mid-run. The template name is positional; --barcode and --location are optional.
set-volume	Assert absolute per-well volumes (uL). Repeat --well WELL=VOLUME per well. Overrides tracked volume; overfill beyond a well's capacity is rejected.
get-volumes	Read per-well volumes folded from the ledger (seeded + set, minus aspirate/dispense).

Pitfalls

• edit-location is PHYSICAL because it can silently corrupt active workflows. The next move the runtime issues will route based on the new location. If a thread already mid-move sees the change, results are undefined. Best practice: pause the affected execution first, edit, then resume. Existing reservations are NOT auto-cancelled — inspect them with orca reservation list first.
• reset-location is for "the runtime and reality have diverged; this is the truth now" situations — typically after a stop or external intervention. Only safe before any thread has moved the labware; at runtime it corrupts the owning thread's location assumptions.
• register --location <location> does NOT physically place the plate. The CLI assumes the plate already exists there.

Raw device commands

For debugging and recovery.

orca device send       <id> <command>    [key=value ...] [--params <json>]   # arbitrary backend command
orca device invoke     <id> <capability> [key=value ...] [--params <json>]   # call a typed interface method
orca device initialize <id>                                                  # run the driver's initialize hook

Both send and invoke take options either as positional key=value pairs or as a single --params JSON object (not @file; --params wins if both are given). Values in key=value form are best-effort typed (true/false → bool, integer → int, else float, else string).

orca device send

Generic backend command. Lower-level than invoke — bypasses the typed interface layer.

orca device send shaker_01 set_temperature celsius=37
orca device send shaker_01 set_temperature --params '{"celsius": 37}'

orca device invoke

Calls a method on the device's typed driver interface. Pass the bare method name as it appears in orca device capabilities <id>. A legacy <namespace>.<method> form is accepted but the namespace is ignored — dispatch is by method name.

orca device invoke shaker_01 shake duration=30 speed=500
orca device invoke shaker_01 shake --params '{"duration": 30, "speed": 500}'

orca device initialize

Runs the driver's initialize hook. Use after a device reset or comms re-establishment.

Pitfalls

• send and invoke bypass the workflow engine. They acquire a short-term device reservation, run the command, release. If a workflow thread is mid-method on that device, both will queue behind it.
• Direct commands can leave labware state stale. If you send shaker.shake directly, the runtime doesn't update any labware "was shaken" facts. Use direct commands for diagnostics, not as a replacement for workflow actions.
• initialize may take seconds to minutes depending on the driver. The CLI shows status updates if --verbose.