Exit codes

acpx uses a small, stable set of exit codes so wrapping scripts can branch on them.

#Notes

• 0 is also returned by cancel when there is nothing to cancel. The text/JSON output makes the distinction.
• 1 is the catch-all for adapter errors, transport failures, and unexpected runtime errors. Stderr or the JSON error envelope contains details.
• 2 signals "you typed something acpx cannot run" — combining --agent with a positional agent token, mutually exclusive permission flags, missing required arguments, etc.
• 3 is reserved for --timeout expiry. Adapter-side timeouts that are not surfaced as acpx timeouts come through as 1.
• 4 is the "directory walk found no active session" signal. Run sessions new (or sessions ensure for idempotent scripts) and retry.
• 5 only fires when at least one permission request happened, and every one ended in a denial or cancellation. If at least one was approved, the result reflects whatever the agent returned.
• 130 matches the conventional shell signal exit code for Ctrl+C (128 + SIGINT). acpx cancels cooperatively before exiting with this code.

#Branching example

if acpx --format quiet codex 'one-line summary' >summary.txt; then
  echo "ok"
else
  case $? in
    2)   echo "usage error" ;;
    3)   echo "timed out"   ;;
    4)   echo "no session — run sessions new"; acpx codex sessions new ;;
    5)   echo "all denied"  ;;
    130) echo "interrupted" ;;
    *)   echo "agent or runtime error" ;;
  esac
fi

#See also

• Permissions — what makes exit 5 happen.
• Sessions — what makes exit 4 happen and how to fix it.
• Prompting — --timeout and --no-wait semantics.