@agwab/pi-workflow 0.2.1 → 0.3.0

package/node_modules/@agwab/pi-subagent/docs/usage.md

@@ -33,20 +33,23 @@ Every call has an `action`. The default is `run`, so omitting `action` starts a
 | `action` | Purpose | Key parameters |
 |---|---|---|
 | `run` (default) | Start a new subagent run, or launch independent runs in parallel. | `agent`/`task` or `tasks`; plus `sandbox`, `worktree`, `model`, `async`, etc. |
-| `status` | Read a run's current state. | `runId`, optional `attemptId` |
-| `logs` | Read a run's captured logs. | `runId`, optional `attemptId` |
-| `wait` | Block until a run finishes. | `runId`, optional `timeoutMs`, `pollIntervalMs` |
-| `interrupt` | Signal a process-backed run. | `runId`, optional `attemptId`, `signal`, `escalateAfterMs`, `killAfterMs`, `reason` |
-| `mark-background` | Mark a run as not needed before the final answer. | `runId` |
-| `reconcile` | Re-read durable artifacts and repair stale/orphaned state when possible. | `runId` |
+| `status` | Read a run's current state. | `runId`, optional `cwd`, `attemptId` |
+| `logs` | Read a run's captured logs. | `runId`, optional `cwd`, `attemptId` |
+| `wait` | Block until a run finishes. | `runId`, optional `cwd`, `timeoutMs`, `pollIntervalMs` |
+| `interrupt` | Signal a process-backed run. | `runId`, optional `cwd`, `attemptId`, `signal`, `escalateAfterMs`, `killAfterMs`, `reason` |
+| `mark-background` | Mark a run as not needed before the final answer. | `runId`, optional `cwd` |
+| `reconcile` | Re-read durable artifacts and repair stale/orphaned state when possible. | `runId`, optional `cwd` |
 
-State is file-based under `.pi/agent/runs/<run-id>/`. `status`/`logs`/`wait` read those files; `interrupt` sends a real OS signal; `mark-background` updates run metadata; `reconcile` repairs local metadata from durable attempt artifacts without relaunching work.
+State is file-based under `.pi/agent/runs/<run-id>/`. `status`/`logs`/`wait` read those files; `interrupt` sends a real OS signal; `mark-background` updates run metadata; `reconcile` repairs local metadata from durable attempt artifacts without relaunching work. Recent runs also write a global locator pointer, so existing-run actions can often resolve a `runId` even when `cwd` is omitted or the run was launched from another cwd.
+
+Parent orchestrators may record descendant state with `recordSubagentChildEvent`, which appends `child.*` events to the parent run's `events.jsonl` (`child.started`, `child.failed`, `child.completed`, or `child.cancelled`). `status` and `/subagent panel` aggregate those into `childSummary`, including failure counts, active child run IDs, and the latest child failure. This keeps parent status distinct from descendant failures and makes retry attempts distinguishable from newly-started child work.
 
 Model:
 
 ```text
 run = one subagent execution
 attempt = one launch attempt
+child = descendant work reported by an orchestrator through child.* events
 correlationId = optional external trace label
 ```
 
