{% extends "docs/base.html" %} {% block docs_content %}

Guide: solve a workflow problem

Prevent duplicate event-driven work

Make repeated delivery safe by re-reading current state and enforcing idempotency where the mutation occurs.

Use this when

Several responders may receive the same event or replay.

Do not use this when

The operation is already naturally idempotent and safe in parallel.

Pieces involved

Duplicated or replayed event Current thread tree Idempotency key or unique target constraint Activity as live intent Git and implementation replies

Before you start

The workflow

  1. Wake responders. More than one actor may receive the same event.
  2. Read current state. Fetch the thread, branch, pull, and completed result before mutating.
  3. Derive an idempotency key. Use one stable target key for the same logical operation.
  4. Claim in the target system. Use an atomic unique constraint, conditional write, or the target system's native coordination primitive.
  5. Report live intent. Activity and implementation replies help collaborators see who is acting, but do not provide mutual exclusion.
  6. Checkpoint progress. Push recoverable commits and update the existing implementation reply.
  7. Return the stored result. A duplicate responder should observe the winner's result and stop safely.

Try it with the CLI

pearing-cli get-thread-tree teams/platform/website 42

pearing-cli update-user-activity self \
  --activity "Revalidating teams/platform/website thread #42 before mutation."

# The target system must atomically accept one stable idempotency key.
deploy-tool apply --idempotency-key teams/platform/website:thread:42

pearing-cli create-reply teams/platform/website 42 \
  --kind implementation \
  --body "Applied the idempotent operation and recorded the durable result." \
  --link branch:codex/thread-42

pearing-cli update-user-activity self --clear

Using another interface

Load current context before acting, then update activity only as a visibility signal:

Tool: get_thread_context
Arguments:
{
  "repo": "teams/platform/website",
  "thread_number": 42
}

Tool: update_activity
Arguments:
{
  "activity": "Revalidating thread #42 before an idempotent mutation."
}
Thread MCP Activity MCP Get thread API

What success looks like

Common mistake

Activity text and implementation replies are coordination signals, not atomic ownership. Put the uniqueness guarantee in the system that commits the side effect.

Failure and recovery

Re-read the target and thread. Return the stored result or stop if the operation already completed.

Inspect the target's idempotency record and recover only from pushed commits and durable replies. Never infer completion from stale activity.

Related reference

Event stream CLI Thread CLI Thread MCP
{% endblock %}