feat: support image attachments in X replies

[kunchenguid]

Intent

Add proper image attachment support to firstmate's X reply client. The reply helper must accept --image , validate and encode a local image, detect media_type from common image extensions, and include the relay's optional image object on both /connector/answer and /connector/followup. The follow-up helper must forward --image through to fm-x-reply.sh --followup. Help text, header usage, AGENTS.md section 14, and public docs should make image support immediately discoverable. Threaded replies must keep the image on the first opener tweet, matching the relay contract. FMX_DRY_RUN should preview a compact image marker with media_type, bytes, and source_path instead of the base64 blob. Preserve existing no-image behavior and current exit contracts, with tests for answer, followup, bad image paths, dry-run, help, and unchanged no-image paths.

What Changed

• Add --image <path> support to the X reply path, including local image validation, extension-based media_type detection, base64 payload construction, and relay image objects for both answers and followups.
• Preserve existing no-image replies while routing threaded image replies through the opener tweet and showing compact image metadata in FMX_DRY_RUN instead of raw base64.
• Update fm-x-followup forwarding, CLI help, firstmate/docs references, and X mode tests for answer, followup, dry-run, missing image, help, and unchanged no-image paths, captain.

Risk Assessment

✅ Low: Captain, the change is well-scoped to X reply/follow-up image payload handling and the earlier temp-file and argv-limit risks are addressed without introducing material regressions I can substantiate.

Testing

Baseline full tests were already green; I reran the X-mode suite and manually exercised the end-user CLI flows for image answer, image follow-up, threaded dry-run preview, bad image path handling, help/docs discoverability, and no-image preservation, with all checks passing and reviewer evidence saved in the requested evidence directory.

Evidence: CLI transcript

## answer with image req-e2e-answer ## no-image answer stays unchanged req-e2e-noimage ## follow-up wrapper with image req-e2e-followup ## threaded dry-run with image marker req-e2e-thread ## bad image path exit=1 fm-x-reply: image file does not exist: /var/folders/5x/4nqprlbx0518k3ybcb1sz6gr0000gn/T/no-mistakes-evidence/01KWCX362DRKDW9H4EQZ8RSPXH/assets/missing.png

## answer with image
req-e2e-answer

## no-image answer stays unchanged
req-e2e-noimage

## follow-up wrapper with image
req-e2e-followup

## threaded dry-run with image marker
req-e2e-thread

## bad image path
exit=1
fm-x-reply: image file does not exist: /var/folders/5x/4nqprlbx0518k3ybcb1sz6gr0000gn/T/no-mistakes-evidence/01KWCX362DRKDW9H4EQZ8RSPXH/assets/missing.png

## help excerpts
usage: fm-x-reply.sh <request_id> [--followup] [--image <path>] <text>
       fm-x-reply.sh <request_id> [--followup] [--image <path>] --text-file <path>
       fm-x-reply.sh <request_id> [--followup] [--image <path>] -
  --image <path>   Attach one local image file; threaded replies attach it to the opener tweet.
       fm-x-followup.sh <task-id> [--image <path>] --text-file <path>
       fm-x-followup.sh <task-id> [--image <path>] -
  --image <path>   Attach one local image file; threaded replies attach it to the opener tweet.

Evidence: Answer image payload summary

{"request_id":"req-e2e-answer","text":"Here is the generated diagram.","image":{"media_type":"image/png","data_base64_length":92}}

{
  "request_id": "req-e2e-answer",
  "text": "Here is the generated diagram.",
  "image": {
    "media_type": "image/png",
    "data_base64_length": 92
  }
}

Evidence: Follow-up image payload summary

{"request_id":"req-e2e-followup","text":"Done - generated image attached.","image":{"media_type":"image/png","data_base64_length":92}}

{
  "request_id": "req-e2e-followup",
  "text": "Done - generated image attached.",
  "image": {
    "media_type": "image/png",
    "data_base64_length": 92
  }
}

Evidence: No-image payload summary

{"request_id":"req-e2e-noimage","text":"Plain text answer.","has_image":false,"keys":["request_id","text"]}

