pi-agent-squad 0.8.4 → 0.8.5

package/README.md

@@ -64,6 +64,8 @@ metadata and does not sandbox filesystem access.
 ## Features
 
 - **Delegation**: `subagent` tool (sync / background `async:true`); background results are injected into the main session when done.
+- **Durable background ledger**: key background lifecycle snapshots are stored as TUI-only custom entries on the current Pi session branch.
+- **Recovery and explicit retry**: reopening a session restores background history, marks stale work interrupted, repairs pending result delivery, and supports `/subagent-retry <runId>` without automatically rerunning old work.
 - **Real-time two-way**: subagent<->main and subagent<->subagent, via file channel + an active-run registry that covers both direct runs and resident RPC processes.
 - **Non-blocking**: background tasks do not occupy the main session.
 - **Adaptive orchestration is opt-in**: `/orchestrate on` enables main's discretion to delegate based on speed, quality, context management, independent judgment, and parallel progress while weighing latency, over-analysis, misunderstanding, duplication, and integration risk.
@@ -178,6 +180,39 @@ from the visible transcript:
   `triggerTurn: true` and `deliverAs: "steer"`, preserving the former
   synthetic-user-message behavior without inheriting `userMessageBg`.
 
+## Background task persistence and recovery
+
+Background task lifecycle state is append-only in the current Pi session. The
+plugin writes `agent-squad-task-state` snapshots for `starting`, `running`,
+`completed`, `failed`, `cancelled`, and `interrupted` transitions. These custom
+entries do not enter LLM context.
+
+When the same session is reopened, the plugin reconstructs the ledger from the
+**active branch**. The last valid snapshot for each run is authoritative.
+Malformed entries and unknown schema versions are ignored independently.
+
+- A `starting` or `running` task owned by an older plugin runtime is changed to
+  `interrupted`; it is never assumed alive from a PID or child-session path.
+- Interrupted, failed, and cancelled work is **not** automatically rerun. Use
+  `/subagent-retry <runId>` to create a new background run with a new run ID and
+  address. The new ledger entry records `retryOf`.
+- Completion is persisted before its result is injected. If a completed result
+  was not delivered before shutdown, reopening the session schedules recovery
+  delivery after session initialization.
+- Each completed result uses `agent-squad-result:<runId>` as its stable
+  `deliveryId`. Recovery scans durable custom-message entries for that ID before
+  sending and again immediately before delivery, preventing duplicate result
+  messages across crash windows.
+- `/subagent-status` merges current live tasks with bounded current-branch
+  history and distinguishes delivered from pending completed results.
+
+The ledger stores bounded metadata and result/error summaries, not complete
+child transcripts, credentials, controllers, promises, streams, or callbacks.
+Background child Pi sessions remain separate and retain their full transcript;
+the ledger stores only the bounded summary plus the child session file path.
+This version does **not** revive dead OS processes, take over processes from an
+older runtime, daemonize subagents, or provide cross-runtime process keepalive.
+
 ## Architecture
 
 ```
@@ -210,6 +245,10 @@ subagents/
 |-- message.ts      # generic messaging (file channel + send/reply/read + main-side router)
 |-- session.ts      # common interactive session-handle interface
 |-- session-ui.ts   # focused overlay for live transcript + interactive input
+|-- task-state.ts   # durable schema, validation, and branch reconstruction
+|-- task-recovery.ts # stale-run and undelivered-result reconciliation planning
+|-- task-delivery.ts # delivery IDs, durable dedupe, and recovery outbox
+|-- task-status.ts  # bounded live + persisted status formatting
 |-- orchestrator.md # main-agent adaptive delegation prompt (enabled with /orchestrate on)
 `-- README.md
 ```
@@ -230,6 +269,9 @@ pi --append-system-prompt ~/.pi/agent/extensions/subagents/orchestrator.md
 "Use subagent async=true, agent=actor, task=..."     # explicit background delegation
 "Use subagent agent=reviewer timeoutSeconds=120 ..." # override the default 6h task timeout (only when the user asked)
 "Have reviewer review the recent changes"            # main agent delegates to reviewer
+
+/subagent-status                 # live tasks plus bounded current-branch history
+/subagent-retry <full-run-id>    # explicit retry; creates a new run id/address
 ```
 
 Main is not required to follow a fixed planner → actor → reviewer chain. It may