Consolidate duplicate and dead HTTP routes serving the same session resource

[moshloop]

The HTTP surface serves the same session resource from several parallel routes with different handlers and different JSON shapes, and several registered routes have no caller at all. Found while fixing the session detail page dropping its changed files (sessionFromOverview never mapped metadata->'files'); these are the sibling duplications the same audit surfaced.

Findings, in severity order

1. GET /api/captain/sessions/{id} is dead and duplicates GET /api/v1/sessions/{id}.
Both resolve to cli.RunSessionGet (pkg/cli/session_get.go:50) and emit SessionGetResult. The webapp uses only the /api/v1 one (pkg/cli/webapp/src/sessionData.ts:353); the /api/captain twin is referenced only by pkg/cli/serve_test.go:98. Removal is not purely mechanical — POST /api/captain/sessions/{id}/message shares the prefix.

2. Three envelopes for one session aggregate.

• GET /api/v1/sessions/{id} → {sessions:[{summary, detail, activeRunId, chat, chatState}]}
• GET /api/chat/sessions/{id} → a bare *session.Session (pkg/aichat/threads_http.go:98)
• GET /api/chat/sessions → []*Thread, a third projection of the same rows

A session opened from /chat/{id} is rendered from a payload with no chat/chatState/activeRunId, so live-run affordances are unavailable there.

3. /api/captain/projects vs /api/v1/projects are the same noun, different everything.
RunProjectOptions (pkg/cli/projects.go:76) is a DB aggregate returning {value,label,path,sources,sessions,lastUsed}; RunProjectsList (projects.go:53) is a filesystem scan returning {project,sessions,size,lastUsed} with pre-formatted display strings. The project picker gets the first, the chat agent gets the second. They will disagree.

4. Two independent cancel paths for one run id.
task.WithGroupID(runID) (pkg/cli/prompt_run.go:105) makes the clicky task group id equal the prompt run id, so POST /api/captain/tasks/{id}/control and POST /api/captain/prompt/runs/{id}/stop (prompt_chat_http.go:53) both cancel the same run through unrelated machinery, and GET /api/captain/tasks/{id} and GET /api/captain/prompt/runs/{id} describe it with unrelated JSON. Nothing reconciles them.

5. captain plan with no argument can never return a native plan.
resolveLatestTranscriptPlan (pkg/cli/plan.go:88) skips resolveNativePlan (:187), so it shows the stale transcript copy while captain plan <id> on the same session shows the approved revision from captain_plans. (The session detail path now prefers the native plan; captain plan still does not.)

6. Unmatched /api/** returns index.html with 200, which is why dead routes go unnoticed.
pkg/cli/serve.go:205 falls through to the UI handler, and newCaptainWebappHandler (serve.go:378-393) serves index.html for any path whose last segment has no dot. A wrong API path returns HTML rather than 404/405. Concretely: clicky-ui's TaskManager.tsx:301 POSTs /api/captain/tasks/{id}/tasks/{taskId}/control, which task.RegisterHandlers never registers, and silently receives HTML.

7. Other dead routes. GET /api/chat/tools (the UI injects tools so ChatWindow never fetches it), POST /api/chat/sessions/{id}/interrupt, GET /api/entities, POST /api/v1/ai/models.

8. Duplicated datemath parsing. parseSessionQueryTime (pkg/cli/serve_sessions.go:83) reimplements what clicky's flag parser already does, so the two session-list routes have two parsers and two error bodies for the same bad from=.

Note on why the /api/captain/* twins exist

Clicky's executor infers the HTTP method from the command path and defaults to POST, so read-only commands (sessions live, contexts, cost, plan, whoami) are exposed as POST. DatabaseContextMiddleware (pkg/cli/db_context_http.go:55) rejects non-GET on a non-default context with 409. The hand-written GET /api/captain/{contexts,sessions/live,projects} routes exist to work around that. The duplication is a symptom of the method inference, not an independent design — fixing it at that seam may remove several twins at once.

Scope

Triage and split as needed. Items 1, 6 and 7 are cheap deletions/guards. Items 2-4 need a decision about which contract wins. Item 5 is a one-line resolver-order fix.

Acceptance criteria

• Every route registered under /api/** either has a caller or is removed.
• An unmatched /api/** path returns 404, not index.html with 200.
• One session-aggregate contract, or an explicit documented reason for each variant.

[coderabbitai]

🔗 Related PRs

#13 - Feat/captain subagent history [merged]
#38 - Improve transcript ingestion and setup [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[adityathebe]

Where this sits in the overall plan: split in two — the mechanical cleanups are Phase-0 work worth doing immediately (they protect every later refactor), while the "which contract wins" decisions defer to #54. Reviewed against main @ 5db1179; every finding verified, several with sharpened detail:

Do now (independent, cheap, high-leverage):

• Finding 6 first. Confirmed, and worse than written: not only do unmatched /api/** paths return the SPA with 200, a method mismatch on a real pattern (e.g. POST to a GET-only route) also falls through to / instead of 405. Meanwhile /api/chat/** already 404s correctly because the sub-mux claims the prefix — that's the model: an /api/ guard returning 404/405 before the SPA handler. This single change is what makes every other dead route visible, so it should land before the deletions.
• Finding 1: confirmed dead, and the /api/captain twin is the weaker one (forwards only offset/limit/tail, dropping the --tool/--category filters the /api/v1 binding supports). Delete it; keep POST /api/captain/sessions/{id}/message which shares the prefix.
• Finding 5: confirmed — bare captain plan can never see a persisted plan revision (resolveLatestTranscriptPlan never calls resolveNativePlan, and sessions without an on-host transcript are skipped entirely). One-line resolver-order fix.
• Finding 7: GET /api/chat/tools and POST /api/v1/ai/models confirmed dead from the webapp. /api/chat/sessions/{id}/interrupt and /api/entities are probably dead but not provable without checking clicky-ui internals (link: dep, no node_modules in a clean checkout) — verify there before deleting. Minor extra: chat.Handler() is constructed twice (serve.go:198-199), building two independent sub-muxes.

Defer to #54 (don't decide here): finding 2's three envelopes for one session aggregate is the same decision as #54's "bounded thread summaries + detail hydration from a server-authoritative contract". Let #54 define the winning shape; this issue then deletes the losers.

Needs its own decision, tied to the runtime/task work: finding 4 — confirmed that both cancel paths are live from the UI (RunningPrompts.tsx mounts task-control at /api/captain; the stop button uses /stop), and the task-control path bypasses the chat broker (chats.getRun → chat.stop cleanup only happens via /stop), so cancelling via task control can strand chat state. That's an argument for making /stop the only public path sooner rather than later.

Cross-repo root cause: the method-inference workaround (why the /api/captain twins exist) is consistent with the evidence but lives in clicky's executor — fixing it there retires several twins at once; worth a clicky issue.

---

Generated by Claude Code