@maxiaochao/pi-toolkit 0.11.6 → 0.11.8

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 2026-10-14 - v0.11.8
+
+- bundle openai-account-pool v0.1.0: add OpenAI Codex account pooling with safe quota failover and live usage status
+- bundle the OpenAI Account Pool package
+- Add `@maxiaochao/pi-openai-account-pool` with `/codex_pool`, which pools several ChatGPT Plus/Pro logins behind `openai-codex` and continues a request on the next usable account when one proves it is out of quota.
+- Let `node scripts/capture-package-media.mjs <slug>` regenerate media for selected packages, and render Chinese output with a CJK font.
+
+## 2026-10-13 - v0.11.7
+
+- bundle herdr-subagents v0.5.0: simplify lifecycle to one report-first state machine with strict serial and bounded read-only parallel execution
+
 ## 2026-10-13 - v0.11.6
 
 - add a Why column to the child package table in README

package/README.md

@@ -33,7 +33,8 @@ Restart Pi after updating. The `todo` tool and widget will no longer load. `pi u
 | [pi-todo](packages/todo/README.md) | Optional branch-local execution plan UI; not bundled with pi-toolkit | `pi install npm:@maxiaochao/pi-todo` | `pi update npm:@maxiaochao/pi-todo` | I don't recommend this for now, as both OpenAI and Claude Code official have stated that strong models are currently cumbersome in Todo |
 | [pi-cache-export](packages/cache-export/README.md) | Tau-aligned interactive cache dashboard for Pi sessions | `pi install npm:@maxiaochao/pi-cache-export` | `pi update npm:@maxiaochao/pi-cache-export` | Because I watched the cache video on @alejandro.ao YouTube, which has a Tau style page for viewing cache |
 | [pi-codex-edit](packages/codex-edit/README.md) | Codex-harness `apply_patch` routing for selected GPT models | `pi install npm:@maxiaochao/pi-codex-edit` | `pi update npm:@maxiaochao/pi-codex-edit` | The core lies in the fact that the Codex model is naturally good at apply_patch, and the model is trained on this during training. However, hash-based in-context patch schemes have high token costs and complexity |
-| [pi-herdr-subagents](packages/herdr-subagents/README.md) | Interactive Herdr Pi Agents with bounded concurrency, direct navigation, and recovery | `pi install npm:@maxiaochao/pi-herdr-subagents` | `pi update npm:@maxiaochao/pi-herdr-subagents` | I wanted several Agent tasks to run at the same time while each one stays a real interactive Pi session in its own Herdr pane, and the main conversation only receives short summaries instead of every child's full transcript |
+| [pi-herdr-subagents](packages/herdr-subagents/README.md) | Visible Herdr Pi Agents coordinated by a small task state machine | `pi install npm:@maxiaochao/pi-herdr-subagents` | `pi update npm:@maxiaochao/pi-herdr-subagents` | I wanted simple serial or bounded-parallel dispatch while each task stays a real interactive Pi session in its own Herdr pane, and the main conversation only receives short summaries instead of every child's full transcript |
+| [pi-openai-account-pool](packages/openai-account-pool/README.md) | Several ChatGPT Plus/Pro logins behind `openai-codex`, switching accounts on a proven quota limit | `pi install npm:@maxiaochao/pi-openai-account-pool` | `pi update npm:@maxiaochao/pi-openai-account-pool` | One `/login openai-codex` credential overwrites the previous one, so hitting the subscription limit meant logging in again by hand mid-task; this keeps the accounts I authorized side by side and continues the same request on the next usable one |
 | [pi-scheduler](packages/scheduler/README.md) | Session-scoped interval prompts with Agent and `/schedule` controls | `pi install npm:@maxiaochao/pi-scheduler` | `pi update npm:@maxiaochao/pi-scheduler` | I don't recommend this, it's just that it sends messages to the main session at loop intervals |
 | [pi-worktree](packages/worktree/README.md) | Worktree CLI, current-session switching Extension, and agent skill | `pi install npm:@maxiaochao/pi-worktree` | `pi update npm:@maxiaochao/pi-worktree` | In addition to the basic worktree CLI + skill, what can be achieved is to directly switch to the worktree path in the main conversation to continue the task conversation after communicating the requirements in the main conversation |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.11.6",
+  "version": "0.11.8",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
@@ -16,6 +16,7 @@
     "packages/cache-export",
     "packages/codex-edit",
     "packages/herdr-subagents",
+    "packages/openai-account-pool",
     "packages/scheduler",
     "packages/worktree",
     "themes",
@@ -35,6 +36,7 @@
       "./extensions/btw/index.ts",
       "./packages/codex-edit/extensions/codex-edit.ts",
       "./packages/herdr-subagents/extensions/herdr-subagents.ts",
+      "./packages/openai-account-pool/extensions/openai-account-pool.ts",
       "./packages/scheduler/extensions/scheduler.ts",
       "./packages/worktree/extensions/worktree.ts"
     ],
@@ -59,8 +61,8 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/scheduler test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
-    "load-test": "pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts && pi -ne -e ./packages/scheduler/extensions/scheduler.ts && pi -ne -e ./packages/worktree/extensions/worktree.ts",
+    "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/openai-account-pool test && npm --prefix packages/scheduler test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
+    "load-test": "pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts && pi -ne -e ./packages/openai-account-pool/extensions/openai-account-pool.ts && pi -ne -e ./packages/scheduler/extensions/scheduler.ts && pi -ne -e ./packages/worktree/extensions/worktree.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",
     "postinstall": "node scripts/install-agents.mjs"

package/packages/herdr-subagents/ARCHITECTURE.md

@@ -1,408 +1,112 @@
-# Herdr Subagents architecture and decision-pause design
+# Herdr Subagents architecture
 
-This document describes the package's current architecture, the problems exposed by failure and blocking semantics, and the target decision-pause model. Sections marked **Current** describe implemented behavior. Sections marked **Target** are an implementation plan, not the current contract.
+## Goal
 
-## 1. Product boundary
+Herdr owns terminal presentation and pane operations. The package owns scheduling and durable state. Pi children own only their attempt result.
 
-Herdr Subagents runs ordinary interactive Pi Agents in visible Herdr panes and keeps their complete sessions and results in project-local durable records. The parent receives compact status, questions, summaries, and document paths.
+The implementation deliberately stays small: one task state machine, one run aggregation rule, and one bounded worker pool. Serial and read-only parallel dispatch share the same path. There are no alternate lifecycle engines for background work, blocking, retries, or resume.
 
-A batch is a resource-bounded collection of **independent tasks**:
+## State machines
 
-- array order controls FIFO scheduling, pane numbering, and result order;
-- `concurrency` controls how many tasks may be active at once;
-- a batch containing a write-capable persona is forced to concurrency one;
-- concurrency one does **not** express `A -> B` dependency semantics;
-- tasks that consume another task's result must be orchestrated by the parent as separate runs.
+Task:
 
-The package does not currently need a DAG scheduler. If dependency workflows become a first-class product requirement, they should be introduced explicitly with dependency and skip-propagation semantics instead of inferred from array order.
-
-## 2. Architecture overview
-
-```text
-Parent Pi tool call
-        |
-        v
-Extension lifecycle and foreground handoff
-        |  extensions/herdr-subagents.ts
-        v
-Global run dispatcher ---- persisted background queue
-        |                  src/dispatcher.ts, src/queued-runs.ts
-        v
-Batch runner and bounded workers
-        |  src/batch-runner.ts
-        +---- pane allocation / Herdr Agent lifecycle
-        |     src/run-pane-allocator.ts, src/live-agent.ts, src/herdr.ts
-        +---- attempt-scoped structured report
-        |     src/attempts.ts, src/protocol.ts, src/records.ts
-        +---- durable run/task/session records
-        |     .pi/herdr-subagents/runs/<run>/...
-        v
-Aggregate status, monitor, control, recovery and cleanup
-           src/run-status.ts, src/status.ts, src/fleet*.ts,
-           src/blocking.ts, src/historical-resume.ts,
-           src/reconcile.ts, src/tab-cleanup.ts
-```
-
-### Responsibilities
-
-| Layer | Responsibility |
-| --- | --- |
-| Extension | Register tools, bind parent-session lifetime, return foreground results, send final background follow-ups. |
-| Dispatcher | Give one run ownership of the global submission lane and queue later submissions FIFO. |
-| Batch runner | Persist the run, start bounded workers, allocate one pane per task, and aggregate task results. |
-| Live Agent adapter | Start or continue an interactive Pi Agent and distinguish runtime telemetry from business reports. |
-| Records | Atomically persist run, task, turn, report, attempt, ownership, and resume state. |
-| Control | Inspect, answer, retry/continue saved work, cancel, resume history, and clean archives. |
-| Recovery | Reconcile stale owners and processes, settle abandoned work, and clean identifiable tabs. |
-| Fleet | Project durable business state plus transient runtime telemetry into the parent UI. |
-
-## 3. Authoritative state and invariants
-
-1. A matching attempt-scoped `subagent_report` is authoritative for business `completed`, `blocked`, or `failed`.
-2. Herdr `working`, `blocked`, `idle`, and `done` are transport/runtime telemetry. Herdr UI `blocked` projects to `waiting_interaction`; it does not make the business task blocked.
-3. Each task owns one pane and one Pi session. A pane is never reused by another task.
-4. A task session has at most one writer. Task resume locks enforce that invariant.
-5. Shared `run.json` changes occur under the short-lived run-state lock. An Agent turn never holds that lock.
-6. Every new prompt has a unique attempt ID. A late report from an older attempt cannot settle a newer attempt.
-7. Task and report state is persisted before it is exposed as an actionable parent result.
-8. Running work is not forcibly interrupted merely because a sibling needs a decision.
-
-## 4. Current execution flow
-
-### Submission
-
-1. Tool parameters are validated.
-2. Configuration and personas are loaded and resolved.
-3. A stable run ID is allocated.
-4. Background runs are durably queued before dispatch; foreground runs wait for the dispatcher lane.
-5. The batch runner creates `run.json`, task directories, task records, prompts, and session paths.
-6. Effective concurrency is bounded by settings and forced to one if any persona is write-capable.
-
-### Task execution
-
-Each worker repeatedly claims the next FIFO task, allocates a pane, starts an interactive Pi Agent, waits for the matching structured report, persists the result, and claims another task. A failed task does not currently stop that worker. A blocked task stops only its worker lane.
-
-### Current foreground outcomes
-
-| Event | Current foreground behavior | Queued siblings |
-| --- | --- | --- |
-| All tasks complete | Return after the whole batch settles. | Completed normally. |
-| Failure with concurrency one | Continue later tasks, then return terminal `failed` or `partial`. | Continue automatically. |
-| Failure with concurrency greater than one and unfinished siblings | Persist the failure, return early, detach the batch, and let it finish in the background. | Continue automatically. |
-| Business block | Wait for the other worker lanes to settle, then return the question and retain the dispatcher lane. | A blocked worker stops, but other workers keep claiming tasks. |
-| Herdr UI block | Keep waiting for an authoritative report while showing `waiting_interaction`. | Unchanged. |
-
-The failure and block rows are asymmetric: parallel failure gives control back promptly, while block may withhold its question until unrelated work finishes. Serial failure also assumes later tasks are independent. The target design removes both ambiguities.
-
-## 5. Dispatcher ownership in plain language
-
-The dispatcher is the global submission lane, not the task-concurrency limiter.
-
-| Operation | Meaning |
-| --- | --- |
-| `detach` | The run continues in the background but gives up the submission lane, so another run may start. |
-| `retain` | The run is waiting for a parent decision and keeps the lane; a new foreground run is rejected and a background run stays queued. |
-| `release` | A retained run is resolved or cancelled and gives up the lane. |
-
-Current parallel failure uses `detach`; current business block eventually uses `retain`.
-
-## 6. Target decision-pause model
-
-### Goal
-
-Any actionable business problem returns control to the parent immediately and stops new task dispatch until the parent decides what to do. Already-running siblings are allowed to finish safely.
-
-```text
-A reports failed or blocked
-        |
-        +---- persist task/report/attempt state
-        +---- pause new queue claims
-        +---- return pause details to the parent immediately
-        +---- retain the dispatcher lane
-        |
-B and C were already running ---- continue to a terminal report
-D and E were queued ------------- remain queued
-```
-
-"Pause" means pausing **dispatch**, not freezing an Agent process at an arbitrary instruction. Forcibly suspending or cancelling running siblings could leave tools, file writes, or external operations in an unknown state.
-
-### Run control state must be separate from task outcome
-
-The current `RunStatus` reuses task statuses and aggregates them into `running`, `blocked`, `partial`, and terminal values. That combines two different questions:
-
-1. May the scheduler dispatch more work?
-2. What outcomes have tasks produced?
-
-The target model separates them conceptually:
-
-```ts
-type RunPhase = "queued" | "running" | "paused" | "cancelling" | "settled";
-type RunOutcome = "completed" | "partial" | "failed" | "cancelled";
-```
-
-The public status projection may continue exposing `status: "paused"` for convenience, but durable control logic should use the phase. While a run is paused, some task activities may still be `running` as already-started siblings settle.
-
-### Durable pause reasons
-
-A pause is tied to a specific task attempt so stale answers cannot resolve newer work:
-
-```ts
-interface PauseReason {
-  taskId: string;
-  taskOrder: number;
-  attemptId: string;
-  kind: "blocked" | "failed";
-  resolution: "pending" | "responded" | "retried" | "continued" | "cancelled";
-  createdAt: string;
-  resolvedAt?: string;
-}
-```
-
-The durable reason should reference authoritative task/report records instead of duplicating mutable summary, question, and error text. Status and tool responses project a detailed view:
-
-```json
-{
-  "status": "paused",
-  "pauseReasons": [
-    {
-      "task": 1,
-      "kind": "failed",
-      "summary": "Authentication review failed.",
-      "error": "Provider request failed.",
-      "allowedActions": ["retry", "continue", "cancel"]
-    }
-  ]
-}
+```mermaid
+stateDiagram-v2
+    [*] --> queued
+    queued --> running: worker slot available
+    queued --> cancelled: parent cancellation
+    running --> completed: valid completed report
+    running --> failed: valid failed report or process exits without report
+    running --> cancelled: parent cancellation
+    completed --> [*]
+    failed --> [*]
+    cancelled --> [*]
 ```
 