{
  "request_id": "req-e2e-noimage",
  "text": "Plain text answer.",
  "has_image": false,
  "keys": [
    "request_id",
    "text"
  ]
}

Evidence: Threaded dry-run image marker

{"request_id":"req-e2e-thread","texts_count":3,"image":{"media_type":"image/webp","bytes":34},"has_base64":false}

{
  "request_id": "req-e2e-thread",
  "text": "alpha bravo charlie delta echo foxtrot (1/3)",
  "texts_count": 3,
  "image": {
    "media_type": "image/webp",
    "bytes": 34,
    "source_path": "/var/folders/5x/4nqprlbx0518k3ybcb1sz6gr0000gn/T/no-mistakes-evidence/01KWCX362DRKDW9H4EQZ8RSPXH/assets/thread-preview.webp"
  },
  "has_base64": false
}

Evidence: Raw answer relay payload

{"request_id":"req-e2e-answer","text":"Here is the generated diagram.","image":{"media_type":"image/png","data_base64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII="}}

Evidence: Raw follow-up relay payload

{"request_id":"req-e2e-followup","text":"Done - generated image attached.","image":{"media_type":"image/png","data_base64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII="}}

Evidence: Docs and help discoverability grep

bin/fm-x-followup.sh:17:#   fm-x-followup.sh <task-id> [--image <path>] --text-file <path>
bin/fm-x-followup.sh:18:#   fm-x-followup.sh <task-id> [--image <path>] -
bin/fm-x-followup.sh:28:# With --image <path>, the follow-up carries one local image attachment; if the
bin/fm-x-followup.sh:43:  echo "usage: fm-x-followup.sh --check <task-id> | <task-id> [--image <path>] --text-file <path> | <task-id> [--image <path>] -" >&2
bin/fm-x-followup.sh:49:       fm-x-followup.sh <task-id> [--image <path>] --text-file <path>
bin/fm-x-followup.sh:50:       fm-x-followup.sh <task-id> [--image <path>] -
bin/fm-x-followup.sh:56:  --image <path>   Attach one local image file; threaded replies attach it to the opener tweet.
bin/fm-x-reply.sh:4:# Usage: fm-x-reply.sh <request_id> [--image <path>] <text>
bin/fm-x-reply.sh:5:#        fm-x-reply.sh <request_id> [--image <path>] --text-file <path>
bin/fm-x-reply.sh:6:#        fm-x-reply.sh <request_id> [--image <path>] -
bin/fm-x-reply.sh:7:#        fm-x-reply.sh <request_id> --followup [--image <path>] ...
bin/fm-x-reply.sh:14:# Optional --image <path> attaches one local image file to the answer or followup
bin/fm-x-reply.sh:17:# attaches that image to the first/opener tweet only.
bin/fm-x-reply.sh:81:  echo "usage: fm-x-reply.sh <request_id> [--followup] [--image <path>] <text> | [--followup] [--image <path>] --text-file <path> | [--followup] [--image <path>] -" >&2
bin/fm-x-reply.sh:86:usage: fm-x-reply.sh <request_id> [--followup] [--image <path>] <text>
bin/fm-x-reply.sh:87:       fm-x-reply.sh <request_id> [--followup] [--image <path>] --text-file <path>
bin/fm-x-reply.sh:88:       fm-x-reply.sh <request_id> [--followup] [--image <path>] -
bin/fm-x-reply.sh:94:  --image <path>   Attach one local image file; threaded replies attach it to the opener tweet.
bin/fm-x-reply.sh:202:# Build the body with jq so the text and optional image object are correctly
docs/scripts.md:41:| `fm-x-lib.sh`            | Shared X-mode `.env`, alternate env-file, relay, dry-run config, reply-thread splitting, outbound image payloads, and task-to-X-request meta-link helpers |
docs/scripts.md:43:| `fm-x-reply.sh`          | Post or dry-run preview a composed public-safe X answer or `--followup`, auto-splitting long text into `{request_id,text,texts}` threads and optionally attaching `--image <path>` to the opener; reads text from an argument, stdin, or `--text-file` |
docs/scripts.md:46:| `fm-x-followup.sh`       | Detect, post, and clear the single completion follow-up for an X-linked task, forwarding optional `--image <path>`, enforcing the local 24h window, and retrying only when the relay post fails |
docs/configuration.md:128:Add `--image <path>` to attach one local image as the relay's optional `image` object.
docs/configuration.md:130:Add `--image <path>` there too when the completion follow-up should carry an image.
docs/configuration.md:133:When `--image <path>` is present on a split reply, the image rides the first/opener tweet and later chunks stay text-only.
docs/configuration.md:140:When an image is attached, the dry-run record uses compact `{media_type, bytes, source_path}` metadata instead of writing the base64 bytes.
AGENTS.md:834:When the reply needs one outbound image, pass `--image <path>` to `bin/fm-x-reply.sh`; the helper reads the local file, detects the media type, base64-encodes the raw bytes, and sends the relay's optional `image` object without inlining image bytes into the shell command.
AGENTS.md:841:When the completion follow-up needs one outbound image, pass `--image <path>` to `bin/fm-x-followup.sh`; it forwards the image to `bin/fm-x-reply.sh --followup` so the same relay image contract is used for the follow-up endpoint.
AGENTS.md:859:When `--image <path>` accompanies a reply that auto-splits into a thread, the client includes `image` alongside `text` and `texts`, and the relay attaches that image to the first/opener tweet only while later chunks remain text-only.
AGENTS.md:863:When `--image <path>` is present, the live POST body carries the real `image.data_base64`, but the dry-run outbox stores only a compact marker `{media_type, bytes, source_path}` so previews do not write multi-MB blobs.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 2 issues found → auto-fixed (2) ✅

