cao-session-liveness

Verify CAO session liveness by corroborating status values against terminal output.

1.2k|249|Updated Jul 29, 2025
One-click install
npx skills add https://github.com/awslabs/cli-agent-orchestrator --skill cao-session-liveness
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: cao-session-liveness
Source: https://github.com/awslabs/cli-agent-orchestrator/tree/main/skills/cao-session-liveness
Command: npx skills add https://github.com/awslabs/cli-agent-orchestrator --skill cao-session-liveness

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

CAO providers infer agent state by pattern-matching the rendered terminal screen, so a crashed or stalled CLI can still report an idle or processing status. This Skill prevents reporting progress on sessions that are already dead by requiring output-based corroboration before any status claim.

Core Features & Use Cases

  • Two-Signal Verification: Always cross-check the reported status against the output tail, and trust the output when the two disagree.
  • Dead-Session Detection: Recognize concrete failure signatures such as shell prompts, CLI usage errors, API errors, and session-ended markers regardless of reported status.
  • Provider Reliability Guidance: Interpret detection quirks for kiro_cli, hermes, opencode_cli, claude_code, and codex, and verify a provider with a throwaway session before depending on it.
  • Use Case: A send to a worker session times out and the status reads idle. Instead of reporting completion, you read the output tail, find a bare shell prompt, and correctly report the session as dead rather than finished.

Quick Start

Check whether my CAO session named build-worker is actually alive by comparing its status with its recent output before reporting progress.

Frequently Asked Questions about cao-session-liveness

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if a CAO session is still alive?

Read the session status with get_terminal_status or cao session status, then read the output tail and compare the two. If they disagree, trust the output; an idle status with a shell prompt in the output means the CLI exited and the session is dead.

Why does a CAO session show idle when the agent already exited?

CAO infers agent state by pattern-matching the rendered terminal screen, with no structured protocol to the provider CLI. A crashed or exited provider can leave a screen that still matches an idle or processing pattern, so status alone is unreliable.

What should I do when a CAO send times out?

Treat a timeout as the agent still working, not as a failure. Never re-send the task, since the original may still be running and a duplicate risks conflicting work; poll again later using the two-signal rule.

Does a missing worker terminal mean a handoff was fabricated?

No. A blocking handoff tears down its worker when it returns, so querying that terminal later legitimately returns not-found. Confirm the delegation from the conductor's own transcript showing the handoff tool call and its returned output.

Which CAO providers have known detection quirks?

kiro_cli depends on version-specific prompt and separator patterns, hermes uses an idle timer that custom themes can break, and opencode_cli keeps roughly one viewport of scrollback so long responses can fail extraction. claude_code and codex are generally stable headless.