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 inprogress/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 MCPstop_job(ordetached-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 → readprogress, 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
startonce. If JSON saysalready-running, do not start again.- Loop
wait(use--timeout-ms 15000for a livelier pane). The human should see working in the side column from the wait JSON — do not also dump the log in chat. - After each slice, the same log pane appends
delta. Optional:present_artifactthe same id for a custom title. - On
ok, present once more (status=ok, lastdelta) and finish the task. Onfailed, fix from the log. - Stop when the job is hanging, buffering forever, watching the wrong thing, or you already have the answer. MCP
stop_job(same id, optionalreason) ornode 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
skill-improver
When a miss will recur — you made it twice, or a person told you the rule — write the lesson into the skill before the turn ends. One sentence, in the same change. Run in the turn, not on a schedule.
release
暂无简介
long-running
暂无简介
worktree-install
Reinstall dependencies in a Sideboard worktree after merge-from-main or a lockfile change. Use when `pnpm install` hangs, several worktrees install at once, or a native build is outside the permitted directory.
review
Merge-readiness review for this repository. Use when reviewing a PR, worktree diff, or Sideboard Review (Approve / Approve with nits / Request changes).
release
Cut a Sideboard version. Default: bump, README/changelog, commit, merge, then push/retarget the `v*` tag so `.github/workflows/release.yml` publishes npm (OIDC) and the signed Mac desktop. No workflow_dispatch. Do not pack Electron in a worktree turn. Use for electron release, desktop release, pnpm release, or “I’ll publish npms.”