• 🚨 bin/fm-x-lib.sh:202 - --image stores the base64 blob in a shell variable and passes it to jq via --arg; the final payload is later passed to curl --data the same way. Normal screenshots or generated images can exceed the OS argument limit, so valid image replies will fail before reaching the relay. Stream the encoded data and POST body through stdin or temp files instead, for example jq -Rs plus curl --data-binary @-.
• ⚠️ bin/fm-x-lib.sh:248 - The refactor removed the reply client's EXIT cleanup trap for the bearer-token header file. If the process is interrupted after fmx_auth_header_file succeeds and before the explicit rm, the token-bearing temp file can be left behind. Restore scoped trap cleanup inside fmx_post_json or avoid creating a persistent header file for this path.

🔧 Fix: Stream X image replies safely
1 warning still open:

• ⚠️ bin/fm-x-reply.sh:76 - reply_tmp_file appends to TMP_FILES, but every caller invokes it through command substitution, so the append happens in a subshell and the parent EXIT trap never sees the paths. Successful replies and dry-runs now leave request payload temp files behind, and image replies leave base64 image payload files in TMPDIR; create/register the temp path in the parent shell instead.

🔧 Fix: Captain, clean X reply temp tracking
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• Baseline already completed successfully before this run: command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• bash tests/fm-x-mode.test.sh
• Manual fake-relay CLI evidence: bin/fm-x-reply.sh req-e2e-answer --image <png> ..., bin/fm-x-reply.sh req-e2e-noimage ..., bin/fm-x-followup.sh task-img --image <png> --text-file ..., FMX_DRY_RUN=1 FMX_X_REPLY_MAX_CHARS=50 bin/fm-x-reply.sh req-e2e-thread --image <webp> ..., missing-image failure, and --help excerpts
• rg -n -- '--image <path>|opener tweet|image object|dry-run record uses compact|compact \{media_type|image support|outbound image' AGENTS.md docs/configuration.md docs/scripts.md bin/fm-x-reply.sh bin/fm-x-followup.sh > /var/folders/5x/4nqprlbx0518k3ybcb1sz6gr0000gn/T/no-mistakes-evidence/01KWCX362DRKDW9H4EQZ8RSPXH/docs-discoverability.txt
• git status --short and transient artifact scan confirmed no working-tree artifacts were left behind

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.