القائمة
Use when adding a long-running background task to Canary Lab (anything that shouldn't block a REST request or the UI) — coverage generation, port-ification, spec/eval generation.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when creating or extending a Canary Lab feature by hand — "create a feature for X", "add test cases to <feature>", "capture the env files", "switch the feature's branch" — through the author MCP tools (create_feature, capture_feature_env_files, write_envset, start/update/apply_external_draft, get_feature_repo_status, checkout_feature_repo_branch). For docs/PRD/coverage use canary-lab-coverage; for full onboarding of a bare repo use canary-lab (flight).
Use when working the Canary Lab semantic coverage ledger — "what's actually tested?", "map coverage for <feature>", "refresh the PRD summary", "close the coverage gaps", "add this plan/spec to the feature docs" — through the coverage MCP tools (write/list/delete_feature_doc, start/submit_external_summary, start/submit_external_coverage, get_feature_coverage, clear_prd_summary). For writing new tests use canary-lab-author.
Use when exporting a Canary Lab run as an evaluation — "export the evaluation", "produce the report for run 7cvh", "give me the evaluation archive", "review what the run proved" — through the export MCP tools (start/submit_external_evaluation_export, get/list/download_evaluation_export). The run must be terminal (passed, failed, or aborted).
Use when making a Canary Lab feature concurrency-ready — "portify <feature>", "make the ports injectable", "why can't these run concurrently", "undo the portification" — through the portify MCP tools (start/submit_external_portify, get_portify, save_portify, cancel_portify, remove_portification, list_portify_status).
Use when running or healing an EXISTING Canary Lab feature locally — "run <feature>", "fix the failing run", "rerun 7cvh", "drive the heal loop" — through the repair MCP tools (start_run, wait_for_heal_task, signal_run, get_heal_context, pause_run, cancel_heal, abort_run). Fix failing runs by editing app/service code, not tests. For end-to-end onboarding of a new repo use canary-lab (flight); for deployed-environment checks use canary-lab-verify.
Use when the user wants Canary Lab to take a product repo end to end — "test this app", "onboard this repo", "run a flight", "evaluate what I just built" — through the flight pipeline (start_flight / get_flight / respond_flight_checkpoint over MCP). One conducted background pipeline goes from bare repo(s) to a green, covered, healed run ending in an evaluation export. For a single capability use the focused skills instead — canary-lab-run (run + heal), canary-lab-verify (deployed-env verification), canary-lab-author (create feature + specs), canary-lab-coverage (PRD summary + coverage ledger), canary-lab-portify (concurrency-readiness), canary-lab-export (evaluation export).
| name | cl_async-task-ux |
| description | Use when adding a long-running background task to Canary Lab (anything that shouldn't block a REST request or the UI) — coverage generation, port-ification, spec/eval generation. |
Long-running work (agent runs, multi-second generation, double-boot verification) must NOT block a REST handler or freeze the UI. Canary models it as a background job: start returns immediately, the job persists to disk, the UI/MCP poll it, and a server restart recovers it. Get this contract right by copying an existing impl — don't invent a new lifecycle.
| Subsystem | Store | Runner / lifecycle |
|---|---|---|
| Verified Coverage jobs | apps/web-server/src/features/coverage/logic/coverage/jobs/store.ts | …/jobs/runner.ts (startCoverageJob) |
| Port-ification | apps/web-server/src/features/portify/logic/runtime/store.ts | …/portify/* + src/features/portify/routes/portify.ts |
Coverage jobs are the smallest complete example — read those two files first.
running
manifest, kicks off the work detached (no await on the driver), and returns
202 with the manifest. The driver streams progress into the manifest and
flips it to done / failed when it settles.<logs>/<kind>/<id>/…json
index.json), never only in memory. save() writes atomically (tmp +
rename) then emits a changed event (the WS/poll push point). Reads come
straight off disk so a fresh process sees history.store.reconcileInterrupted(now) to flip
any job left running by the dead process to aborted — otherwise it shows as
live forever AND wedges the single-flight lock. Wire this next to the other
store reconciles in server.ts.GET …/jobs/:id)
plus a per-feature list (GET …/:name/jobs). The dialog/pill re-attaches to a
running job by polling that id — closing the UI never kills the work.feature + kind): store.activeFor(...) → throw a typed
conflict (409). UI disabling is cosmetic, never the guard — two tabs, an
agent, and the UI all hit the same on-disk index, so the server must be the lock.Every async capability ships on BOTH the UI (REST) and MCP, against the same store
(see cl_add-mcp-tool). Start + poll + list at minimum; accept/reject-style
follow-ups if the job parks for human input. MCP tools may construct a fresh store
over the same logsDir — the lock is the on-disk index, not the instance.
| Mistake | Consequence |
|---|---|
await-ing the driver in the start handler | Request blocks — the whole point is lost |
| Single-flight enforced only by disabling the button | A second tab / an agent / a restart races a duplicate job |
Skipping reconcileInterrupted on boot | Crashed jobs show as live forever and hold the lock |
| In-memory-only state | A restart loses history and re-openability |
| Non-atomic manifest writes | A crash mid-write corrupts the job; readers throw |