**Skill**: [Autonomous Agent Operations](../SKILL.md)

# Pueue Command Semantics

Critical knowledge about pueue behavior that agents must understand before operating on job queues.

## `pueue restart` Creates New Tasks

This is the most dangerous misunderstanding:

```bash
$ pueue restart 42
# Does NOT restart task 42 in-place
# Creates NEW task (e.g., task 100) with identical command
# Task 42 stays as Done/Failed
# Task 100 is Queued

$ pueue restart --in-place 42
# Actually restarts task 42 itself
# No new task created
# Task 42 goes back to Queued status
```

## `pueue status --json` Payload Scales with Total Tasks

The JSON output includes ALL tasks, including Done/Failed/Cleaned. After `pueue clean`, done tasks are removed, shrinking the payload. But `pueue clean` only removes tasks in the "Done" state — "Failed" tasks are also "Done" and get cleaned too.

## Group Parallelism is per-Group, not Global

`pueue parallel 8 --group p1` sets p1 to 8 concurrent. If p2 is also at 8, total concurrent is 16. Each group is independent.

## `pueue kill` vs `pueue remove`

- `pueue kill TASK_ID`: Sends SIGKILL to running task, marks as Done/Killed. Task stays in queue.
- `pueue remove TASK_ID`: Removes task from queue entirely. Only works on non-running tasks.
- `pueue clean`: Removes all Done/Failed/Killed tasks from queue.

## Exit Codes

| Exit Code | Meaning           | Cause                                |
| --------- | ----------------- | ------------------------------------ |
| 0         | Success           | Task completed normally              |
| 1         | Application error | Python/Rust exception, bad arguments |
| 130       | SIGINT            | Ctrl-C or `pueue kill` with SIGINT   |
| 137       | SIGKILL / OOM     | cgroup MemoryMax exceeded            |
| 143       | SIGTERM           | Graceful shutdown requested          |

## Task Lifecycle

```
Stashed → Queued → Running → Done (Success/Failed/Killed)
                     ↓
              pueue restart (default)
                     ↓
              NEW task created (Queued)  ← DANGER: original stays as Done
```
