# Session Freeze Protocol

Session freeze is how long Cursor agent work survives context exhaustion, window changes, and human interruptions.

## When To Freeze

Freeze before:

- A chat window approaches context exhaustion.
- A role finishes a phase or hands work to another role.
- The user reports confusion or asks for a status reset.
- A significant incident occurs, such as sync failure, credential friction, or a blocked safety gate.
- A role-misdirection incident occurs or a prompt may have been sent to the wrong Cursor window.

## Required Freeze Outputs

Update:

- `USER_STATUS.md`: human-facing current state and single next action.
- Relevant `handoff/*.md`: role-specific state and next owner.
- Relevant `tasks/*.md`: machine-readable task status.
- `knowledge/LESSONS_LEARNED.md`: reusable insight from the session.

Create archive note when useful:

```text
archive/YYYYMMDD-short-topic.md
```

## Freeze Template

```text
Current phase:
Completed:
Blocked:
Safety constraints:
Next owner:
Single next action:
Files updated:
Resume prompt:
```

## Resume Prompt

Every freeze should leave a prompt that a new session can use:

```text
You are resuming the OpenClaw COACH/ORCHESTRATOR workflow.
Read USER_STATUS.md, AGENT_BOARD.md, relevant handoff files, sync-state/README.md, and knowledge/LESSONS_LEARNED.md.
Do not start mutation work unless USER_STATUS.md and AGENT_BOARD.md both allow it.
```

## Role-Misdirection Freeze

If a prompt was sent to the wrong role or wrong Cursor window:

- Stop execution immediately.
- Update `USER_STATUS.md` with a paused status and one safe next action.
- Record the incident in the active role handoff and, if needed, `handoff/CORRECTION.md`.
- Follow `docs/ROLE_MISDIRECTION_RECOVERY.md`.
- Do not resume mutation or authorization work until ORCHESTRATOR has adopted or corrected the affected control-plane files.