-Multiple already-running siblings may subsequently fail or block. Their reasons accumulate. No queued task starts while any pending reason remains.
-
-### Decision actions
-
-| Reason | Action | Effect |
-| --- | --- | --- |
-| `blocked` | `respond` | Continue the same live/saved session with the answer. |
-| `failed` | `retry` | Retry or continue the selected task explicitly; never infer a task. |
-| `failed` | `continue` | Accept that task's failure and allow the run to proceed without retrying it. |
-| Any | `cancel` | Cancel running and queued work and settle the run as cancelled. |
-
-`respond` should no longer be overloaded for failed tasks once `retry` exists. This makes control intent and audit history explicit.
-
-The queue resumes only when every pending pause reason is resolved. A retry or response that blocks/fails again creates a reason for the new attempt.
-
-### Failure classification
-
-Both child-reported failures and generated terminal failures can pause a run:
-
-- valid `subagent_report(status="failed")`;
-- child process or prompt API terminal error without a valid report;
-- Agent settled without publishing a report after the grace period;
-- pane or Agent startup failure.
-
-Ambiguous prompt delivery remains `delivery_unknown` while the child is alive and must not be converted into a retryable failure. Retry safety should be projected explicitly when the implementation can prove whether a prompt was submitted; the system must never automatically replay an attempt with uncertain side effects.
-
-### Foreground handoff
-
-Failure and block should share one foreground-handoff mechanism:
-
-1. observe an actionable, durably persisted task attempt;
-2. atomically pause dispatch and register its reason;
-3. detach the parent tool-call abort signal without cancelling the run;
-4. retain dispatcher ownership;
-5. return the projected pause details immediately;
-6. keep already-running siblings and final background lifecycle tracking alive;
-7. send at most one terminal follow-up after the run eventually settles.
-
-The event-specific policy only determines allowed decisions and response rendering. It should not duplicate lifecycle, persistence, or notification machinery.
-
-## 7. Target flows
-
-### Independent parallel tasks
-
-```text
-Submit A, B, C, D with concurrency 3
-A/B/C start; D queued
-A fails
-  -> run phase paused
-  -> D remains queued
-  -> parent receives A failure immediately
-B/C continue safely
-Parent retries A, continues past A, or cancels
-  -> once all pending reasons are resolved, dispatch may resume
+The three terminal states are immutable. Follow-up work creates a new task or run.
+
+Run:
+
+```mermaid
+stateDiagram-v2
+    [*] --> running
+    running --> completed: every task completed
+    running --> failed: every task failed
+    running --> cancelled: every task cancelled
+    running --> partial: terminal outcomes are mixed
+    completed --> [*]
+    failed --> [*]
+    cancelled --> [*]
+    partial --> [*]
 ```
 
-### Serial tasks
-
-```text
-Submit A, B, C with concurrency 1
-A starts; B/C queued
-A fails or blocks
-  -> run phase paused
-  -> B/C do not start
-  -> parent decides
+Run state is derived from task state. `partial` means terminal tasks have mixed outcomes.
+
+Scheduler and arbitration:
+
+```mermaid
+flowchart TD
+    Q[Queued tasks] -->|FIFO, free worker slot| S[Start Pi in Herdr pane]
+    S --> P[Deliver prompt exactly once]
+    P --> R{Attempt report exists?}
+    R -->|yes| V[Validate attempt and report]
+    V --> T[Commit immutable terminal task]
+    R -->|no| L{Child Pi process alive?}
+    L -->|yes| W[Herdr wait wake-up]
+    W --> R
+    L -->|no| C{Final disk reconciliation}
+    C -->|report found| V
+    C -->|no report| F[Commit failed task]
+    T --> Q
+    F --> Q
 ```
 
