AGENT SKILL

long-running

Detach and wait on any long worktree job (pack, notarize, full test, deploy) so a new chat turn does not SIGTERM it, and the human does not have to poll. Use when a command may run more than ~30s, or the user mentions wait / status / aborted builds. Do not use for a server that should stay up (a local site preview). Stop that job instead of waiting.

License 许可
Apache-2.0
最近更新
2026-11-15
Stars
★ 4
Forks
0

01 前言 Front Matter

name
long-running
description
Detach and wait on any long worktree job (pack, notarize, full test, deploy) so a new chat turn does not SIGTERM it, and the human does not have to poll. Use when a command may run more than ~30s, or the user mentions wait / status / aborted builds. Do not use for a server that should stay up (a local site preview). Stop that job instead of waiting.

03 SKILL.md 正文

Long-running jobs

Sideboard ships this method to every worktree agent (/long-running is a product skill). This repo copy adds Mac-release notes below. A workspace skill with the same name wins over the bundled copy.

A Sideboard or Cursor worktree turn SIGTERMs the agent shell (and its process group) when the user sends another message or the turn is interrupted. block_until_ms: 0 is not enough — the child stays in that group.

Do not ask the human to check back. Detach, then wait in 45s slices (same idea as MCP wait_for_turn) until stillRunning is false. Do not end the turn after starting a job — a native CLI Task or bash notify does not resume a Sideboard chat (Claude, Cursor, Codex, OpenCode).

A process that is supposed to stay up is not this skill. Do not start a static file server, preview server, or anything else that never exits (python -m http.server, a dev server). stillRunning stays true, and the orchestrator will not let the turn end. To show the local marketing page, open site/index.html (side column or a browser). If a stay-up server is already a detached job, stop that id and continue. Do not loop wait on it.

Tool

Prefer the helper path from the Sideboard playbook (absolute node "…" start). In this repo, scripts/detached-job.cjs is the same file.

# Start (exits in ~1s; job survives this turn)
node scripts/detached-job.cjs start <id> -- <command> [args...]

# Wait — returns within ~45s even if the job is still going
node scripts/detached-job.cjs wait <id>

# Block until the process exits (humans / a turn that will not be interrupted)
node scripts/detached-job.cjs wait <id> --until-done

node scripts/detached-job.cjs stop <id> [--reason TEXT]
node scripts/detached-job.cjs status <id>
node scripts/detached-job.cjs ui <id> [--title TEXT] [--out FILE]

<id> is kebab-case (mac-release, core-test, fly-deploy). State is .context/.sideboard/detached-jobs/<id>/ (local scratch).

Wait JSON:

  • stillRunning: true → exit 2 → call wait again. Progress is in progress / phase. Do not start a second job. Do not ping the user. If it is hanging, producing no useful output, or doing the wrong thing, call MCP stop_job (or detached-job.cjs stop) instead of looping forever.
  • ok: true → exit 0 → continue the rest of the task (README, commit, deploy next step).
  • failed: true → exit 1 → read progress, fix, start once.
  • stopped: true → you ended it. Present the last delta (status=failed) and decide the next step.

Sideboard UI (append-only log)

The side column is the live view. wait_for_job / stop_job (and shell detached-job wait JSON) open a type=log pane automatically (artifact_id = job id, content = delta). You may still call present_artifact type=log for a custom title. Each update appends — send only delta, not the full log and not HTML.

present_artifact
  title: <short title>
  type: log
  artifact_id: <id>
  content: <wait.delta>          # new lines only; empty is ok
  status: running | ok | failed  # from wait.status
  phase: <wait.phase>

After start, the first wait opens the pane (status=running). Do not dump the log in chat. Do not also fence HTML.

detached-job.cjs ui still writes a snapshot HTML file for debugging. Prefer type=log.

If you started via release-mac-detached.js (legacy pid/log):

node scripts/detached-job.cjs ui --pid-file apps/desktop/release/release.pid --log-file apps/desktop/release/release.log --ok-pattern RELEASE_BUILD_OK --title "Mac pack"

Ad-hoc pid/log (legacy or another tool’s files):

node scripts/detached-job.cjs wait --pid-file FILE --log-file FILE [--ok-pattern TEXT]

Agent loop

  1. start once. If JSON says already-running, do not start again.
  2. Loop wait (use --timeout-ms 15000 for a livelier pane). The human should see working in the side column from the wait JSON — do not also dump the log in chat.
  3. After each slice, the same log pane appends delta. Optional: present_artifact the same id for a custom title.
  4. On ok, present once more (status=ok, last delta) and finish the task. On failed, fix from the log.
  5. Stop when the job is hanging, buffering forever, watching the wrong thing, or you already have the answer. MCP stop_job (same id, optional reason) or node scripts/detached-job.cjs stop <id>. Do not stop a pack/test/deploy that is clearly making progress.

Never tell the user “say status when it’s done.” You wait — unless you decided to stop.

Connector CLIs (Vercel, Supabase, Sentry, PostHog)

Huge --json / --expand dumps crash any worktree agent mid-turn (Claude / Cursor / Codex / OpenCode). On Cursor the chat shows the packaged bundle (file://…/cursor-runtime/…/@cursor/sdk/dist/esm/index.js then minified importas e from"@bufbuild/protobuf"). Write CLI/HTTP output to .context/cli/ (not .context/attachments/), then read a slice. Tight window first; one query at a time; jq only the fields you need. After the error line, stop fetching. If a raw shell is still going at ~40s with empty output, detach or stop_job — piping to head does not help.

PR checks (only if a goal is given)

Do not watch after every push. If the user gave a goal (Greptile 5/5, CI green, until checks pass), wait the same way:

node scripts/detached-job.cjs start pr-checks -- gh pr checks --watch

On miss, fix, commit, push, and watch again until the goal is met or you are blocked. Do not ask the human to poll. Do not merge unless asked.

Mac desktop release

Default: push/retarget the v* tag and watch Actions — do not pack locally. Full steps: .claude/skills/release/SKILL.md.

node scripts/detached-job.cjs start gha-release -- node scripts/watch-gha-run.cjs <run-id>
node scripts/detached-job.cjs wait gha-release

Do not gh run watch (full TTY reprint every 3s; stalls the log pane).

04 同仓库更多 Skills