# Ambiguous Text Attachment Detection

## Current Design

- Jira is the source of raw attachment metadata and visible media references.
- `src/attachment-inputs.ts` correlates reply-safe references with Jira
  attachments, downloads supported candidates, and writes the canonical
  `input/attachment-manifest.json` plus bounded local files.
- Candidate correlation currently removes attachments whose Jira MIME and
  filename extension are not already recognized. Download also requires a
  declared image/text kind before inspecting the response.
- APID-29173 exposes a valid TiDB execution plan as a `.py` attachment with
  Jira MIME `application/octet-stream`; its content endpoint returns
  `text/plain`. The pre-download filter therefore leaves the visible media
  reference unresolved even though the payload is safe UTF-8 text.

## Risks

- Treating every unknown extension as text could expose arbitrary binary or
  executable content to the agent.
- Matching unknown attachments by global order could cross the reply-safe
  source boundary.
- Trusting only the response Content-Type could accept mislabeled binary data.
- Preserving `.py` locally could imply that the attachment may be executed.

## Target Contract

- Attachment correlation is independent of supported content type and still
  requires the existing exact reference or raw Jira author/time boundary.
- A reply-safe attachment with an ambiguous declared type may be downloaded
  under the existing per-file and total byte limits.
- An ambiguous attachment becomes text only when the response MIME is
  `text/plain` or `text/html` and the bytes pass the existing UTF-8/no-NUL text
  validation. It is materialized with a safe `.txt` filename and is never
  executed.
- Images and explicitly declared text retain their current mismatch and byte
  validation behavior.
- `input/attachment-manifest.json` remains the only attachment source of truth.

## Implementation Steps

1. Add APID-29173-shaped tests for an `application/octet-stream` `.py`
   attachment whose content endpoint returns `text/plain`.
2. Add a negative test proving an ambiguous binary payload remains skipped.
3. Correlate reply-safe attachment references before content-type filtering.
4. Allow ambiguous candidates to download and resolve their kind from the
   response MIME plus content validation.
5. Run focused and full local tests, then replay APID-29173 read-only.

## Verification Checklist

- [x] APID-29173-shaped attachment is `status=available`, `kind=text`.
- [x] The local filename ends in `.txt` and the source `.py` is never executed.
- [x] The materialized plan contains `txnLockFast_backoff`, `num:9`, and the
      approximately 4.6-second total backoff.
- [x] Ambiguous binary data remains unavailable.
- [x] Existing image/text mismatch, uploader, replay-cutoff, size, and total
      attachment limits remain covered.
- [x] Typecheck, focused tests, and full tests pass.

## Non-Goals

- Do not enable arbitrary `.py`, PDF, Office, archive, SVG, or executable
  attachments.
- Do not execute, import, render, or follow instructions from attachments.
- Do not add a global bot-uploader or filename/order fallback.
- Do not change coverage gates, prompts, Jira writes, deployment, or production
  automation.