Stopping or deleting a project cancels its owned work and waits for cleanup. A stop retains
completed artifacts. Deletion removes project files only after owned work settles; a reported
cleanup failure returns DEPENDENCY_CLEANUP_FAILED (HTTP 409) and keeps those files.
Other projects and app-owned shared services keep their own lifetimes.
sequenceDiagram
participant API as Project API
participant Workflow
participant Work as Owned work
participant Files as Project files
API->>Workflow: stop(project)
Workflow->>Work: Abort caller signals, including queued work
Work->>Work: Close resources and await owned process cleanup
Work-->>Workflow: Settle tasks and playback preparation
alt Cleanup succeeded
Workflow-->>API: Stopped
opt Delete requested
API->>Files: Remove project files and saved records
end
else Cleanup failed
Workflow-->>API: DEPENDENCY_CLEANUP_FAILED
Note over API,Files: Keep project files
end
Workflow tracks preparation, preview/full builds,
refinement copying, auxiliary project work and playback preparation. Its stop() aborts work,
awaits task and playback settlements, checks cleanup failures, then reapplies cancelled state.
Queued work receives the caller's signal and can leave the queue before execution.
The API awaits this lifecycle for cancellation and deletion. During
deletion it rejects new project requests with PROJECT_DELETING, waits for pending full-build
preparation, and removes data only after stop succeeds. Completed job status does not exempt
its background playback preparation from cancellation. Cancelled playback work is not
resumed automatically after restart.
| Resource | Owner and cleanup |
|---|---|
| Claude and Codex SDK subprocesses | Both adapters use withProcessScope; cancellation reaches the SDK and remaining owned subprocess trees are terminated. |
| Reference browser and native recorder | Browser launch uses createProcessScope; native capture closes its MCP connection and owned helpers. |
| Commands, rendering, installation and audio | Caller signals reach the shared command/process-tree helpers; cancellation waits for cleanup. Serialized speech requests wait for worker cleanup before starting the next request. |
| Editable ZIP downloads | Workflow.projectDependency registers the export. Project stop or client disconnect aborts it and closes its streams. |
| Remote capture | The client sends session DELETE on cancellation with an independent, bounded cleanup signal. The worker aborts its session, closes its browser and waits for queued/active actions before removing the workspace. |
| Shared proxy and per-project SDK-home setup | The proxy is app-owned. SDK-home setup is shared only by callers within the same project. Cancelling a caller stops its wait without interrupting another caller; app shutdown handles shared proxy cleanup. |
process-scope.ts records child-process handles
through Node's child_process diagnostics channel, with ownership isolated by async context.
Before forwarding parent cancellation, it snapshots descendant PIDs so immediate SDK shutdown
does not lose helper ownership. SDK shutdown receives 2.5 seconds before remaining owned
process trees are terminated. Closing a scope also drains late-created children.
process-tree.ts shares termination across SDK scopes,
commands, recording and speech. It uses captured PIDs and explicitly owned process groups,
never application-name matching. Unix cleanup escalates from graceful termination to forced
termination and checks for survivors. Windows uses taskkill /T /F; Windows runtime behavior
has not been verified on the macOS development host.
This ownership model tracks children created inside the scope and their captured descendants; it is not a system-wide process supervisor. Process enumeration itself runs outside the owned scope so cleanup does not register its own helper as another dependency.
Concurrent builds share a recording lock on the recording host. It covers native recording and saving, while native review, editing and export can continue after release. Lock contention is cancellable and does not guarantee FIFO ordering. See shared recorder ownership for timing, stale-lock recovery and diagnostics, and worker setup for remote capture.
- Pass the caller's
AbortSignalthrough queues, SDK/MCP requests, downloads and commands. - Await resource shutdown in
finally; do not finish the owning task while cleanup is pending. - Use
withProcessScopefor SDK turns, orcreateProcessScopewhen resource creation and closing have separate lifetimes. Use the shared process-tree helper for explicit child handles. - Register project work outside the normal build task through
Workflow.projectDependency. - Give cleanup requests their own bounded signal when the original caller is already aborted.
- Keep app-shared services outside project scopes. Do not detach project-owned work without a tracked owner and settlement promise.
- Propagate cleanup failures so deletion can retain files rather than report false success.
Automated coverage includes queue cancellation, command cleanup, process trees, scope isolation, both installed SDK cancellation paths, stop/delete and shutdown, playback preparation, worker transport and project exports. SDK cancellation probes use local dummy executables; they do not make model API calls.
Interactive native desktop-recording tests are not part of the unattended suite. The local fixture tests above cover process ownership, cancellation, worker transport and export handling; they do not establish that screen recording works on a particular desktop. Verify actual native recording separately on the target desktop before relying on it.
Project-local runtime files explains filesystem ownership and why native recorder locks and app-owned services remain explicitly shared.