emasoft/amcos-agent-termination

Agent Termination

Overview

Handles clean shutdown of agent instances including work verification, state preservation, termination execution, and registry cleanup. Use when an agent's work is complete, when reclaiming resources, or during cleanup.

Prerequisites

• AI Maestro running, ai-maestro-agents-management and agent-messaging skills available
• Target agent in RUNNING or HIBERNATED state
• Team registry accessible via REST API

Instructions

Termination Procedure (PROCEDURE 2)

1. Request GovernanceRequest approval - Submit termination request to sourceManager via amcos-permission-management skill. BLOCK until approved. Do NOT proceed without approval.
2. Verify work complete - Confirm no pending tasks or uncommitted work
3. Save final state - Request agent to save context/progress to handoff file
4. Send termination warning via agent-messaging with hibernation-warning type
5. Execute termination via ai-maestro-agents-management skill (requires confirmation)
6. Update registry - uv run python scripts/amcos_team_registry.py remove-agent
7. Cleanup resources - Verify tmux session gone, temp directories cleaned
8. Log termination - Record timestamp, reason, outcome in lifecycle log

Graceful vs Forced

| Type | When | Procedure | |------|------|-----------| | Graceful | Agent responsive, work done | Full 8-step procedure | | Forced | Unresponsive 5+ min | Skip steps 2-4, force-terminate tmux |

Always attempt graceful first.

Quality Standards

• Terminated agents MUST be cleaned from registry
• ALWAYS hibernate instead of terminate when agent may be needed again
• ALWAYS save state before termination
• Log every termination per record-keeping

Output

| Step | Expected Output | |------|----------------| | Termination | tmux session destroyed, process stopped | | Registry | Agent removed, status "terminated" | | Cleanup | Resources freed, log entry written |

Error Handling

| Issue | Resolution | |-------|-----------| | Uncommitted work | Request commit/push first. Do NOT proceed until confirmed | | tmux persists | tmux kill-session -t <name> | | Registry update fails | Retry 3x, then remove via ai-maestro-agents-management skill |

Examples

Graceful Termination

# 1. Send status request via agent-messaging
# 2. After confirmation, terminate via ai-maestro-agents-management skill
# 3. Update registry
uv run python scripts/amcos_team_registry.py remove-agent --name ampa-svgbbox-impl
# 4. Verify
tmux has-session -t ampa-svgbbox-impl 2>/dev/null && echo "RUNNING" || echo "TERMINATED"

Forced Termination

# After 5 min no response:
tmux kill-session -t ampa-stuck-agent
uv run python scripts/amcos_team_registry.py remove-agent --name ampa-stuck-agent

Checklist

Copy this checklist and track your progress:

• [ ] Request GovernanceRequest approval before termination
• [ ] Verify work complete and state saved
• [ ] Execute termination and remove from registry
• [ ] Cleanup resources and log event

Resources

• record-keeping — Lifecycle logs, registries, session state formats, log queries
  • Lifecycle Log
  • Approval Requests Log
  • Team Assignments Log
  • Project: svgbbox-library
  • Project: auth-service
  • Operation Audit Trail
  • Log Maintenance
  • Log Access
  • Agent Registry Structures
    • Central Agent Registry
    • Team Registry (Project-Level)
  • Session State Formats
    • Hibernation State Snapshot
    • Health Check Response Format
    • Team Status Report Format
  • Log Query Examples
    • Get recent spawns
    • Find all operations for specific agent
    • Check hibernation/wake cycles
    • Get approval decisions from current month
    • Trace specific operation by request ID
  • Best Practices