murmur wait

Blocks until an agent reaches a target phase, a terminal phase, or comes to rest awaiting input — then prints a one-line outcome and the agent’s status. Useful in scripts and CI pipelines that need to act on agent completion. The wait ends when the first of these happens:

the agent enters the --phase target (if one was given),
the agent enters a terminal phase (PHASE_COMPLETED, PHASE_FAILED, PHASE_CANCELED),
the agent comes to rest: PHASE_TASK_COMPLETE, PHASE_IDLE, or PHASE_SLEEPING with no queued follow-ups. A resting agent cannot move again without input — a sleeping agent never completes on its own — so waiting longer can never be satisfied. Check the printed phase: “at rest” means the agent is awaiting follow-ups, not finished.

The command is interruptible — press Ctrl-C to stop waiting.

Synopsis

murmur wait [flags] [slug]

On a VM, the slug is optional — omitting it queries the current agent’s own status.

Arguments

Name	Type	Required	Description
`slug`	string	on laptop	The agent’s slug. Optional on VMs (defaults to self).
`--phase`	string	no	The phase to wait for — `running`, `task-complete`, and `PHASE_TASK_COMPLETE` spellings all work. Default: none — wait until the agent is terminal or at rest.
`--workspace`	string	no	Workspace name. Overrides the value from `murmur.yaml`.

Valid phases

Phase	Meaning
`PHASE_STARTING`	Agent is provisioning — acquiring a VM and preparing the workspace.
`PHASE_RUNNING`	Agent is actively working on a task.
`PHASE_TASK_COMPLETE`	Agent finished a task and is waiting for follow-ups or will go idle.
`PHASE_IDLE`	Agent is idle — VM is still running, waiting for a follow-up or sleep.
`PHASE_SLEEPING`	VM is stopped. The agent wakes on the next follow-up or `murmur wake`.
`PHASE_DESTROYING`	Agent is shutting down and releasing its VM.
`PHASE_COMPLETED`	Agent finished and exited normally. Terminal.
`PHASE_FAILED`	Agent encountered an error. Terminal.
`PHASE_CANCELED`	Agent was killed. Terminal.

If the agent reaches a terminal phase — or comes to rest — before the target phase, the command returns immediately with the current status. A target-phase wait never blocks on an agent that cannot reach the target on its own.

Output

The command prints a one-line outcome (wait ended: …) followed by the same status output as murmur status — workflow ID, phase, VM assignment, progress, output, and cost.

Examples

Wait for an agent to finish its work

murmur wait fix-auth

wait ended: turn finished (task-complete) — agent is awaiting follow-ups and will rest per its on_idle policy
workflow: github_oauth/alice/w/backend/fix-auth
phase:    PHASE_TASK_COMPLETE
response: Fixed the auth middleware to validate JWT expiry before checking claims.
pr:       Fix JWT expiry validation (https://github.com/acme/backend/pull/42)
commits:  3
cost:     $0.85

Wait for an agent to start running

murmur wait --phase running fix-auth

wait ended: target phase running reached
workflow: github_oauth/alice/w/backend/fix-auth
phase:    PHASE_RUNNING
vm:       murmur-a1b2c3d4 (acme-agents/us-central1-a) [running]
version:  0.4+a1b2c3d4

Wait in a script

murmur spawn fix-auth --task "Fix the JWT expiry bug"
murmur wait fix-auth
echo "Agent finished or needs input — check the phase"

Waiting on an agent that went to sleep

murmur wait --phase PHASE_COMPLETED fix-auth

wait ended: agent is at rest (sleeping) — it will not progress or complete on its own; use queue_add to give it work, wake to start its VM, or kill to end it
workflow: github_oauth/alice/w/backend/fix-auth
phase:    PHASE_SLEEPING

Under the default on_idle: sleep policy an agent parks its VM after the idle timeout and never reaches PHASE_COMPLETED by itself. The command returns the resting status instead of blocking forever — send a follow-up with murmur queue add or kill the agent to drive it terminal.

Agent fails before reaching target phase

murmur wait --phase PHASE_IDLE fix-auth

wait ended: agent is terminal (failed)
workflow: github_oauth/alice/w/backend/fix-auth
phase:    PHASE_FAILED

The command returns because PHASE_FAILED is terminal — it does not block forever waiting for PHASE_IDLE.

Errors

Code	Meaning	What to do
`NOT_FOUND`	No agent with that slug exists.	Check the slug spelling. Use `murmur ls` to see running agents.
`UNAUTHENTICATED`	Identity token is missing or expired.	Run `murmur auth` or check your `murmur.local.yaml` configuration.
`DEADLINE_EXCEEDED`	The wait was interrupted or timed out.	Re-run the command, or check the agent’s status with `murmur status`.
—	`unknown phase "<value>"`	The `--phase` value is not a recognized phase name. Use one of the phases listed above.

Agents — concept overview
murmur status — check an agent’s current status
murmur sleep — stop an agent’s VM
murmur wake — restart a sleeping agent’s VM
murmur spawn — start an agent
murmur ls — list running agents

Getting Started

Core Concepts

Guides

Synopsis

Arguments

Valid phases

Output

Examples

Wait for an agent to finish its work

Wait for an agent to start running

Wait in a script

Waiting on an agent that went to sleep

Agent fails before reaching target phase

Errors

​Synopsis

​Arguments

​Valid phases

​Output

​Examples

​Wait for an agent to finish its work

​Wait for an agent to start running

​Wait in a script

​Waiting on an agent that went to sleep

​Agent fails before reaching target phase

​Errors

​Related

Synopsis

Arguments

Valid phases

Output

Examples

Wait for an agent to finish its work

Wait for an agent to start running

Wait in a script

Waiting on an agent that went to sleep

Agent fails before reaching target phase

Errors

Related