-This makes serial execution safer, but still does not make B consume A's result. A real `A -> B` workflow remains parent-orchestrated as separate runs.
-
-### Runtime-only Herdr block
-
-```text
-Herdr reports blocked
-  -> task remains business running
-  -> Fleet shows waiting_interaction
-  -> no decision pause yet
-Child publishes matching structured blocked report
-  -> create pause reason
-  -> return exact question
-```
-
-## 8. Configuration: keep fewer concepts, not necessarily fewer files
-
-### Current user-facing sources
-
-| Scope | Runtime settings and persona overrides | Persona definitions and prompts |
-| --- | --- | --- |
-| Project | `.pi/herdr-subagents.json` | `.pi/herdr-subagents/agents/*.md` |
-| Global | `~/.pi/agent/herdr-subagents.json` | `~/.pi/agent/herdr-subagents/agents/*.md` |
-| Package | Built-in defaults | Built-in `agents/*.md` |
-
-The two formats have distinct jobs:
-
-- JSON is suitable for environment policy and small overrides.
-- Markdown frontmatter plus body is suitable for a named persona and its system prompt.
-
-Merging them into one physical file would either put long prompts into JSON or require runtime policy to be parsed from Markdown. It would also force users to copy an entire built-in persona merely to override its model. Therefore the two physical forms should remain.
-
-### Sources of confusion to remove
-
-1. Persona Markdown and JSON both expose `model`, `thinking`, `skills`, and `extensions`; this is intentional override layering but must be described as one resolution pipeline.
-2. Call-level task model overrides are resolved later in `tool.ts`, after configuration loading.
-3. TypeBox validates shape while `validation.ts` validates action-dependent requirements; these are complementary but currently look like duplicated validation.
-4. Downstream modules receive partially resolved values instead of one canonical run plan.
-
-### Canonical normalization boundary
-
-All sources should be normalized once before persistence or dispatch:
-
-```text
-Built-in defaults
-  <- global JSON
-  <- project JSON
-  <- effective persona Markdown
-  <- global persona override
-  <- project persona override
-  <- call/task override
-        |
-        v
-ResolvedRunPlan + diagnostics + source metadata
-```
-
-A target canonical plan can contain only execution-ready values:
-
-```ts
-interface ResolvedRunPlan {
-  label: string;
-  requestedConcurrency: number;
-  effectiveConcurrency: number;
-  tasks: Array<{
-    name: string;
-    prompt: string;
-    persona: string;
-    access: "read" | "write";
-    model?: string;
-    thinking?: string;
-    tools?: string[];
-    skills: string[];
-    extensions: string[];
-    systemPrompt: string;
-  }>;
-  provenance: Record<string, string>;
-  diagnostics: string[];
-}
-```
-
-After this boundary, the batch runner, persistence, recovery, and UI should not know about global/project/package precedence.
-
-### Configuration reductions
+Herdr `idle`, `blocked`, and `done` never transition a business task; they only wake the reconciliation loop.
 
