ccb-comm-reply-recover

name	ccb-comm-reply-recover
description	Diagnose and recover CCB communication and reply delivery stalls. Use when a user reports a missing CCB_REPLY, stuck ask, agent stuck busy/delivering, queued work behind an active job, cancelled/incomplete reply, empty artifact, chain not continuing, rejected active-turn followup, duplicate retry after success, or a CCB mailbox/communication backend that appears stuck.

CCB Comm Reply Recover

Overview

Use this skill for user-visible "I did not receive the reply" incidents. It combines message lineage repair with mailbox and provider-pane evidence, then hands off to runtime recovery only when the chain evidence proves the provider process or pane must be replaced.

Mutations must go through CCB control-plane commands. Do not directly edit mailbox, lifecycle, lease, runtime, provider-session, artifact, or tmux authority files.

Core Workflow

1. Identify the target from the user's evidence:
   • job_id, message_id, attempt_id, reply_id, inbound event id, or artifact path when provided.
   • agent name when the user only says a target is stuck.
   • ccb queue --detail all when neither id nor agent is clear.
2. Trace lineage first:
   • ccb trace <id>
   • record message, attempt, reply, event, chain, and job states.
   • read the full artifact file before acting when a request or reply is artifact-backed.
3. Inspect mailbox head-of-line state:
   • ccb queue --detail <agent>
   • ccb pend --inbox --detail <agent>
   • if the requested job is queued behind an active event, trace the active job before touching the queued job.
4. Cross-check runtime evidence when a job is running or delivering longer than expected:
   • ccb ps
   • ccb ping <agent>
   • ccb doctor logs <agent> when provider/pane failure is plausible.
   • read-only tmux pane capture only from the socket and pane id reported by ccb ps, and only as evidence.
5. Classify the incident, choose the least disruptive repair, then re-run trace and queue checks.

Incident Classes

• normal_running: the active job is visible in the provider pane and making progress. Report that it is running; do not restart or duplicate-submit.
• head_of_line_blocked: an active job is running/delivering, later jobs are queued behind it, and pane/log evidence shows stale, dead, mismatched, or non-progressing provider state.
• queued_behind_active: the user's job is not lost; it is queued behind an active event. Repair the active event only if evidence proves it is blocked.
• provider_pane_stale: CCB reports the runtime healthy, but pane text/logs show an old prompt, a dead/update prompt, or a request that does not match the active lineage.
• empty_cancel_artifact_expected: trace shows terminal cancelled with cancel_info, and the empty artifact came from an intentional cancel.
• empty_bad_artifact: a completed, failed, or required artifact-backed reply is absent, zero bytes, truncated, or unreadable without a valid cancel reason.
• duplicate_retry_after_success: a later retry or resubmission of the same work is still queued/running after another attempt already completed and the user received the needed reply.
• chain_or_ack_stalled: a reply exists and is acceptable, but chain or inbox progress did not advance.
• followup_not_injected: ccb followup returned rejected, too_late, or terminal; the active request was not corrected.

Repair Rules

• If trace shows the blocking job is still in flight, run ccb cancel <job_id> first when the user supplied maintenance intent. If cancel fails or reports a blocker, stop.
• Prefer ccb repair retry <job_id|attempt_id> when the same work should run again and the original lineage remains valid.
• Prefer ccb repair resubmit <message_id> when the old execution lineage is stale, context-corrupted, semantically wrong, or no longer suitable.
• Use ccb repair ack <agent_name> [inbound_event_id] only when the reply is already accepted and progress state is wrong.
• Cancel duplicate_retry_after_success jobs rather than letting an agent run the same review or repair twice.
• Treat only followup_status: injected as success. For any other terminal status, cancel and resubmit the complete corrected request when still needed; do not queue the correction as unrelated work.
• Hand off to ccb-self-recover for ccb restart <agent> only after chain repair clears or cancels active work and the target remains stale, dead, or unusable. Restart is not the first repair for a communication stall.

Verification

After every repair:

• ccb trace <old_job_or_message> proves the old path is terminal, completed, or intentionally cancelled.
• ccb queue --detail <agent> and ccb pend --inbox --detail <agent> show no unexpected active head-of-line blockage.
• the desired job is completed, or a fresh valid job is queued/running with no duplicate path.
• artifact-backed replies are read from the full artifact file when needed.
• report intentional cancelled empty artifacts as expected maintenance output, not as missing user replies.

Example Pattern

In a typical stall incident, the user reported that no specialist-agent reply arrived. Trace showed one old active job stuck in running/delivering, while later asks were queued behind it. Provider logs showed a host update and pane death, but ccb ps still showed a bound pane. The correct repair was:

1. cancel the stale active job;
2. verify the next queued job entered the provider pane and was progressing;
3. avoid restart while valid work was running;
4. accept the completed new reply;
5. cancel the duplicate old retry that remained after success;
6. verify the target mailbox returned to idle.

Red Lines

• Do not restart, clear, reload, or kill before tracing the message lineage.
• Do not submit a second concurrent path for the same work while the original path is still active unless the user explicitly retargets or duplicates the task.
• Do not treat observer snapshots as terminal authority; use ccb trace.
• Do not infer from artifact preview text when the full artifact is required.
• Do not mutate tmux directly or write CCB runtime authority files.
• Do not read provider secrets, credentials, API keys, or unrelated private provider state.