Worker 扩容与生命周期

agent worker controller 根据队列启动 worker。它使用服务账号 key，必须提供 --spawn 脚本；脚本负责创建进程、容器或 Pod。

按请求创建

agent worker controller --spawn ./spawn.sh --pool my-pool --session-token

CURSOR_API_KEY 由运行环境提供。默认 controller 先 list/watch 请求，成功 claim 后调用 spawn。脚本必须保留 CURSOR_AGENT_WORKER_ID，使启动的机器与 claim 对应。

--session-token 让 spawn 收到 CURSOR_AUTH_TOKEN 和过期时间，服务账号 key 留在 controller。token 只服务一次 claim，claim 释放或签发 key 失效即不能使用；7 天过期只是最长兜底。可写入文件并让 worker 用 --auth-token-file，在重连时重读更新值。

预热容量

agent worker controller --spawn ./spawn.sh --pool my-pool --warm-idle 5

warm 模式维持每个指定 pool 的空闲数量，不主动 claim；每 60 秒对照 pool 状态，SSE 用于加速补充。必须指定 --pool，不能与 --all-pools 或 --session-token 组合。

每池只运行一个 warm controller，服务端没有 spawn lease，多个 controller 可能短时重复创建。Kubernetes 新部署使用官方 k8s-workers 模板，旧 Cursor operator/WorkerDeployment 已弃用。

空闲释放

专题页说明 --idle-release-timeout 默认 3600 秒，设 0 禁止按空闲释放；通用 CLI 表仍写默认 0，属于官方版本差异。部署时建议显式指定所需值：

agent worker --pool my-pool --idle-release-timeout 600 start

会话结束后等待 follow-up，收到新消息则重新计时；到期退出码 0，交给 supervisor 回收。API release claim 是立即释放的另一操作，轮次正在用 worker 时会拒绝。

恢复工作区

无 hibernation 时，后续消息可能拿到新机器，旧工作区不自动迁移。需要保存现场时由基础设施 snapshot，并为 pool 配置 workerReadyTimeoutSeconds 重连窗口，默认 0 表示立即重新分配。

controller 可识别 claimed_offline 及 claimedWorkerId/wakeTimeoutMs，以同一 worker ID 恢复；无法恢复则 release claim，或等待窗口到期重新排队。

自定义控制器与监控

队列 list 返回 streamCursor，再以相同 filters 接 SSE；cursor 在签发 list 后 5 分钟到期，410 Gone 时重新 list。事件为尽力投递，list 才是纠正状态的依据。

worker 的 --management-addr 可暴露 /healthz、/readyz、/metrics。监控连接、active session、重试和最后活动时间，结合队列深度判断容量，不能只看团队总 worker 数。