-Do:
+Legacy readers still accept old `starting` and `blocked` values so existing archives can be inspected and cleaned up. New execution does not produce them.
 
-- retain one JSON settings file per scope and one persona directory per scope;
-- centralize precedence and call overrides in a single `resolveRunPlan` step;
-- expose resolved values and provenance through `list/settings` diagnostics;
-- state prominently that batch tasks are independent;
-- make decision pause the safe fixed behavior rather than adding a new failure-policy option;
-- keep runtime-only Herdr states out of business configuration.
+## Scheduling
 
-Do not add now:
+A run uses a bounded worker pool:
 
-- DAG or `dependsOn` configuration;
-- configurable `failurePolicy` variants;
-- separate block/failure handoff settings;
-- automatic retry counts;
-- configuration for dispatcher `detach`/`retain` behavior.
+1. Tasks begin FIFO.
+2. With concurrency one, the next task cannot start until the previous task is terminal.
+3. With concurrency N, at most N tasks own live child processes.
+4. Failure consumes only that task's lane; queued siblings continue.
+5. Parallel execution is rejected if any task is write-capable.
+6. The caller remains attached until all tasks are terminal or the caller cancels.
 
-These options would multiply state-machine branches before a demonstrated need. The safe decision gate should be the invariant.
+There is no global dispatcher, persisted background queue, blocked response lane, historical resume, or early detach.
 
