Workflow: Escrow Lifecycle

When Sentinel issues a HELD verdict, the action is not executed or discarded -- it is placed in escrow. A human must decide what happens next. This page covers the full lifecycle of an escrow item from creation to resolution.

Overview

Escrow is TheWARDN's mechanism for human-in-the-loop governance. It ensures that uncertain or sensitive actions receive human judgment before executing, without losing the action context.

State Diagram

          Action arrives
               |
               v
      Sentinel returns HELD
               |
               v
    +---------------------+
    |       HELD          |
    | (escrow created)    |
    +---------------------+
       /       |       \
      /        |        \
     v         v         v
+---------+ +--------+ +-----------+
| RELEASED| | KILLED | | TIMED_OUT |
| (human  | | (human | | (timeout  |
| approves)| | rejects)| | expires) |
+---------+ +--------+ +-----------+
     |         |            |
     v         v            v
  Action    Action        Action
  executes  dies          dies
     |         |            |
     v         v            v
+--------------------------------+
|   Audit record sealed          |
|   (outcome + hash chain)       |
+--------------------------------+

Step-by-Step Lifecycle

1. Escrow Creation

When Sentinel evaluates an action and determines it should be HELD, an escrow record is created:

{
  "escrow_id": "esc_def456",
  "agent_id": "agent_abc123",
  "action": "send_email",
  "parameters": { "to": "customer@example.com", "subject": "Follow-up" },
  "verdict": "HELD",
  "fired_policies": ["policy_confidence_floor"],
  "reason": "Confidence score 0.62 below floor 0.70",
  "created_at": "2026-04-10T14:32:01.000Z",
  "timeout_at": "2026-04-10T14:42:01.000Z",
  "status": "PENDING"
}

The action payload is frozen in its entirety. Nothing about the action can change while in escrow.

2. Timeout Configuration

Escrow timeouts are tier-based by default:

Tier	Default Timeout	Description
A-tier	No escrow	A-tier actions are either CLEARED or BLOCKED, never HELD
B-tier	10 minutes	Standard operational actions
C-tier	30 minutes	Higher-stakes actions that may need more review time

TIP

Timeout values are configurable per-policy. You can set custom timeouts in your CHAM policy definitions to match your operational needs.

3. Resolution Outcomes

There are exactly three ways an escrow item can be resolved:

RELEASED (Human Approves)

The reviewer examines the action and decides it is safe to execute.

# Via API
curl -X POST https://api.thewardn.ai/escrow/esc_def456/release \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision_note": "Reviewed email content, no PII present. Safe to send."}'

What happens:

• The action is executed as originally submitted
• The escrow status changes to RELEASED
• A decision acknowledgment is recorded with the reviewer's identity
• The audit record is sealed with the outcome

KILLED (Human Rejects)

The reviewer examines the action and decides it should not execute.

# Via API
curl -X POST https://api.thewardn.ai/escrow/esc_def456/kill \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision_note": "Email contains customer PII in subject line. Blocked."}'

What happens:

• The action is permanently discarded
• The escrow status changes to KILLED
• A decision acknowledgment is recorded
• The audit record is sealed with the outcome
• Optionally, a violation record can be created if the reviewer deems it warranted

TIMED_OUT (Timeout Expires)

No human acts on the escrow item before the timeout expires.

What happens:

• The action is permanently discarded
• The escrow status changes to TIMED_OUT
• The audit record is sealed with the timeout outcome
• The agent is notified (if webhook configured)

WARNING

Timeout always kills the action. TheWARDN is fail-closed by design -- if no human reviews the action in time, the action does not execute. Silence is never approval.

4. Audit Trail

Every escrow outcome is recorded in the immutable audit trail:

{
  "audit_id": "aud_resolution_001",
  "escrow_id": "esc_def456",
  "outcome": "RELEASED",
  "decided_by": "user_greg@thewardn.ai",
  "decision_note": "Reviewed email content, no PII present. Safe to send.",
  "decided_at": "2026-04-10T14:35:22.000Z",
  "hash": "b4c5d6e7f8a9...",
  "prev_hash": "a3f2b1c4d5e6..."
}

The audit record includes who made the decision, when, and why. This creates a complete chain of custody for every governed action.

Managing Escrow via Console

Viewing Pending Escrow Items

The console displays all pending escrow items in the Escrow Queue panel. Each item shows:

• Agent name and ID
• Action type and summary
• Fired policies and reasons
• Time remaining before timeout
• Confidence scores

Releasing or Killing from Console

Click on any escrow item to expand its details. You will see the full action payload, all fired policies, and the agent's confidence scores. Two buttons are available:

• Release -- Approve the action. You must provide a decision note.
• Kill -- Reject the action. You must provide a decision note.

TIP

Decision notes are required. They become part of the immutable audit trail and are essential for compliance reporting.

Managing Escrow via API

List Pending Escrow Items

curl https://api.thewardn.ai/escrow?status=PENDING \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a Specific Escrow Item

curl https://api.thewardn.ai/escrow/esc_def456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Poll for Resolution (Agent-Side)

Agents that send /govern requests and receive a HELD verdict can poll for the outcome:

import time
import requests

def wait_for_escrow(escrow_id, api_key, poll_interval=5):
    """Poll escrow status until resolved."""
    url = f"https://api.thewardn.ai/escrow/{escrow_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        resp = requests.get(url, headers=headers)
        data = resp.json()

        if data["status"] != "PENDING":
            return data  # RELEASED, KILLED, or TIMED_OUT

        time.sleep(poll_interval)

Escrow Best Practices

1. Set appropriate timeouts -- Too short and reviewers miss items. Too long and actions queue up.
2. Monitor your escrow queue -- A growing queue of TIMED_OUT items means your review process needs attention.
3. Always provide decision notes -- These are invaluable during audits and incident investigations.
4. Use AUDIT_ONLY mode first -- Before switching to ENFORCED, run in AUDIT_ONLY to understand your escrow volume.
5. Configure webhook notifications -- Get alerted when new escrow items arrive instead of polling.

Next Steps

• Govern an Action -- The full governance flow that creates escrow items
• Policy Evaluation -- Understanding which policies trigger HELD verdicts
• Incident Response -- Handling violations that bypass escrow