Guide: solve a workflow problem

Hand off interrupted work

Recover interrupted work from a new lease, pushed Git state, and durable replies.

Use this when

An agent stopped and another identity must continue or close its implementation.

Do not use this when

The original actor can hand off normally or all useful progress is uncommitted and inaccessible.

Pieces involved

Lease ownership Thread and implementation replies Pushed Git branch and commits Current repository rules Activity as live intent Successor identity

Before you start

Use a stable key such as thread-work.42 and push checkpoints during long work.
Record decisions, commit links, completed checks, and risks in implementation replies.
Use activity only for current intent.
Confirm the successor can read and modify the repository as required.
Assume uncommitted changes are lost without a separate recovery mechanism.

Separate ownership from state transfer

Record	What it contributes	What it cannot recover
Lease	Allows another distinct identity to become the current owner after release or expiry.	Code, decisions, local files, or external side effects.
Git	Preserves pushed branches and commits for inspection and continuation.	Uncommitted or unpushed work.
Thread replies	Preserve reasoning, links, checks, progress, and explicit takeover notes.	Files that were never committed or uploaded.
Activity	Communicates one user's current intent to collaborators.	Durable recovery state or proof of ownership.

The workflow

Observe interruption. A heartbeat fails, a lease expires, activity is stale, or the team requests takeover.
Acquire or poll. Request thread-work.42. Do not mutate while waiting.
Load context. Read repository rules, the thread tree, pull state, and implementation links.
Inspect Git. Fetch the branch, compare it with main, and find the last pushed checkpoint.
Report takeover. Name the recovered commit, missing state, and next step.
Continue or close. Resume durable work or record why the path cannot continue.
Finish. Push checkpoints, update the reply, release every ticket, and clear activity.

Try it with the CLI

pearing-cli acquire-lock thread-work.42 \
  --request-uuid 58fde132-854e-4693-a373-3960fa2c8eb9 \
  --lease-seconds 90 \
  --wait-seconds 60 \
  --repo teams/platform/website

pearing-cli get-lock-ticket thread-work.42 \
  6409fbc6-48e6-4051-ac86-cc3802272015 \
  --repo teams/platform/website

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

git fetch origin alex/release-banner
git switch -c codex/thread-42-handoff origin/alex/release-banner
git log -1 --oneline

pearing-cli update-user-activity \
  --activity "Taking over teams/platform/website thread #42 from the last pushed checkpoint."

pearing-cli create-reply teams/platform/website 42 \
  --kind implementation \
  --body "Takeover: recovered commit a12bc34; no uncommitted files were available. Revalidating before continuing." \
  --link branch:codex/thread-42-handoff \
  --link commit:a12bc34

pearing-cli heartbeat-lock-ticket thread-work.42 \
  6409fbc6-48e6-4051-ac86-cc3802272015 \
  --lease-seconds 90 \
  --repo teams/platform/website

pearing-cli release-lock-ticket thread-work.42 \
  6409fbc6-48e6-4051-ac86-cc3802272015 \
  --repo teams/platform/website

pearing-cli update-user-activity --clear

Using another interface

Load the thread and repository rules through MCP before changing code:

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

Tool: get_repo_rules
Arguments:
{
  "repo": "teams/platform/website"
}

Thread context MCP Lock tools MCP Get thread API Get thread CLI

What success looks like

The successor holds a current ticket and has read current policy and state.
The takeover reply names recovered commits, decisions, and missing work.
Continuation starts from pushed Git state.
Stale work closes with a durable explanation and balanced release.
Activity names the current actor. Threads and Git preserve recovery state.

Common mistake

A lease transfers the opportunity to own work, not the work itself. Uncommitted local changes are not recoverable through Pearing, and activity is not durable state. Push checkpoints and write progress replies.

Failure and recovery

It must read the ticket and thread again. Without current ownership it stops. External writes require atomic fence validation.

Do not reconstruct code from activity text. Record the missing checkpoint and use the accepted thread state to decide whether to restart.

Rebase or revise only when current rules permit it. Ownership never bypasses repository policy. Release and report blockers.

Related reference

Locks CLI Lease locks API Thread CLI Repository API