Workspace heartbeat

The backend posts to /internal/v1/heartbeat through the Unix socket /var/strong-network/socks/sidecar-ipc every five seconds. No browser connection, caller token, workspace ID, or public proxy is required.

While at least one chat turn is in flight, it sends wasActive: true. This includes backend setup, quiet model/tool execution, and subagents belonging to that turn, even if the browser disconnects. A turn waiting for an interactive answer remains in flight. Once all turns finish, fail, or end after cancellation, heartbeats use wasActive: false, which does not refresh the workspace idle timer. Merely running the HTTP server or an idle OpenCode server does not keep the workspace active.

Recent use of the web UI is the second source of wasActive: true. The browser posts to /api/activity when the page loads and, while the user is typing or clicking, once a minute thereafter; each post keeps the workspace active for five minutes. Reading a long answer or composing a message therefore no longer looks idle. The window is deliberately coarse — the platform idle timer is measured in tens of minutes, so it only has to survive a few missed posts. A browser tab left open with nobody touching it stops reporting and goes idle as before.

The supplied REST contract has no generic Chat category: this integration sends IDE_TYPE_VSCODE, so activity is attributed to VS Code reporting. The timestamp is current Unix seconds encoded as a decimal string.

Requests have a five-second timeout and never overlap. Connection failures and non-2xx responses are logged, with exponential retry delays from ten seconds up to one minute. Each retry samples current task activity, never replays old intervals, and successful requests restore the five-second cadence. A timeout leaves delivery unknown. Shutdown cancels any in-flight request and stops the worker.

Logs use the [workspace-heartbeat] prefix. Startup records the socket, interval, and timeout; activity changes show wasActive=true/false along with which source asked for it (task keep-alive and ui keep-alive). A delivered message confirms a successful HTTP response, on first success, activity changes, recovery after failures, and once per minute while unchanged. Failures include the attempted activity state, consecutive failure count, and retry delay. Disabled reporting and worker shutdown are also logged. Delivery confirms receipt, not a workspace lease.

Set KWA_WORKSPACE_HEARTBEAT=false (also 0, no, or off) to disable this task keep-alive mode, including when developing without the sidecar. Enabled by default. There is no TCP fallback or proxy/environment URL override; the socket must be accessible to the server user. Failures do not prevent chat from working.

This implements the supplied workspace-local REST contract; deployed sidecar compatibility must be verified in the target workspace. Heartbeats cannot resume a paused workspace or prevent manual stops and infrastructure failures.