EN 中文

# Background Jobs — Long-Running Tasks

# 后台任务 — 长任务跟踪

Push long builds, test suites, and dev servers to the background and check progress with the monitor tool.

把 build / 测试套件 / dev server 丢到后台，再随时查看进度——不再被一条命令卡死整轮。

Background jobs are session-scoped — they live and die with the current seek session. No persistence across restarts. For persistent scheduled jobs, see Cron. 后台任务随当前 seek 会话生死，不写盘、不跨重启。持久化定时任务见 Cron。

## Launch a Background Job

## 启动一个后台任务

Pass `run_in_background: true` to the bash tool. It returns a handle `bg-N` immediately instead of blocking:

给 bash 传 run_in_background: true，它立即返回句柄 bg-N：

    bash(command="go build ./...", run_in_background=true)
    → [bg: started bg-1] $ go build ./...
      Track with: monitor(job="bg-1", action=poll|wait|kill).

- No timeout — background mode ignores `timeout_ms`. The job runs until it exits, is killed, or the session ends.
- 后台模式下 timeout_ms 被忽略——任务一直跑到退出、被杀、或会话结束。
- Best for: long builds, full test suites, dev servers, file watchers.
- 适用场景：长 build、完整测试套件、dev server、文件 watcher。

## Track with `monitor`

## 用 monitor 跟踪

### `poll` (default) — incremental output since last check

### poll（默认）——看自上次以来的新输出 + 状态

    monitor(job="bg-1")
    → [bg-1: running, elapsed=12s]
      <new output since last poll>

Cursor is server-side — each poll returns only incremental output. No new output = `(no new output)`.

游标是服务端记的——每次 poll 只给你增量输出。

### `wait` — block until exit / match / timeout

### wait——阻塞直到完成 / 命中 / 超时

    monitor(job="bg-1", action=wait, timeout_ms=60000)
    → [bg-1: exited code=0, elapsed=43s]
      <final output>

Three exit paths: task exits, `until_regex` matches ("Listening on" for a dev server), or timeout.

三条退出路径：任务退出、until_regex 命中（如 dev server 的 "Listening on"）、超时。

Cancelling a wait (Esc) stops observing but leaves the job running.

取消 wait（Esc）停止观察但让任务继续跑。

### `kill` — terminate

### kill——终止

    monitor(job="bg-1", action=kill)
    → [bg-1: killed, elapsed=67s]

## Lifecycle

## 生命周期

- Jobs live until: they exit, you kill them, or the session ends.
- 任务一直存活到：自己退出、被 kill、或会话结束。
- Not persisted across restarts — bg jobs never survive a session restart.
- 不跨重启——后台任务不会在会话重启后存活。
- Up to N concurrent jobs (ring buffer). Oldest job is evicted on overflow.
- 最多 N 个并发任务（环形缓冲），溢出时淘汰最老的。

Design: PRD feature-bash-monitor.md

设计文档：PRD feature-bash-monitor.md