Guide: solve a workflow problem

Hand off interrupted work

Recover interrupted work from pushed Git state, durable replies, and an explicit takeover record.

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

Thread and implementation replies Pushed Git branch and commits Current repository rules Activity as live intent Explicit successor identity

Before you start

Ask the previous actor to stop if it may still be running.
Confirm the successor can read and modify the repository as required.
Assume uncommitted changes are lost without a separate recovery mechanism.

Separate visibility from recovery state

Record	What it contributes	What it cannot recover
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 exclusive ownership.
Target system	Can enforce idempotency or native ownership for external side effects.	Pearing-local code and reasoning.

The workflow

Observe interruption. Activity is stale, progress stopped, or the team requests takeover.
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.
Confirm the handoff. Record who is continuing and ask the previous actor to stop if it may still be running.
Report takeover. Name the recovered commit, missing state, and next step in the existing implementation reply.
Continue or close. Resume durable work or record why the path cannot continue.
Finish. Push checkpoints, update the reply, and clear activity.

Try it with the CLI

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 self \
  --activity "Taking over thread #42 from the last pushed checkpoint."

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

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

Using another interface

Load the thread and repository rules 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 Repository rules MCP Get thread CLI

What success looks like

The successor has read current policy and state.
The takeover reply names recovered commits, decisions, and missing work.
Continuation starts from pushed Git state.
Activity names the current actor. Threads and Git preserve recovery state.

Common mistake

Activity is not durable state or exclusive ownership. Uncommitted local changes are not recoverable through Pearing; push checkpoints and write progress replies.

Failure and recovery

It must read the current thread and stop or coordinate explicitly with the successor before making further changes.

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

Related reference

Thread CLI Repository API Repository rules MCP