Giving Muse Spaces Async Jobs: A Design Pattern for Synchronous-Only Actions
Asking an AI to "do the work later" doesn't guarantee that anything keeps running in the background. You need three things: a record of the work, a signal that wakes the agent, and a procedure for delivering the result. And so that work survives when a signal is lost, the source of truth (the record that decides the state of the work) belongs in a database.
This post walks through that idea using one public example: a design pattern that gives async jobs to Muse, Meta's personal AI agent. Muse has a feature called "Spaces," which consist of a web app, their own database (DB), and synchronous actions. You don't need to know Muse or Spaces to follow along; I explain the necessary background as we go.
1. Why you can't just build "accept now, deliver later"
Imagine a service built on a Space: an order form where, once an order comes in, an agent produces the work in the background and delivers it when it's done.
The problem is that Spaces have none of the following out of the box:
- A worker that keeps running in the background
- Events that tell the agent when the DB changes
- A job queue
All a Space can do is run actions synchronously when they're called. It can write an order to the DB, but it has no way to tell the agent "an order came in," and no mechanism for taking orders off a queue one by one. So the flow "accept an order, produce in the background, deliver" can't be built as-is.
Independent developer @nakamo326 has published a design pattern that fills this gap using only existing parts. It's a reusable pattern packaged as a skill (SKILL.md plus templates), under the MIT license. The GitHub repository was created on 2026-11-10. It uses just four parts: file writes, a watch hook, cron, and Space actions.
Here is the author's post announcing it, which summarizes the core of the design in a few lines:
https://x.com/nakamo326/status/2120114658145398889
And here is the repository, where you can read the README, SKILL.md, and templates:
https://github.com/nakamo326/muse-space-async-jobs
According to the post, there are three key points. Spaces can only do synchronous work, so the source of truth lives in the DB. The trigger is a signal file local to the VM. And monitoring uses the watch-hook mechanism Muse already has, not cron. The following sections cover how these three fit together and why the design takes this shape.
2. The big picture: register in the DB, wake with a signal, re-check the source of truth, then process
The flow has five steps. Here I describe the overall design as the skill defines it. The paid implementation contract document separates this from what the reference implementation has actually verified.
- ① The Producer (the Space) registers a job in the DB with status
queued. This is the source of truth. - ② It appends one event line to a signal file (JSONL). The signal is only a "hint."
- ③ A watch hook (bash, polling every 30–60 seconds, meaning it checks at a fixed interval) detects the new event and wakes the agent.
- ④ The worker (the agent) doesn't trust the IDs written in the signal. It sweeps the source of truth, then claims a job (an operation that secures ownership of it: a conditional transition plus a token), processes it, and delivers it.
- ⑤ A Reconciler, run by low-frequency cron (scheduled execution), recovers stuck jobs (only high-importance jobs, Tier A).
[Figure: body-1.png]
Work flows around the DB, and the signal file is used only as "a signal to wake things up."
Each signal line has fields such as a per-event UUID (event_id) and job_id. The signal file lives at ~/hooks/state/<producer>-signal.jsonl, and the hook interval is set when the hook is registered.
The hook has rules too. A single poll wakes the agent at most once. The wake-up message contains no IDs or job data. While a worker is running (that is, while a fresh worker lock, a record showing it is active, exists), the hook skips waking and doesn't touch the record of already-seen events (seen). Signals it skipped are picked up after the running worker finishes.
In other words, the signal is what gets the agent out of bed, but what to do is decided by the DB, which the agent re-reads after waking.
3. Why the DB is the source of truth, not the signal
There are four core principles, and the first is "the signal is a hint; the source of truth is the DB." You don't trust the signal, so that if it breaks or vanishes, no real harm results.
This principle isn't just theory. An incident on the reference implementation's first day of operation shows it, and the README documents it.
The job IDs in the sandbox DB used for testing contaminated the seen record in the production signal file. The production system nearly treated that job ID as already processed, which could have suppressed a real job's signal.
No actual harm resulted, because the worker that woke up swept the source of truth instead of relying on the signal. Even if a signal is swallowed, a queued job still in the DB will be found the next time the worker wakes. The sweep provided a final line of defense, allowing recovery without any actual harm.
The incident changed one part of the design. The idempotency key (the identifier that keeps the same event from being handled twice) was moved from the job ID to a per-event UUID (event_id). A job ID is unique only within a single DB. If DBs are duplicated, as with a sandbox and production, the same ID can show up in another environment. Job IDs are a poor fit for identifiers that cross environments.
There is one more rule about what not to put in a signal: job contents, instructions, personal information, file paths, and credentials. The worker re-reads whatever it needs from the source of truth, because anything written into a signal becomes an entry point where externally injected content can get mixed in (an injection surface).
The rest of the design is the part you implement against: the job state machine, claim and token ownership checks, the delivery order, the Reconciler, and a breakdown of what the reference implementation has actually verified versus what is only specified. That detailed contract is in the paid document linked below.
Get the complete implementation contract ($5)
This free part covered why the design exists, the five-step flow, why the DB is the source of truth, and where the pattern fits. The paid document adds the implementation contract itself, plus a clear line between what has been verified and what is only specified.
What's inside:
- The job state machine and
request_idhandling - Claim, CAS, and token: how ownership of a job is confirmed
- The no-automatic-retry policy, poison-job and
attemptsrules, and the fixed delivery order - The Reconciler's scope and the Tier A / Tier B split
- The verified end-to-end path, the list of contract items not yet implemented, and the three empirical checks
8. What kinds of work it suits, and what it doesn't
This approach is designed for work that tolerates waiting, such as "take a user's request, produce in the background, and deliver when ready." The README and SKILL.md list five uses it isn't suited for:
- Processing that a synchronous action finishes in a few seconds. It would only add a queue, a dispatcher, and a worker to maintain.
- Processing that needs low latency on the order of seconds. Polling can't meet that in principle.
- Environments where testing showed that writes outside the Space failed. The signal path can't work there.
- Anything that needs exactly-once (a guarantee that an effect happens only once) for external side effects such as payments or posts. What this approach guarantees as a contract is at-least-once delivery and effectively once-only processing through claim.
- High-frequency, high-volume jobs. The hook scans the entire signal file and seen record each time, so this becomes the first bottleneck. The checklist has a rotation procedure, but it isn't suited to uses with tens of thousands of lines at all times.
9. Wrapping up: first, test whether you can write the file
If you've read this far and want to try it in your own Space, there's a first step.
Use a small test action to check whether the Space's server code can write a file outside its own directory. An example destination is ~/hooks/state/. The entire signal path hinges on this one point. If writing fails, this approach doesn't work.
To install it, copy the repository's contents into your Muse custom-skills directory. The destination is ~/workspace/custom-skills/space_async_jobs/, where you put SKILL.md, skill.yaml, and templates/. Once placed, Muse can find the pattern through skill search. If you ask it to "add async jobs to my Space," Muse assembles the setup according to the skill. There are five templates in templates/ (action-contract.md, hook-script.sh, worker-prompt.md, reconciler-prompt.md, verification-checklist.md).
The one primary source is this repository. The README covers the overall design, SKILL.md the details, and templates/ the starting files.
https://github.com/nakamo326/muse-space-async-jobs
When you have an AI agent work in the background, the first priority isn't hardening the wake-up mechanism. It's making sure that even if a signal is lost, the record of the work remains in the DB, so the next worker to wake can find it from the source of truth. And it's making sure nothing breaks if the worker is woken twice. That is the idea this post has walked through.
Originally published in Japanese on note. This English edition was translated and edited with AI assistance; all commands and facts are unchanged from the original.
Top comments (0)