---
status: resolved
claimed-by: "019fba91-eabf-76ae-b086-a37ac061d6e8"
claimed-at: "2026-08-01T14:05:41-04:00"
completed-at: "2026-08-01T14:13:54-04:00"
parent: "[[027-pi-subagents-implementation-spec-task]]"
blocked-by:
  - "[[046-pi-subagents-minimal-tracer-bullet-task]]"
tags:
  - ticket/task/afk
---

# Add cancellation, timeout, and shutdown lifecycle controls

## Question

Extend the supervisor so cancellation, timeouts, process failures, and parent shutdown cleanup use the same tracked lifecycle path without leaking child processes.

## What to build

Make child lifecycle robust after the minimal spawn path exists.
The supervisor should own cancellation, startup and runtime timeout behavior, process failure handling, and shutdown cleanup.
Cancellation must be idempotent and should cooperate with Pi RPC before escalating to process-tree termination.

## Acceptance criteria

- [x] Cancelling a running subagent is idempotent and reaches `cancelled`.
- [x] Startup and runtime timeout paths reach `timed_out`.
- [x] Child process exit before semantic settlement reaches a failure state with diagnostics.
- [x] Parent session shutdown cancels supervised children.
- [x] Lifecycle tests cover abort, process close, timeout, and repeated cancel calls.

## Implementation Notes

Use `agent_settled` as semantic completion.
Use process close for resource cleanup after settlement.

Resolved in branch `pi-subagents-tracer-bullet`, commit `4e6baed`.
Cancellation is idempotent, sends RPC `abort` cooperatively with a bounded grace period, then terminates the child process group on Unix.
The supervisor now tracks startup and runtime timers, clears timers on terminal states, marks shutdown cancellation as `cancelled`, and ignores later lifecycle events once a terminal state is reached.
Lifecycle unit tests cover repeated cancel, startup timeout, runtime timeout, process failure, shutdown cleanup, and cancel-after-completion.
Verification: `nix shell nixpkgs#tsx -c tsx --test modules/agents/pi/extensions/subagents/supervisor.test.ts`, managed extension derivation build, Pi RPC command smoke, live repeated cancel smoke, and `nix flake check`.