Orchestration (M4)
Persistent Tasks (Dev Servers)
Run long-lived development servers and watchers concurrently with prefixed logs and clean teardown.
Mark long-lived tasks such as next dev, API servers, or watch bundlers with persistent=True (persistent: true in TypeScript).
Defining Persistent Tasks
Python (@tool(persistent=True))
@tool(name="docs.dev", marks=["dev"], depends=["build"], persistent=True)
def dev_docs(ctx: ToolContext) -> None:
"""Start the docs dev server."""
ctx.run(["bun", "run", "--cwd", "apps/docs", "dev"])TypeScript (persistent: true + ctx.spawn)
Use await ctx.spawn(...) in TypeScript persistent tasks so multiple servers/watchers run non-blockingly in the same Bun or Node.js process and respect ctx.signal cancellation:
export default tool(
{
name: "docs.dev",
marks: ["dev"],
depends: ["build"],
persistent: true,
description: "Start the docs dev server.",
},
async (ctx) => {
await ctx.spawn(["bun", "run", "--cwd", "apps/docs", "dev"]);
},
);Orchestration & Guarantees
- Non-persistent prerequisites first: A persistent task may
dependon one-shot tasks (such asbuild), which finish before the persistent tasks start. - No dependents on persistent tasks: No task may
dependon apersistenttask (check/ graph validation fails with exit code2). - No caching: Persistent tasks cannot enable
cache. - Automatic concurrency & prefixed output: Running
tasknest run --mark devautomatically allocates concurrent workers for all persistent tasks in the plan and prefixes each streamed line with[<task_name>]. Passing an explicit--jobssmaller than the number of persistent tasks fails fast with exit code2. - Coordinated teardown: Pressing
Ctrl+C(SIGINT/SIGTERM), or a failure in any persistent task, aborts all sibling persistent tasks and terminates their child process groups cleanly. - Incompatible with
tasknest watch:tasknest watchruns discrete DAG rebuilds and rejects persistent targets with exit code2.