…eply

Second ST of Feature 5. Joshua DMs → Kora replies. Reply content is
the LOCKED echo "Kora received: {text[:200]}" — real AI-driven
response generation is the KR-FEAT-SLACK-DM-AI follow-on.

## New module

**`kora_cli/clients/slack_client.py`** (~240 lines) — minimal async
Slack Web API wrapper:

- `SlackClient` reads `KORA_SLACK_BOT_TOKEN` at `__init__`;
  **fail-CLOSED** with `SlackClientNotConfigured` if unset/whitespace.
- `post_dm(channel_id, text, thread_ts)` posts to
  `https://slack.com/api/chat.postMessage`.
- httpx (core dep; `httpx[socks]==0.28.1`) over aiohttp (slack
  extra only) — consistent with the daemon's existing outbound HTTP
  patterns (`heartbeat_probes/`, `auth.py`, `web_server.py`); drops
  one extra requirement from daemon deploys.
- 10s per-call timeout.
- **Retry policy** (max 2 attempts):
  - HTTP 429: respect `Retry-After` header (default 1s if missing);
    1 retry.
  - HTTP 5xx: 0.5s backoff; 1 retry.
  - HTTP 2xx + `ok: false` (e.g. `invalid_auth`,
    `channel_not_found`): NO retry; raise `SlackAPIError`.
  - HTTP 4xx other than 429: NO retry; raise `SlackTransportError`.
  - Transport exception on attempt 1: 1 retry.
- Constant-time bearer compare not needed (token is the daemon's
  own, not user-presented); but the token is NEVER logged, NEVER
  in error messages, NEVER in `__repr__` — asserted by
  diverse-failure-mode test.

## Error hierarchy

- `SlackClientError` (base)
  - `SlackClientNotConfigured` — missing env
  - `SlackAPIError` — Slack returned ok:false; carries `slack_error`
  - `SlackTransportError` — network failure / retry exhaustion;
    carries `last_status` when applicable

Handler maps these to stable `failure_reason` codes in outbound JSONL
(`slack_client_not_configured` / `slack_api:<error>` /
`transport:<status>` / `transport:<exc_name>`).

## Handler integration

**`kora_cli/handlers/slack_dm_handler.py`** (+204 lines):

- New optional `slack_client` constructor arg. Production code
  lazy-constructs on first reply via `_get_or_create_slack_client`;
  `SlackClientNotConfigured` → returns None → outbound JSONL
  entry with `failure_reason: "slack_client_not_configured"`. The
  None is CACHED so subsequent inbound events don't re-log the
  same failure.
- After the inbound `received` JSONL entry + chain emit, calls
  `_send_echo_reply()` which:
  - Builds `Kora received: {text[:200]}` (echo format LOCKED).
  - thread_ts = event.thread_ts (already in-thread) OR event.ts
    (new thread under the originating DM) — Kora threads under
    Joshua's message every time.
  - Catches all exceptions (SlackAPIError, SlackTransportError,
    and even unexpected types) — writes outbound JSONL entry +
    `[kora.slack_dm.reply_failed]` structured-log emit + returns
    cleanly. Inbound handler always returns ok to Slack.
- New `_append_outbound_log_entry()` — distinct JSONL schema:
  `{sent_at, channel_id, thread_ts, text, slack_message_ts,
  send_status, failure_reason?}` so operator log-analysis can
  branch on `received_at` (inbound) vs `sent_at` (outbound) key
  presence.

## Filtered events do NOT trigger reply

Only the all-filters-passed identified-Joshua path calls
`_send_echo_reply()`. Non-Joshua / bot / subtype / non-IM /
PAUSED-state events stop at their respective filter without an
outbound attempt — asserted by 4 tests in `test_slack_dm_reply.py`.

## Tests (28 new, 233 total all passing)

**`test_slack_client.py`** (14 tests):
- Fail-CLOSED on missing / whitespace token
- Constructor reads token from env at construction (not lazy)
- Successful post_dm returns response dict; thread_ts in payload
  when present + omitted when None
- Auth header is `Bearer xoxb-...`; Content-Type JSON
- SlackAPIError on ok:false (channel_not_found, invalid_auth) —
  NO retry
- 429 → respect Retry-After → 1 retry → success
- 429 on BOTH attempts → SlackTransportError(last_status=429)
- 429 missing Retry-After header → default value used
- 5xx → retry → success; 5xx on both → SlackTransportError
- 503 treated as 5xx (retryable)
- 4xx non-429 (401/403/404) → NO retry; SlackTransportError
- Timeout on attempt 1 → 1 retry; timeout on both → SlackTransportError
  with last_status=None
- **SECURITY**: Bot token NEVER in error messages / repr / log
  output after diverse failure-mode sequence

**`test_slack_dm_reply.py`** (14 tests):
- Echo format LOCKED `Kora received: {text[:200]}`
- thread_ts uses event.thread_ts when present, falls back to
  event.ts otherwise
- Echo text truncated at 200 chars even for 5000-char input
- JSONL: inbound `received` entry first, outbound `ok` entry
  second; distinct schemas
- Missing bot token → outbound `failed` +
  `failure_reason: slack_client_not_configured` + reply_failed log
- SlackTransportError 429 / 500 / timeout → outbound `failed` with
  stable `transport:<code>` / `transport:<exc_name>` reasons
- SlackAPIError → outbound `failed` with
  `slack_api:<error_code>` reason
- Unexpected exception (RuntimeError) does NOT crash inbound handler
- Filtered events (non-Joshua / bot / subtype / PAUSED) do NOT
  trigger reply
- **SECURITY**: Bot token NEVER appears in JSONL after diverse
  paths (success / transport / api / filtered)

**ST1 test fixture updated**: `_read_log_lines` filters to inbound
entries (`handled_status` key), so existing ST1 assertions stay
sharp; happy-path test that previously asserted "3 lines" now
asserts "5 lines (3 inbound + 2 outbound from 2 Joshua DMs)" with
schema-branched validation.

## §5 ship checklist

- [x] Base `feature/phase2-upgrades`
- [x] Title format `feat(kora): KR-FEAT-SLACK-DM STn — <scope>`
- [x] §4 defaults locked (echo format, retry policy, dead-letter)
- [x] Bot token NEVER logged (asserted at both SlackClient layer +
      handler JSONL layer)
- [x] Reply failure does NOT crash handler (3 distinct exception-
      class tests + 1 unexpected-type test)
- [x] Slack always gets 200 OK (handler returns ok regardless of
      outbound disposition)
- [x] Tests pass locally (**233/233** across full daemon + listener
      + handler + client + docker suite)

## What's next

**ST3** — `kora_docs/15_status_and_roadmap/slack_app_setup_runbook.md`
covering Slack app creation, OAuth scopes (`chat:write`, `im:history`,
`im:read`, `im:write` for bot; `message.im` for events), Event
Subscriptions wire-up, Doppler secret setup for the 3 envs
(`KORA_SLACK_SIGNING_SECRET`, `KORA_SLACK_BOT_TOKEN`,
`KORA_SLACK_JOSHUA_USER_ID`), smoke test, troubleshooting, the dual
signing-secret env transition note (legacy `SLACK_SIGNING_SECRET`
used by `gateway/platforms/slack.py` Bolt path; new env covers the
daemon listener).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>