[API] Transfer cancel never reaches the agent — cancel_transfer has no server-side sender

[ToddHebebrand]

Description

POST /remote/transfers/:id/cancel only flips the DB row and writes an audit event — nothing is sent to the device. The agent keeps transferring after a "successful" cancel, so server/UI state (failed, "Cancelled by user") diverges from device reality until the transfer runs to completion.

Root Cause

apps/api/src/routes/remote/transfers.ts:360-415 — the cancel route does db.update(fileTransfers).set({ status: 'failed', errorMessage: 'Cancelled by user', ... }) + logSessionAudit, and returns. No device command is queued, no WS/relay message is sent.

The agent side is fully built and waiting: CmdCancelTransfer = "cancel_transfer" (agent/internal/remote/tools/types.go:74), handler registered (agent/internal/heartbeat/handlers_desktop.go:135), and filetransfer.Manager.CancelTransfer correctly flags in-flight transfers (loop checks at transfer.go:166-171, 277-282). But grep -rn "cancel_transfer" apps/api/src finds only a docsIndex.json mention — zero senders.

Note for whoever fixes this: the transfer create route (transfers.ts:37) doesn't queue a file_transfer command either — trace how file_transfer commands actually reach the agent today (likely the remote-session relay / viewer path, remoteTools capability) and wire cancel through the same channel. Also apps/web/src/components/remote/FileManager.tsx:552 — cancelTransfer only removes the item from local React state and never calls the API cancel route at all.

Proposed Fix

1. Make the API cancel route deliver cancel_transfer to the device via the same channel file_transfer uses.
2. Wire the web FileManager cancel button to the API route.
3. Only mark the row cancelled/failed after (or alongside) dispatch, and consider a distinct cancelled status vs failed.

Affected Files

• apps/api/src/routes/remote/transfers.ts (primary)
• apps/web/src/components/remote/FileManager.tsx
• agent/internal/heartbeat/handlers_desktop.go (receiver — already works)

Found during the macOS agent memory audit follow-ups (PR #2391 review, #2388).

[ToddHebebrand]

Finding: the missing cancel sender is only half the story — the entire file_transfer remote-transfer path is dead code, so wiring cancel_transfer into the cancel route would be a bridge to nowhere. Stopping before implementation; this needs a product/design decision first.

Evidence

• The only code that ever creates file_transfers rows is POST /remote/transfers (apps/api/src/routes/remote/transfers.ts:117) — and nothing calls it. FileManager.tsx was migrated off /remote/transfers onto the system-tools API in 9379f17 (Feb 2026); today there are zero callers in web, viewer, helper, mobile, or the AI tools. So the cancel route this issue targets is itself unreachable: no transfer rows ever exist to cancel.
• No server-side sender for file_transfer has ever existed either. At 9379f1792~1 (before the FileManager migration, when the web UI did call POST /remote/transfers), the create route still only inserted the DB row — no command was dispatched. The agent's filetransfer.Manager, handleFileTransfer, handleCancelTransfer, and the /remote/transfers/:id/chunks|progress|download endpoints it calls have never been triggered by the product.
• The live file-transfer path is apps/api/src/routes/systemTools/fileBrowser.ts: single-shot file_read / file_write commands via executeCommand (whole file base64 in one command payload). There is no cancellation semantic on that path — by the time the API could react, the agent is already processing the one-shot command.
• The FileManager cancel button (FileManager.tsx:552) just prunes local React state. It does not even abort the in-flight browser fetch, so the download/upload continues to completion regardless.

Options (needs a decision, in rough order of effort)

1. Client-side abort only (small, honest fix): give FileManager an AbortController per transfer so cancel actually stops the browser-side request, and stop rendering cancel as if it reached the device. Doesn't touch the dead path.
2. Deprecate the dead path: remove /remote/transfers* routes, the fileTransfers insert path, and the agent filetransfer manager + file_transfer/cancel_transfer handlers (or gate them behind an explicit revival plan). Sizable, touches agent, and overlaps PR fix(agent): remove filetransfer map entries when HandleTransfer returns (#2388) #2391 which is currently editing agent/internal/filetransfer/transfer.go.
3. Revive chunked transfers as the FileManager backend: the dormant path is actually the better design for large files (chunked, progress reporting, cancellable — everything file_read/file_write can't do, including the 50MB-class memory buffering the one-shot path forces). That's a feature project, not this bug fix.

Given the create route never dispatches anything, "make cancel reach the agent" as scoped can't be completed meaningfully — there is no in-flight agent transfer to cancel. Recommend re-scoping this issue to option 1 (immediate) and opening a separate design issue for 2-vs-3.

[ToddHebebrand]

PR #2404 implements option 1 only (client-side abort) — options 2 and 3 remain open for a decision.

Per the re-scope above: FileManager's Cancel now actually aborts the in-flight browser request via a per-transfer AbortController, shows a distinct cancelled state instead of silently dropping the row, and the copy is honest that a file_write command already dispatched to the device may still complete there (no device-side cancellation exists on the single-shot path). The 120s upload watchdog timeout now also surfaces as unverified with explicit timeout copy instead of browser abort boilerplate.

Intentionally untouched: the dead /remote/transfers* chunked path, the fileTransfers table, and agent/internal/filetransfer/ (open PR #2391 edits the latter). Whether to deprecate that path (option 2) or revive it as the FileManager backend for large/cancellable transfers (option 3) is still the open question this issue should track — leaving it open for that decision.

[ToddHebebrand]

PR #2413 executes option 2 (deprecate/remove the dead chunked-transfer path), as decided.

The removal covers the full surface from the investigation above: /remote/transfers* routes + the agent-facing progress endpoint, the transferCleanup worker, the chunk-storage service, the agent internal/filetransfer package with its file_transfer/cancel_transfer handlers and command types, the file_transfers table (idempotent drop migration with a forensic pre-drop row count in the Postgres logs), every registration-list entry (RLS coverage, device cascade, moveOrg, site-scope), and the docs/env/openapi references. The live path — system-tools file_read/file_write plus the option-1 client-side abort from #2404 — is untouched, as is the remote_sessions file_transfer session type (separate, live concept).

Verification and review details are on the PR. With #2404 (option 1) merged and #2413 covering option 2, this issue closes when #2413 merges (Closes #2396 in the PR body).