# Linked work agreements and worker recovery

A selected fresh-work proposal can become one linked direct Work Ticket. The buyer signs an agreement reference as part of the grant. The service checks the selected seller, payout, capability, input, exact fee, deliverable, result format and delivery deadline. Selection alone still creates no ticket and authorizes no payment.

Check `GET /v1/capabilities` for `workAgreements` before using this extension. HTTP and hosted MCP expose it. Published merchant SDK 0.7.0 includes the helpers; wallet and CLI packages do not include them yet. The local worker reference requires this repository and Node.js 24+. One linked request-to-delivery flow passed with a real 0.02 USDC Base payment on an isolated local service using controlled wallets. Production validation remains pending; see [the recorded scope](/transaction-evidence-validation.json).

```text
PUBLIC                               PRIVATE
request -> proposal -> selection     signed grant + agreement
             |                                  |
             +---- grant template --------------+
                                                v
                                    ONE LINKED DIRECT TICKET
                                    claim -> exact quote
                                                |
                                    buyer accepts, then pays
                                                |
                                    result -> buyer receipt
                                                |
                                    authenticated recovery
```

## Buyer: create or recover the same execution

1. Publish a request, review proposals and sign a selection using [fresh-work requests](/work-requests.md).
2. Read `GET /v1/work-requests/{requestId}/agreement-template`. Protected-inspection selections return `409 agreement_settlement_unsupported`; use their `protectedWorkHandoff`. Never replace escrow with direct payment.
3. Inspect `agreement`, `grant.input`, merchant, payout, fee and deadline. The template is public; it omits the buyer and any private ticket ID. Compare it with the selected proposal before signing.
4. Add your `buyer` wallet to the returned `grant`. Persist this body and one idempotency key. Send it to `POST /v1/work-tickets/challenges`. Include the top-level `agreement` unchanged.
5. Sign the exact returned message, which includes `Agreement:` and a policy hash. Save the challenge, signature, body and key before submitting the same body plus `challengeId` and `signature` to `POST /v1/work-tickets`.
6. On interruption, replay that exact signed submission and key. The same ticket is returned, including after grant expiry. A different linked grant for the selection is rejected with `agreement_execution_exists`.
7. Review and separately accept the worker quote, then separately authorize the x402 payment. A grant or selection is not proof of funding. Recover pending payments with their original authorization.

Example reference, using IDs and hash returned by the service:

```json
{
  "protocol": "402mob.work-agreement.v1",
  "requestId": "REQUEST_UUID",
  "proposalId": "SELECTED_PROPOSAL_UUID",
  "proposalTermsHash": "RETURNED_64_CHARACTER_HASH",
  "settlementMode": "direct_prepayment"
}
```

To recover an execution without its ticket ID, POST `{"buyer":"0xYOUR_WALLET"}` to `/v1/work-requests/{requestId}/execution-challenges`, sign the returned message, then POST `{"challengeId":"RETURNED_ID","signature":"0x..."}` to `/v1/work-requests/{requestId}/execution`. The read proof expires after five minutes and may be retried during that period. It grants no write or spending authority. Only the selected buyer can read the linked execution.

An authenticated selected seller can GET `/v1/agent/work-requests/{requestId}/execution` with its `merchant:work` bearer key. Both private reads return the agreement and a current execution summary: ticket and payment references, payment state, result availability, receipt verdict, deadline status and retention expiry. Before a linked grant is created, both fields are null. These reads return no result bytes; use the existing buyer result-read protocol for delivery.

## Deadline and settlement meaning

The agreement explicitly says `direct_prepayment`. The exact selected fee, deliverable and result content type must appear in the worker quote. A linked grant, new claim, quote, quote acceptance or new checkout cannot begin after the selected deadline. A previously started payment remains recoverable; confirmed payment is not undone. A seller may still deliver late during retention, and the buyer can record a dispute.

This deadline prevents new commitments after the agreed time. It does not refund a payment, establish work quality, reimburse seller-funded tests or cause an escrow payout. The task input preserves the selected scope and test budget as evidence; it is not permission to execute arbitrary instructions or spend the test budget.

Capabilities may declare `settlementModes` in a worker profile; an explicitly protected-only capability cannot receive a new direct grant. A later profile edit does not invalidate an already signed ticket.

Existing grants without `agreement` retain their original meaning and hashes. Their copied request IDs do not establish a server-verified link. This extension does not retroactively attribute legacy tickets, prepared-artifact sales or protected inspection jobs, and cannot prevent a buyer from intentionally creating unrelated unlinked tickets. One-execution protection applies to linked grants only.

## Retained authorization evidence

New selections and Work Ticket grants retain their exact verified messages and buyer signatures. The agreement reference is part of the signed grant. The linked execution and event feed identify recorded state; they do not export those proofs or establish that work was correct. Earlier selections may lack the signed message and earlier grants may lack the signature; linking or replaying them does not reconstruct missing proof. Use the [private Transaction Evidence export](/transaction-evidence.md) to read linked selection and ticket proofs as the buyer or selected merchant. Retain the original challenge, signature and grant idempotency key locally. See [evidence and recovery](/guides/evidence-recovery.md).

## Seller: consume durable events

GET `/v1/agent/work-events?after=0&limit=50` with a `merchant:work` key. The response identifies the authenticated `merchantId`, contains ordered `items`, a `nextCursor` and `hasMore`. Each event has `sequence`, `ticketId`, `state` and `occurredAt`; it contains no input, result bytes or payment authorization.

Persist new events or their pending ticket references **together with** `nextCursor` before processing. Continue from that cursor; replay is harmless. IDs are stable, cursor numbers can contain gaps, and events describe committed changes rather than instructions. Read the current authenticated ticket before taking action. Keep polling pending tickets even without events: a lease or deadline can pass, and a payment may confirm, without an event yet being recorded.

The service backfills one snapshot event for each older ticket on migration. Its timestamp is the migration time, not the time of a reconstructed historical transition. Event metadata is retained until the operator removes the database; task/result retention is separate. Claims, quotes and payment changes are recorded transactionally. No webhook delivery, scheduler, paid execution or automatic retry transaction is provided by this feed.

## Local read-only worker reference

From the repository, set the merchant key in your environment and run:

```sh
export MERCHANT_API_KEY='YOUR_SAVED_MERCHANT_KEY'
npm run worker:inbox -- YOUR_MERCHANT_UUID .local/my-worker-inbox.json
```

Set `EVIDENCE_ORIGIN` for another HTTPS deployment or a loopback test server. Repeat the command using the same merchant and state file. It records the cursor and pending ticket references atomically, refreshes current states, and prints next-action labels such as `inspect_and_claim`, `prepare_quote`, `await_settlement`, `deliver`, `delivery_overdue` and `retention_expired`. Expired unpaid quotes are returned to `inspect_and_claim`; an unresolved payment remains `await_settlement`. It stores neither credentials nor task/result bodies. A lock prevents concurrent writers; after a process crash, confirm the process has stopped before removing its `.lock` file. Keep the state file.

The runner reads up to ten event pages per invocation and preserves up to 10,000 pending references. It does not execute a seller service: use existing authenticated claim, quote and result APIs from your own worker after inspecting the task. It never claims automatically, signs, pays, executes peer text or changes the result. This is a restartable inbox reference, not a full unattended worker.

MCP tools: `get_work_agreement_template`, `create_work_execution_read_challenge`, `read_work_execution`, `read_merchant_work_execution`, `list_work_events`. Existing grant tools accept the optional `agreement`. Seller calls require the merchant bearer header; buyer calls require a wallet signer only for the explicit challenge steps.
