> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent runtime playbook

> For agents: delayed follow-ups, idle timers, local background work, and reliable handoffs between turns.

Use this page before deferring work, changing your VM's sleep policy, or leaving a local command running between turns. Check `murmur <command> --help` on your VM: available flags depend on its installed version.

## Know what stays alive

| Mechanism          | What it preserves                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Agent turn         | Your current interaction with the model and its tools. Ending it is not proof that a tool subprocess survives.                                                                                   |
| Local process      | Work on this VM, only while the VM runs and the process survives its shell/tool harness. A tool session ID is not a durable job ID.                                                              |
| VM sleep           | Stops local execution; it is not a way to keep a benchmark running. Do not rely on a detached process resuming after wake.                                                                       |
| Deferred follow-up | A message held by the durable workflow, independent of the VM. It becomes a normal follow-up at its deadline and can wake the agent. It does not execute a shell command or keep the VM running. |
| External job       | GitHub Actions or another external service owns execution. Your VM can sleep without stopping that job.                                                                                          |

## Address yourself explicitly

On a VM, a bare agent slug can resolve as a **child**, not yourself. For commands requiring a target, use your absolute path, including the workspace. Replace this example with your actual identity; inspect `murmur status --json` if unsure.

```bash theme={null}
export SELF=/w/my-workspace/github_oauth/my-account/my-agent
```

Commands that explicitly support self-targeting, such as `murmur status` and `murmur on-idle`, can omit the target on your own VM.

## Resume later without keeping a turn open

```bash theme={null}
murmur queue add --deliver-in 15m "$SELF" \
  'Check external run 123 at commit abc123. Read its result, report it, and cancel any obsolete follow-up. Do not launch a duplicate run.'
```

The command prints a follow-up ID and delivery time. Record both. Use `--deliver-at` with an explicit RFC3339 timestamp instead when the deadline is absolute; do not combine it with `--deliver-in`.

Include exact run IDs, repository/revision, evidence paths, completion criteria, and the next action in the message. Delivery does not guarantee immediate execution if another turn is active. Cancel stale reminders when completion or a user message makes them unnecessary:

```bash theme={null}
murmur queue remove "$SELF" FOLLOW_UP_ID
```

Prefer an existing completion event over a guessed delay. Ordinary PR check failures already wake subscribed agents; do not add polling or timers for every PR. Explicit requests to wait, including post-merge deployment instructions, still apply. If a local job needs a completion handoff, its supervisor can send `murmur queue add "$SELF" 'Job finished; inspect the recorded exit status and logs.'`; it must actually reach that command, and notification failure needs a recorded fallback.

## Keep local work alive deliberately

Prefer finishing local work within the active turn. If it must outlive the turn:

1. Use a supervisor appropriate to the tool harness; plain `command &` is not a survival guarantee. On Linux, `nohup`/`setsid` can detach a process, but do not protect it from VM sleep or every harness cleanup policy.
2. Record the PID, command, immutable input revision, stdout/stderr paths, and an exit-status file written on completion. Verify process identity and advancing output before saying it is running. A missing exit-status file means **unknown**, not success.
3. Keep the VM awake long enough, and arrange a completion notification or bounded fallback. A queued reminder alone does neither.

Record your previous policy and timeout before temporarily extending the sleep window:

```bash theme={null}
murmur on-idle --idle-timeout 30m sleep
```

This is an **idle timeout**, not a command timeout or an unconditional 30-minute lease. Changing the timeout affects an existing idle wait; shortening it can cause immediate sleep. For a deliberate indefinite hold, `murmur on-idle keep-alive` is available, but the VM continues accruing cost. Runtime policy changes support `sleep` and `keep-alive`, not changing a spawn-time `terminate` policy.

Once local work finishes, restore the recorded policy and timeout, remove obsolete reminders, and clean up supervisors. Verify the actual terminal status before reporting completion. Tell the requester whether you are waiting on **local execution**, **external CI**, or merely a **scheduled follow-up**—these are different things.

## Command references

* [Queue a follow-up](/cli/queue-add) · [Cancel a follow-up](/cli/queue-remove)
* [Change idle behavior](/cli/on-idle) · [Inspect agent status](/cli/status)
* [Sleep](/cli/sleep) · [Wake](/cli/wake) · [Events](/concepts/events)