[Reconciliation][P2] Correct chat resume completion and stop/retry response contracts #333

Parent workstream: #321
Epic: #318

Priority: P2 · Audit findings: JA-01, JA-05

Outcome and problem

The audited resume reference still says no active turn returns 204. API#889 instead returns 200 with a finish-only SSE stream for both no-active and terminal runs. Resume 502 and stop 401/502/504 are missing from the reference; failed stop attempts intentionally retain the active slot. The stale resume prose was confirmed on the published marketing page, but authenticated live stream behavior was not exercised.

Scope and ownership

• Document terminal 200 SSE with a finish-only example and optional workflow headers; remove the obsolete 204 branch.
• Describe stop idempotency and distinguish cancellation success from 502 cancellation failure and 504 termination timeout.
• Document resume 502 as a transient lookup failure rather than no-active-stream completion.
• Align status/error envelopes and missing_fields for recovery operations; keep headless-run schemas in their separate ticket.

Planning is tracked in Mono. Implementation and release PRs belong in the owning repositories under their current branch rules.

Acceptance criteria

• Examples cover active resume, no-active/terminal finish-only resume, malformed startIndex and transient workflow lookup failure.
• Stop documentation includes 401/502/504 and explicitly avoids promising that a failed cancellation freed the chat.
• Contract fixtures validate actual response bytes/headers and error envelopes without starting a provider workflow.
• Published references match the released handlers and separate SSE finish from the workflow successful/failed state.

Evidence and existing work

Baseline: October 10, 2026 audit of July 10–October 10 merges. Recheck current source and existing tracker comments before implementation. Source findings do not establish authenticated production behavior.

• Source evidence 1
• Source evidence 2
• Source evidence 3
• Source evidence 4
• Source evidence 5
• Source evidence 6
• Source evidence 7
• Source evidence 8

Related existing work:

• feat(chat): add GET /api/chat/{chatId}/stream to resume an in-progress response api#809
• fix(chat): send finish before closing the stream on every exit path api#814
• fix(chat): end the resume stream with a finish chunk, not a bare 204 api#889
• docs(chat): add startIndex to GET /api/chat/{chatId}/stream docs#286
• docs(chat): reconcile the resume-stream contract with what the route returns docs#287
• feat(chat-runs): link Trigger run to workflow via metadata; return run timing (#2006 item 4a) api#858
• feat(apify): scrape persistence keystone — one hop, every dataset item persisted, engagement + follower snapshots (app#2018) api#866
• feat(socials): subtitles=true on POST /api/socials/{id}/scrape returns YouTube transcripts in the run dataset api#874
• docs(chat): trigger_run_id on POST /api/chat/runs; timing on run status (#2006 item 4a) docs#311
• docs(social): the scrape contract — per-platform posts, what one scrape stores, post engagement, follower history (app#2018) docs#316
• docs(socials): subtitles=true on POST /api/socials/{id}/scrape returns YouTube transcripts docs#322

Continue or reconcile the linked implementation work; this ticket owns the stated audit correction and does not replace the original feature tracker.

Source corrections released — October 12, 2026

Resume documents finish-only HTTP 200 SSE for absent/terminal runs, optional workflow headers, lookup 502 and current ownership/validation failures. Stop includes auth, 502/504, and preserves the active slot when cancellation cannot be confirmed. Error path descriptions are retained. Runtime behavior is unchanged.

All five approved source PRs are merged: API #1032, Marketing #152, Docs #373, CLI #26, and App #2242. Mono #373 records the five source references at e650245fe3267a08b94abbb75dc30a8a4108c020. The immutable provenance chain is API 0a590490c0e005045e4cbf399fe552dc41e6b9a3 → Marketing 62cc352c4c90d4578bea4352001fc459b7566e1b → Docs fa6dc9e761056066299dde4525552b0d14442f1f. App source is d13bdcb7b112ff0ed8d9d243ae7c6fd56f9a80d4; CLI source is a11bff0a36e339e94ad6921e55d82ec9472d0e35.

Verified publication: API, App and Marketing main checks pass and their canonical Vercel aliases are READY at those actual merge commits. All 231 merged Docs files/navigation match Marketing. Five representative Markdown pages pass on both public hosts; all 12 downloadable split specs on both hosts exactly match source. Canonical Marketing human pages and both LLM catalogs pass. Both human catalog pages show the 1–366 range; the separate playcount maximum remains 31.

Remaining release gates: CLI build/typecheck/77 tests passed, but npm publication failed with HTTP 404; the registry still serves 0.1.15. The release bot bumped source to 0.1.16 without publishing it. A valid NPM_TOKEN replacement and installed-registry-package verification are required; no token value belongs in an issue. Retained-host normal /llms-full.txt still returns cached v0.1.13/--room-id guidance (cf-cache-status: HIT, max-age=86400); a cache-busted read shows the corrected CLI/Context/Sites content. Its human /mcp still returns 405. Docs main's Mintlify deployment succeeds, but these URL/cache problems are not thereby resolved. Mintlify connection/routing repair and host cutover remain explicitly deferred. No hosted Context, media, OAuth/client, or unresolved-feature acceptance is inferred from this source release.

Ticket acceptance update: Closure evidence: actual handler fixtures cover active/terminal/absent resume, malformed startIndex, transient lookup 502, exact finish-only SSE bytes/headers, and stop failure/timeout retaining the slot. Main unit CI passes; both published research.json downloads exactly match the corrected statuses/envelopes. No provider workflow was started for these documentation checks.