emasoft/amcos-agent-hibernation

Agent Hibernation and Wake

Overview

Suspends idle agents and resumes them when needed. Preserves full state so agents resume where they left off.

Prerequisites

• AI Maestro running with ai-maestro-agents-management and agent-messaging skills
• Agent in RUNNING (hibernate) or HIBERNATED (wake) state
• Team registry accessible

Instructions

Copy this checklist and track your progress:

• [ ] Request GovernanceRequest approval from sourceManager via amcos-permission-management
• [ ] Confirm agent idle with no active work
• [ ] Send hibernation warning via agent-messaging skill
• [ ] Request state capture and wait for confirmation
• [ ] Execute hibernation via ai-maestro-agents-management skill
• [ ] Update registry status to hibernated and log event

Agent States

SPAWNING -> RUNNING <-> HIBERNATED
              |
              v
           TERMINATED

Hibernate Procedure (PROCEDURE 3)

1. Request approval via amcos-permission-management. BLOCK until approved.
2. Confirm idle - Verify no active work
3. Send warning via agent-messaging (type: hibernation-warning)
4. Request state capture - Agent saves context/handoff
5. Execute via ai-maestro-agents-management
6. Update registry - uv run python scripts/amcos_team_registry.py update-status --name <agent> --status hibernated
7. Log event

Wake Procedure

1. Verify hibernated - Check registry
2. Check resources - Confirm slot available (max 5)
3. Execute wake via ai-maestro-agents-management (--continue)
4. Verify responsive - Expect response within 30s
5. Restore state - Agent reads saved handoff/context
6. Update registry - Mark "running"
7. Log event

Resource Limits

| Resource | Limit | Action | |----------|-------|--------| | Concurrent agents | 5 | Queue/hibernate oldest idle | | Memory per agent | 2GB | Terminate/hibernate | | Idle timeout | 30 min | Hibernate |

Remote host ops require GovernanceRequest; state replicated via GovernanceSyncMessage.

Output

| Operation | Expected Output | |-----------|----------------| | Hibernate | State saved, session suspended, registry "hibernated" | | Wake | Session resumed, agent responsive, registry "running" |

Error Handling

| Issue | Resolution | |-------|-----------| | Active work during hibernate | Wait for completion or checkpoint | | State capture fails | Retry once, warn (state loss risk) | | Wake fails | Force-wake, respawn if needed (see 3.7) | | Resource limit on wake | Hibernate another idle agent first | | Unresponsive after wake | Wait 60s, retry, then terminate/respawn |

Examples

Hibernate an Idle Agent

# Warn -> wait 2min -> hibernate -> update registry
uv run python scripts/amcos_team_registry.py update-status \
  --name ampa-svgbbox-impl --status hibernated

Wake a Hibernated Agent

# Wake (--continue) -> notify -> update registry
uv run python scripts/amcos_team_registry.py update-status \
  --name ampa-svgbbox-impl --status running

Checklist

Copy this checklist and track your progress:

• [ ] Request GovernanceRequest approval before hibernate/wake
• [ ] Confirm agent idle (hibernate) or hibernated (wake)
• [ ] Execute via ai-maestro-agents-management skill
• [ ] Update registry status and log event

Resources

• hibernation-procedures — Hibernation and wake procedures, state snapshot format, troubleshooting
  • 3.1 What is agent hibernation - Understanding state suspension
  • 3.2 When to hibernate agents - Hibernation triggers
    • 3.2.1 Idle timeout - No activity for threshold period
    • 3.2.2 Resource pressure - System capacity constrained
    • 3.2.3 Scheduled pause - Planned inactivity window
  • 3.3 Hibernation procedure - Step-by-step suspension
    • 3.3.1 Idle confirmation - Verifying no active work
    • 3.3.2 State capture - Serializing agent state
    • 3.3.3 State persistence - Writing to storage
    • 3.3.4 Resource release - Freeing memory and connections
    • 3.3.5 Registry update - Marking as hibernated
  • 3.4 State snapshot format - Hibernation state structure
  • 3.5 Wake procedure - Resuming hibernated agents
    • 3.5.1 State retrieval - Loading from storage
    • 3.5.2 State restoration - Deserializing agent state
    • 3.5.3 Resource reacquisition - Reconnecting services
    • 3.5.4 Registry update - Marking as running
    • 3.5.5 Work resumption - Continuing interrupted tasks
  • 3.6 Examples - Hibernation and wake scenarios
  • 3.7 Troubleshooting - Hibernation issues