feat(server): loopback control API + per-batch progress + idle-exit (#30, PR-2a)

[kfastov]

PR-2a of #30 — server-side foundation for server-executed backfill. The CLI client (backfill --chat X foreground/background, backfill status/count/wait/cancel, auto-start) consumes this in PR-2b.

A. Always-on loopback control API

• New core/control-server.js + a listener in mcp-server.js, bound to 127.0.0.1 (config control.{enabled,host,port}, default true/127.0.0.1/8765), independent of mcp.enabled. The existing MCP listener is untouched.
• Auth: a per-store 192-bit token written to <store>/control.json (mode 0600); every /control/* request must send header x-tgcli-control-token, else 401.
• Endpoints (delegate to the same MessageSyncService methods the MCP tools use — no duplicated job logic):
  • GET /control/ping → { ok, pid, version, startedAt, jobs: { pending, inProgress } }
  • POST /control/backfill {chatId, depth?, minDate?} → addJob + processQueue → { jobId, channelId, status }
  • POST /control/cancel {chatId?|jobId?} → { canceled, jobIds }

B. Per-batch progress persistence

• New started_at jobs column (via the idempotent _ensureJobColumn); _backfillHistory now updates message_count/cursor/updated_at (and stamps started_at on the first batch) every batch, so backfill status/count (PR-2b) reflect live progress. New helpers getJobCounts() and getWatchedChannelCount().

C. Idle-exit

• server --idle-exit <duration> (forwarded to the worker child). Idle = 0 pending + 0 in-progress jobs AND 0 watched channels (sync_enabled=1) AND control API quiet longer than the window → graceful shutdown (removes control.json). No flag → always-on. So any active channels watch keeps the daemon alive (it needs realtime).

Why

The server is a lock-free WAL writer and CLI reads coexist with it. Routing backfill through it (PR-2b) means the CLI won't take its own exclusive write lock → single writer, no lock contention.

Scope — not here

Server-side only: part of #30, not a close. PR-2b adds the CLI backfill client + auto-start; PR-3 routes realtime/auth through the single writer. The MCP listener is unchanged.

Tests

npm test → 252 passing (224 baseline + 28 new across 4 files): control endpoints incl. 401 on missing/wrong token; per-batch progress with a temp DB + stub client; idle predicate truth table + fake-timer shutdown + control.json 0600 lifecycle; control.* config normalization. No real network.

Noted hardening follow-ups (negligible on a loopback+token API; not blocking)

• Token compare is plain === — could use crypto.timingSafeEqual.
• No request-body size cap on the control endpoints.