-### Validation ownership
+## Child boundary
 
-- `parameters.ts`: public schema, field types, basic bounds, and model-visible descriptions.
-- `validation.ts`: cross-field and action-specific requirements.
-- `resolveRunPlan`: persona existence, precedence, capability constraints, effective concurrency, and canonical values.
-- runtime state machine: whether an action is legal for the selected run/task/attempt.
+Each task owns one Herdr pane and one single-task Pi process. Herdr first starts and detects the interactive Pi, then submits the prompt exactly once. The child extension exits the process at Pi’s final `agent_settled` boundary, giving each task an unambiguous process lifetime without parent-side prompt retries.
 
-This division avoids both duplicated validation and an oversized configuration loader.
+The child writes:
 
-## 9. Implementation seams for the target model
+- `results/<attempt-id>.md`
+- `reports/<attempt-id>.json`
 
-| Area | Required change |
-| --- | --- |
-| `records.ts` | Separate run phase/outcome, persist attempt-scoped pause reasons, and preserve backward-compatible reads. |
-| `run-status.ts` | Aggregate task outcomes independently from scheduler phase. |
-| `batch-runner.ts` | Add a shared dispatch gate; stop queue claims immediately when a reason is registered. |
-| `extensions/herdr-subagents.ts` | Replace failure-only early return with shared actionable-event handoff. |
-| `dispatcher.ts` | Retain paused runs and release only after resolution/cancellation; keep ownership transitions explicit. |
-| `blocking.ts` / control | Split blocked `respond` from failed `retry`; add explicit `continue`. |
-| `continue-run.ts` | Resume queued dispatch only when no pending reason remains. |
-| `reconcile.ts` | Recover paused runs and cancel them when their owning parent session disappears. |
-| `status.ts` / Fleet | Show pause reasons, allowed actions, and still-running sibling activity together. |
-| `parameters.ts` / `validation.ts` | Add `retry` and `continue`, clarify independent-task semantics. |
-| tests | Cover immediate handoff, dispatch pause, multiple reasons, resolution races, restart recovery, and exactly-once final notification. |
+Both are attempt-scoped. The report is published with atomic rename. The orchestrator validates it, verifies the attempt identity, and promotes it to `report.json`.
 
