pi-impatient-tasks

A pi extension that forces every shell command into a tracked background process and makes sure the agent never hangs waiting on a command, never ignores a runaway task, and never gets a dozen wake-ups when five commands finish at once.

Architecture, state machines, and sequence diagrams are documented with Mermaid graphs in design.md.

What it does

• Blocks bash and powershell tool calls. The block reason routes the agent to it_spawn.
• it_spawn requires a patience (seconds). It spawns the command detached and streams stdout/stderr, unbounded, to an absolute log file.
• Short commands are synchronous. it_spawn returns when the command finishes or when its patience elapses. Anything that finishes inside the window returns its result inline like a normal shell tool; anything longer becomes a background task.
• Runaway tasks become overdue. When patience elapses the task state changes from running to overdue. The agent must then choose: it_set_patience (keep watching with a new window, returns immediately) or it_kill (stop it).
• The agent cannot end a turn while a task is overdue. agent_settled re-delivers the pending set until the agent chooses. After 5 unanswered prompts the tasks are extended automatically to 30 minutes so the loop is always bounded.
• Events are level-triggered and batched. State changes mark a task dirty; a fixed 2 s tick reports the current state of every dirty task as one message, only while the agent is idle. A task that went overdue and then completed inside the same window is reported once, as completed. Kills are silent.
• ESC enters silence mode. If you press ESC while a task is still running, the footer badge turns blue (instead of yellow) and task events — completed, failed or overdue — are buffered but never wake the agent. They are delivered only after you prompt the agent yourself. alt+s toggles the same mode by hand, so you can silence events without leaving a task running.
• Multiple tasks can run concurrently.

Reading output

Every it_spawn result, event message, and it_status reports the absolute log path. Read that file directly; it is not truncated or size-capped. Agent-facing tails are truncated exactly like pi's native bash tool — the last 2000 lines / 50 KB — with the same [Showing lines X-Y of Z. Full output: <path>] notice on exceed.

Every elapsed time is shown against the task's patience as elapsed / patience (e.g. 12s / 30s), so the two always travel together.

Tools

Tool	Purpose
it_spawn	Start a command. command, patience (required, 1–86400 s), optional name, shell (auto/bash/powershell), timeoutSecs. Blocks until the command finishes or goes overdue.
it_status	List tasks, or inspect one by id (status, elapsed, pid, patience, absolute log path).
it_set_patience	Keep a running/overdue task alive with a new patience window. Returns immediately.
it_kill	Stop a running or overdue task. Silent.

Each task has a process-local short id (#1, #2, ...) alongside its durable hex id. it_status, it_set_patience, and it_kill accept either form: #3, 3, or 1b1328. The human /kill command takes short ids only.

Human UI

• Footer: animated bright-yellow braille badge ⠋ 1 task running while anything is running or overdue. In silence mode (ESC while a task is still running) it turns blue and reads ⠋ 1 task running · silent; buffered task events are held until you prompt the agent again.
• alt+k — kill all tasks (same as /kill with no id).
• alt+s — toggle silence mode (the mode ESC enters): while silent, completed, failed and overdue events are buffered instead of waking the agent. Toggling it off delivers whatever was buffered.
• /tasks — open the panel: a scrollable task list (↑/↓) sorted by status with running tasks first, Enter for a task's details with a live output tail, k to kill, o to mark a task overdue, t to set its due time (type a number of seconds, Enter applies, Esc cancels), and s to toggle the sort between status and id. k, o and t work from both the list and the details view.
• /kill [id] — stop a task by short id; with no id, stop every task.

Install

Auto-discovered from ~/.pi/agent/extensions/pi-impatient-tasks/index.ts. Run /reload in pi (or restart) to load it.

Test

node test/run.mjs

The harness loads the real extension through jiti with pi's module aliases and a mock pi API, runs real shell commands (bash and, on Windows, PowerShell), and asserts on the state machine, patience/overdue cycle, the settle gate, event flushing, log capture, and UI wiring.