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 in 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 cannot satisfy the request. 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] [path]

On a VM, the path is optional. If you omit it, the command waits on the current agent itself.

Arguments

Name	Type	Required	Description
`path`	string	on laptop	The agent’s slug, or a slash-separated path to a descendant (e.g. `director/fix-auth`). Use an absolute path like `/w/{workspace}/{owner_provider}/{account}/{slug}` for an agent outside your own path. On a VM, a relative path names a child of the calling agent, and omitting it targets the calling agent itself.
`--phase`	string	no	The phase to wait for. The spellings `running`, `task-complete`, and `PHASE_TASK_COMPLETE` all work. The command exits non-zero if the wait ends in another phase. By default, waits until the agent is terminal or at rest, and exits non-zero if the agent failed, was canceled, or reported an error.
`--timeout`	int	no	Maximum seconds to block. On timeout, the command prints the latest status and exits non-zero. `0` means no client deadline. Default: `0`.
`--json`	bool	no	Print the `AgentStatus` as JSON instead of the outcome line and status. Default: `false`.
`--workspace`	string	no	Workspace name. Overrides the value from `murmur.yaml`.

Valid phases

Phase	Meaning
`PHASE_BILLING_BLOCKED`	Billing does not currently allow the organization new usage. The agent waits without a VM.
`PHASE_STARTING`	Agent is provisioning: acquiring a VM.
`PHASE_RECOVERING_VM`	The agent’s VM stopped and its disk is being brought back.
`PHASE_PREPARING_WORKSPACE`	Repositories are being cloned or updated. Precedes the agent’s first turn.
`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 destroying 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. On timeout, it prints only the status, without the outcome line. With --json, it prints only the AgentStatus as JSON.

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_app/acme/w/backend/github_oauth/alice/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)
cost:     $0.85

Wait for an agent to start running

murmur wait --phase running fix-auth

wait ended: target phase running reached
workflow: github_app/acme/w/backend/github_oauth/alice/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 Fix the JWT expiry bug
murmur wait --timeout 3600 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_app/acme/w/backend/github_oauth/alice/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, and exits non-zero because the target phase was not reached: 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_app/acme/w/backend/github_oauth/alice/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 login` or check your `murmur.local.yaml` configuration.
none	`wait timed out after <N>s (phase <phase>)`: `--timeout` elapsed before the wait ended. The latest status is printed first.	Re-run with a longer `--timeout`, or check the agent’s status with `murmur status`.
none	`wait ended in phase <phase> before target phase <target>`: the wait ended (terminal or at rest) in a phase other than `--phase`.	Read the printed status. Send a follow-up with `murmur queue add` or kill the agent.
none	`wait ended: agent failed`, `wait ended: agent canceled`, or `wait ended: task reported an error`: without `--phase`, the agent failed, was canceled, or marked its result as an error.	Read the printed status for the cause.
none	`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