-## 10. Required tests
+The orchestrator writes:
 
-1. Serial failure pauses before the next queued task starts.
-2. Serial block pauses before the next queued task starts.
-3. Parallel failure returns immediately while already-running siblings continue.
-4. Parallel block returns immediately while already-running siblings continue.
-5. Queued siblings never start while a reason is pending.
-6. A second already-running sibling can add another pause reason without losing the first.
-7. Resolving only one of multiple reasons does not resume dispatch.
-8. `continue` preserves the failed task result and eventually produces `partial` when other tasks succeed.
-9. Retry/response is scoped to task and attempt; stale resolution is rejected.
-10. Herdr UI `blocked` alone never pauses business dispatch.
-11. `delivery_unknown` never causes automatic replay.
-12. A paused run retains the dispatcher lane; foreground submissions fail fast and background submissions remain queued.
-13. Cancellation settles running/queued tasks and releases the retained lane.
-14. Parent-session shutdown and startup reconciliation do not leave ownerless paused work.
-15. Foreground handoff and final follow-up are each delivered at most once.
+- `task.json`
+- `run.json`
+- promoted `report.json`
 
-## 11. Non-goals
+## Completion arbitration
 
-- Inferring dependencies from task order or prompt text.
-- Freezing arbitrary live Agent processes.
-- Automatically retrying failed or ambiguously delivered prompts.
-- Treating Herdr UI state as business truth.
-- Loading complete child results into parent context.
-- Adding policy configuration for every state transition.
+1. Check for a valid attempt report.
+2. If present, the report wins, including against a concurrent cancellation observation.
+3. Otherwise inspect child process liveness.
+4. While the process is alive, keep waiting. Herdr agent states only wake reconciliation.
+5. If the process has exited, check disk once more and fail only when no report exists.
 