@@ -68,6 +71,7 @@ import {
   waitForSubagent,
   interruptSubagent,
   reconcileSubagentRun,
+  recordSubagentChildEvent,
 } from "@agwab/pi-subagent/api";
 
 const run = await runSubagent({
@@ -83,9 +87,17 @@ const logs = await getSubagentLogs({ cwd: process.cwd(), runId: run.runId });
 await waitForSubagent({ cwd: process.cwd(), runId: run.runId, timeoutMs: 300000 });
 await interruptSubagent({ cwd: process.cwd(), runId: run.runId, reason: "caller cancelled" });
 await reconcileSubagentRun({ cwd: process.cwd(), runId: run.runId });
+await recordSubagentChildEvent({
+  cwd: process.cwd(),
+  runId: run.runId,
+  event: "failed",
+  childRunId: "run_child_123",
+  childTaskId: "task-4",
+  failureKind: "model",
+});
 ```
 
-`runSubagent` accepts the same run options as the tool, plus an optional `signal`. Existing-run helpers accept `cwd`, `runId`, optional `attemptId`, and optional `runsDir`. The API is intentionally object-only and does not expose the lower-level runner internals.
+`runSubagent` accepts the same run options as the tool, plus an optional `signal`. Existing-run helpers accept `runId`, optional `cwd`, optional `attemptId`, and optional `runsDir`; when `cwd` is omitted they use the global locator index first and fall back to the current cwd for legacy records. The API is intentionally object-only and does not expose the lower-level runner internals.
 
 The code API is ESM-only. Import `@agwab/pi-subagent/api`; do not deep-import internal files such as `src/orchestrate/*` because only documented package subpaths are public.
 
@@ -128,6 +140,21 @@ Use `concurrency` to cap parallel fan-out:
 }
 ```
 
+For synchronous parallel fan-out, `failFast:true` stops scheduling additional siblings after the first failed result. Add `cancelSiblingsOnFailure:true` to also abort siblings that are already running:
+
+```json
+{
+  "failFast": true,
+  "cancelSiblingsOnFailure": true,
+  "tasks": [
+    { "task": "Run check A." },
+    { "task": "Run check B." }
+  ]
+}
+```
+
+The parallel response includes `totalTasks`, `startedCount`, `skippedCount`, and `failFastTriggered` so callers can distinguish skipped siblings from completed/failed runs. Async parallel launches return once children are started, so fail-fast decisions for later runtime failures must be handled by the parent/workflow layer.
+
 Chain/sequential execution is intentionally not supported by this engine. If step B needs output from step A, keep that sequencing in the parent agent or a workflow layer.
 
 ## Async and existing runs
@@ -177,14 +204,26 @@ Interrupt a process-backed run:
 
 `interrupt` is conservative. It can signal runs with registered process metadata. Unsupported or already-terminal runs return explicit status rather than pretending cancellation succeeded.
 
+### Existing-run resolution
+
+For `status`, `logs`, `wait`, `interrupt`, `mark-background`, and `reconcile`, the lookup order is:
+
+1. Use the explicit `cwd`/`runsDir` when provided.
+2. Otherwise, check the current cwd's `.pi/agent/runs` for legacy/local records.
+3. Otherwise, resolve `runId` through the global locator index and read the pointed-to run directory.
+
+The locator index is only a pointer for finding runs across cwd boundaries. `run.json`, `events.jsonl`, and attempt `result.json` files remain the source of truth.
+
 ## Common run options
 
 | Option | Use |
 |---|---|
-| `cwd` | Run from a specific project directory. Existing-run actions also accept `cwd` to find that run registry. |
+| `cwd` | Run from a specific project directory. Existing-run actions accept `cwd` to force a registry location; if omitted, recent runs can be found by global locator and older runs fall back to the current cwd. |
 | `timeoutMs` | Limit worker execution time for `run`; limit polling duration for `action: "wait"`. Omit it for no runtime kill deadline; `wait` alone defaults to 60s polling. |
 | `visible` | Use a visible tmux-backed worker (`visible: true`). |
 | `concurrency` | Cap parallel run fan-out. |
+| `failFast` | For synchronous parallel runs, stop scheduling new siblings after the first failed result. |
+| `cancelSiblingsOnFailure` | For synchronous parallel runs, abort already-running siblings after the first failed result; implies fail-fast scheduling. |
 | `model` | Select a Pi model/provider for model-backed workers. |
 | `thinking` / `thinkingLevel` / `reasoningLevel` | Set the reasoning level. |
 | `tools` | Tool allowlist. With a named agent this may only narrow agent-declared tools; it cannot expand authority. For agentless runs it sets the full tool allowlist. |
@@ -247,8 +286,8 @@ There are three inputs for worktree isolation, in order of preference:
 | Input | When to use |
 |---|---|
 | `worktree` | Primary switch. `true` to isolate; or a string path for an explicit worktree location. |
-| `workspace` | Advanced. `"shared" | "worktree" | "auto"`, or `{ mode, path }` for an explicit path. |
-| `worktreePolicy` | Advanced. `"auto" | "required" | "never"` to force or forbid isolation. |
+| `workspace` | Advanced. `"shared" \| "worktree" \| "auto"`, or `{ mode, path }` for an explicit path. |
+| `worktreePolicy` | Advanced. `"auto" \| "required" \| "never"` to force or forbid isolation. |
 
 Most calls only need `worktree`:
 
@@ -389,6 +428,8 @@ Runs write durable evidence under:
 
 `run.json` records a `parentSessionId` field: the Pi session id of the session that launched the run, injected from the tool context (not a model-settable argument). Consumers (e.g. status panels) can use it to scope a shared per-`cwd` runs directory to the session that owns each run. The field is omitted when no session id is available, and older records simply lack it.
 
+Recent runs also write a small locator file under Pi's global subagent-run index. A locator contains the `runId`, absolute `cwd`, optional `runsDir`, optional `parentSessionId`, optional `correlationId`, and `updatedAt`. It is not authoritative evidence and can become stale if the pointed-to run directory is moved or deleted; use `run.json`, `events.jsonl`, and attempt `result.json` as the source of truth.
+
 Older `schemaVersion: 1` artifacts under `<run-id>/<task-id>/` are still readable for compatibility.
 
 Tool responses return compact status and artifact references rather than raw logs.
@@ -399,7 +440,17 @@ Tool responses return compact status and artifact references rather than raw log
 /subagent panel
 ```
 
-The panel shows all/completed/failed filters, run/attempt details, workspace/artifact paths, dependency metadata, event tail, and log tail. The panel is for human inspection; existing-run tool actions remain the programmatic interface.
+The panel shows run/attempt details, workspace/artifact paths, dependency metadata, event tail, and log tail. It has three scopes:
+
+- `session`: runs whose `run.json.parentSessionId` matches the current Pi session. This is the default when a session id is available.
+- `cwd`: runs under the current workspace's `.pi/agent/runs`, including legacy records that lack `parentSessionId`.
+- `all`: the global locator index plus current-cwd legacy records.
+
+Status filters are `all`, `running`, `completed`, and `failed`. In the `all` status view, the default list shows all active runs plus recent terminal runs only: 20 for `session`/`cwd`, 50 for `all`. The `completed` and `failed` filters use the same recent terminal cap; `running` is uncapped. The header reports `shown/total`, and when older matching runs are hidden, press `m` in the panel to show more; no separate command is needed. The panel keeps a fixed-height layout, uses an internally scrollable detail pane, and never renders raw `parentSessionId` values.
+
+Stale or malformed locators are counted in the header and skipped. Active runs whose process metadata is dead and whose heartbeat/update timestamp is stale are rendered read-only as `failed` with failure `stale`; the panel does not mutate or delete records. Use `action:"reconcile"` to repair local registry state from durable artifacts when possible.
+
+The panel is for human inspection; existing-run tool actions remain the programmatic interface.
 
 ## Development validation
 

package/node_modules/@agwab/pi-subagent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agwab/pi-subagent",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Minimal subagent runtime for Pi.",
   "type": "module",
   "private": false,
@@ -37,7 +37,7 @@
     "image": "https://raw.githubusercontent.com/AgwaB/pi-subagent/main/assets/subagent-panel.png"
   },
   "scripts": {
-    "check:scripts": "for d in scripts test internal/scripts; do [ -d \"$d\" ] && find \"$d\" -name '*.mjs' -print; done | xargs -n1 node --check",
+    "check:scripts": "for d in scripts test; do [ -d \"$d\" ] && find \"$d\" -name '*.mjs' -print; done | xargs -n1 node --check",
     "check:resolver": "node ./test/checks/resolver.mjs",
     "check:api": "node ./test/checks/api.mjs",
     "check:artifacts": "node ./test/checks/artifacts.mjs",

package/node_modules/@agwab/pi-subagent/src/api.ts

@@ -1,10 +1,16 @@
 import { resolve } from "node:path";
 import { loadAgentByName, type AgentDefinition } from "./agents.ts";
-import type { ResultEnvelope } from "./artifacts/index.ts";
+import {
+	appendRunEvent,
+	type ResultEnvelope,
+	type RunEvent,
+} from "./artifacts/index.ts";
 import type {
 	ExecutionMode,
+	FailureKind,
 	ResolveInput,
 	ResolvedBackend,
+	Status,
 } from "./core/constants.ts";
 import { resolveBackend } from "./core/resolver.ts";
 import { validateResolveInput } from "./core/validation.ts";
@@ -22,6 +28,7 @@ import {
 	type ReconcileSubagentRunOptions as ReconcileRunOptions,
 	type ReconcileSubagentRunResult,
 } from "./orchestrate/reconcile.ts";
+import { resolveRunRef } from "./orchestrate/run-ref.ts";
 import {
 	runParallelSubagentTasks,
 	runSubagentTask,
@@ -50,6 +57,16 @@ export type WaitForSubagentOptions = WaitForRunOptions;
 export type InterruptSubagentOptions = InterruptRunOptions;
 export type ReconcileSubagentOptions = ReconcileRunOptions;
 
+export interface RecordSubagentChildEventOptions extends RunStatusRef {
+	event: "started" | "updated" | "completed" | "failed" | "cancelled";
+	childRunId: string;
+	workflowRunId?: string;
+	childTaskId?: string;
+	status?: Status;
+	failureKind?: FailureKind | string | null;
+	message?: string;
+}
+
 export class SubagentValidationError extends Error {
 	readonly failureKind = "validation" as const;
 	readonly backend?: ResolvedBackend;
@@ -269,6 +286,40 @@ export async function reconcileSubagentRun(
 	return await reconcileRun(options);
 }
 
+function defaultChildStatus(
+	event: RecordSubagentChildEventOptions["event"],
+): Status {
+	if (event === "started" || event === "updated") return "running";
+	if (event === "completed") return "completed";
+	if (event === "cancelled") return "cancelled";
+	return "failed";
+}
+
+export async function recordSubagentChildEvent(
+	options: RecordSubagentChildEventOptions,
+): Promise<RunEvent> {
+	const {
+		event,
+		childRunId,
+		workflowRunId,
+		childTaskId,
+		failureKind,
+		message,
+	} = options;
+	const ref = await resolveRunRef(options);
+	return await appendRunEvent(ref, {
+		type: `child.${event}`,
+		status: options.status ?? defaultChildStatus(event),
+		...(message === undefined ? {} : { message }),
+		data: {
+			childRunId,
+			...(workflowRunId === undefined ? {} : { workflowRunId }),
+			...(childTaskId === undefined ? {} : { taskId: childTaskId }),
+			...(failureKind === undefined ? {} : { failureKind }),
+		},
+	});
+}
+
 export type {
 	ArtifactRef,
 	CompletionMetadata,
@@ -294,6 +345,8 @@ export type { InterruptRunResult } from "./orchestrate/interrupt.ts";
 export type { ReconcileSubagentRunResult } from "./orchestrate/reconcile.ts";
 export type { ParallelRunResult } from "./orchestrate/run.ts";
 export type {
+	RunChildFailureSummary,
+	RunChildSummary,
 	RunLogRef,
 	RunLogsSnapshot,
 	RunStatusRef,

package/node_modules/@agwab/pi-subagent/src/artifacts/registry.ts

@@ -18,6 +18,11 @@ export type RunEventType =
   | "run.cancelled"
   | "run.interrupt_requested"
   | "run.mark_background"
+  | "child.started"
+  | "child.updated"
+  | "child.completed"
+  | "child.failed"
+  | "child.cancelled"
   | "attempt.started"
   | "attempt.process_started"
   | "attempt.heartbeat"
@@ -716,11 +721,11 @@ export async function readRunEvents(ref: RunRef, limit = 50): Promise<RunEvent[]
   const paths = runPaths(ref);
   try {
     const text = await readFile(paths.eventsPath, "utf8");
-    return text
+    const lines = text
       .split(/\r?\n/)
-      .filter(Boolean)
-      .slice(-limit)
-      .map((line) => JSON.parse(line) as RunEvent);
+      .filter(Boolean);
+    const selected = Number.isFinite(limit) ? lines.slice(-limit) : lines;
+    return selected.map((line) => JSON.parse(line) as RunEvent);
   } catch (error) {
     if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return [];
     throw error;

package/node_modules/@agwab/pi-subagent/src/artifacts/result.ts

@@ -80,6 +80,7 @@ export interface ResultSessionMetadata {
 
 export interface ResultMetadata {
 	contextLengthExceeded: boolean;
+	contextOverflowRecovered?: boolean;
 	provider?: string;
 	model?: string;
 	usage?: unknown;
@@ -89,6 +90,7 @@ export interface ResultMetadata {
 	session?: ResultSessionMetadata;
 	streamErrors?: string[];
 	nonFatalStreamErrors?: string[];
+	recoveredStreamErrors?: string[];
 	parseErrors?: string[];
 }
 
@@ -199,6 +201,9 @@ function normalizeMetadata(input: ResultEnvelopeInput): ResultMetadata {
 	const metadata = input.metadata ?? {};
 	return {
 		contextLengthExceeded: metadata.contextLengthExceeded ?? false,
+		...(metadata.contextOverflowRecovered === undefined
+			? {}
+			: { contextOverflowRecovered: metadata.contextOverflowRecovered }),
 		...(metadata.provider === undefined ? {} : { provider: metadata.provider }),
 		...(metadata.model === undefined ? {} : { model: metadata.model }),
 		...(metadata.usage === undefined ? {} : { usage: metadata.usage }),
@@ -218,6 +223,9 @@ function normalizeMetadata(input: ResultEnvelopeInput): ResultMetadata {
 		...(metadata.nonFatalStreamErrors === undefined
 			? {}
 			: { nonFatalStreamErrors: metadata.nonFatalStreamErrors }),
+		...(metadata.recoveredStreamErrors === undefined
+			? {}
+			: { recoveredStreamErrors: metadata.recoveredStreamErrors }),
 		...(metadata.parseErrors === undefined
 			? {}
 			: { parseErrors: metadata.parseErrors }),

package/node_modules/@agwab/pi-subagent/src/core/constants.ts

@@ -16,6 +16,11 @@ export const FAILURE_KINDS = [
 	"sandbox",
 	"rpc",
 	"model",
+	"provider_error",
+	"model_error",
+	"output_schema_error",
+	"guard_failure",
+	"user_cancelled",
 	"tool",
 	"exit",
 	"parse",
@@ -109,6 +114,10 @@ export interface ResolveInput {
 	mode?: ExecutionMode;
 	tasks?: SubagentTaskInput[];
 	concurrency?: number;
+	/** Stop scheduling additional parallel siblings after the first failed result. */
+	failFast?: boolean;
+	/** Abort already-running parallel siblings after the first failed result. Implies fail-fast scheduling. */
+	cancelSiblingsOnFailure?: boolean;
 	asyncDependency?: AsyncDependency;
 	workspace?: WorkspaceInput | WorkspaceMode;
 	worktree?: boolean | string;

package/node_modules/@agwab/pi-subagent/src/core/validation.ts

@@ -572,6 +572,27 @@ export function validateResolveInput(
 		input.concurrency = concurrency;
 	}
 
+	if (raw.failFast !== undefined) {
+		const failFast = validateBoolean(
+			raw.failFast,
+			"failFast",
+			backendForKnownFailure,
+		);
+		if (typeof failFast !== "boolean") return failFast;
+		input.failFast = failFast;
+	}
+
+	if (raw.cancelSiblingsOnFailure !== undefined) {
+		const cancelSiblingsOnFailure = validateBoolean(
+			raw.cancelSiblingsOnFailure,
+			"cancelSiblingsOnFailure",
+			backendForKnownFailure,
+		);
+		if (typeof cancelSiblingsOnFailure !== "boolean")
+			return cancelSiblingsOnFailure;
+		input.cancelSiblingsOnFailure = cancelSiblingsOnFailure;
+	}
+
 	if (raw.chain !== undefined) {
 		return failure(
 			'chain mode is not supported by pi-subagent; use mode:"parallel" for fanout or have the parent orchestrate sequencing.',