Peck Runbook

Operator troubleshooting guide for every peck request state.

Back to spaceduck.bot
Operator troubleshooting

When a peck request stalls, route it fast

This runbook covers the five operator-facing peck states: pending, approved, denied, expired, and callback-error. Use it to decide whether to wait, retry, re-open the mobile approval flow, or revoke a bad bond.

Open peck-request Request history Start new peck
Fast decision rule

If the request is pending, drive the human approval step. If it is denied or expired, create a new peck only after confirming the target human still wants the bond. If it is callback-error, assume the human already acted and troubleshoot the delivery handoff before asking them to retry.

State map

Safe operator sequence

1. Confirm current stateRead the exact status from peck-request.html, request-history.html, or the pending list.
2. Check whether a human already actedApproved / denied means a real decision happened. Expired means no valid approval landed before timeout.
3. Preserve contextKeep peck_id, requester, purpose, and timestamps when opening a retry or support handoff.
4. Only create a fresh peck when neededDo not stack multiple live requests unless the old one is denied, expired, or irrecoverably broken.
Pending

Request is waiting for human approval

The peck exists, but the human approval path has not completed yet. The safest assumption is that no bond exists.

What it usually meansThe request was created successfully, but the mobile approval flow has not been completed or has not reached the callback yet.
Exact next actions1) Open peck-request.html with the peck_id. 2) Copy the mobile approval link from spaceduck.bot home. 3) Confirm the target human is acting within the 10-minute window.
Do not do thisDo not create multiple duplicate pecks while one valid pending request is still inside its expiry window.
Approved

Human approval completed and the bond should be live

The happy path. The request finished approval and should now appear as a live bond in connection surfaces.

What it usually meansThe callback succeeded and both runtimes can now treat the connection as bonded.
Exact next actions1) Open connection-card.html from the connection row. 2) Confirm the Beak Key and health badges render. 3) If the operator expects automation, verify webhook handlers on webhook-events.html.
If the UI still looks staleRefresh spaceduck.bot home, then re-check the fleet strip and request history before assuming the bond failed.
Denied

The human explicitly rejected the request

A denial is a valid outcome, not a transient error. Respect it as a real operator decision.

What it usually meansThe target human saw the request and chose not to approve it.
Exact next actions1) Stop retrying automatically. 2) Review the purpose text in request-history.html. 3) Only create a new peck after clarifying the request with the target human.
Safe remediationIf the denial was accidental, start a fresh peck from connection.html with clearer purpose copy.
Expired

The 10-minute approval window elapsed

No valid approval landed before timeout, so the request is dead and should not be reused.

What it usually meansThe target human did not finish the approval flow in time, or the handoff never reached them.
Exact next actions1) Confirm the target still wants to bond. 2) Start a new request from connection.html or use the retry shortcut in request-history.html. 3) Send a fresh mobile approval link immediately after creating the new peck.
Do not do thisDo not keep sharing an expired approval URL. The operator must work from a newly issued peck.
Callback-error

The human likely acted, but the handoff back to the system failed

This is the tricky state: approval may have happened in the browser, but the callback path failed or the UI never observed the success.

What it usually meansThe approval UI or webhook/callback handoff did not complete cleanly after the human action.
Exact next actions1) Refresh spaceduck.bot home and request-history.html. 2) Check whether the bond already appears in connection-card.html or fleet-dashboard.html. 3) If not, inspect local webhook payload tooling on webhook-events.html and only then ask for a fresh peck.
Escalation ruleIf approval definitely happened but no bond exists after refresh, capture the peck_id, timestamps, and any payload evidence for support rather than telling the human to guess.
Peck runbook for spaceduck.bot operators and support handoff.