-## 12. Summary
+There is no fixed drain delay and no transcript parsing. Pi retries are internal to the same one-shot process, so transient provider or transport errors cannot create a premature terminal task.
 
-The architecture becomes clearer when it separates four concerns:
+Writing the same report again is idempotent. A conflicting replacement is rejected.
 
-1. **Task outcome:** what each child authoritatively reported.
-2. **Run phase:** whether new work may be dispatched or a parent decision is required.
-3. **Runtime telemetry:** what Herdr currently observes without changing business truth.
-4. **Dispatcher ownership:** whether another run may enter the global submission lane.
+## Cancellation and recovery
 
-The immediate next design step is a shared decision-pause and foreground-handoff mechanism for business failure and block. Configuration should be simplified through one canonical resolution boundary and fewer policy choices, not by forcing settings and persona prompts into one file.
+Caller or parent-session cancellation aborts active waits, marks nonterminal tasks cancelled, and closes the owned Herdr tab. Startup recovery is scoped by recorded parent ownership and retains readers for prior record formats. Recovery never resumes or mutates an already terminal task.

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-10-13 - v0.5.0
+
+- simplify lifecycle to one report-first state machine with strict serial and bounded read-only parallel execution
+
 ## 2026-10-13 - v0.4.14
 
 - allow explicit extension sources with native Pi package semantics and reliable cleanup checks