@maxiaochao/pi-toolkit 0.10.5 → 0.10.7

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2026-10-09 - v0.10.7
+
+- bundle scheduler v0.1.0: add session-scoped interval prompts with Agent and user controls
+- Add the bundled and independently installable `@maxiaochao/pi-scheduler` package for session-scoped interval prompts, manual triggering, lightweight TUI status, and shared Agent/user controls.
+
+## 2026-10-09 - v0.10.6
+
+- bundle herdr-subagents v0.4.3: add per-run status, neutral analyst persona, and tool-agnostic Agent Team protocol
+- Add per-run Herdr Subagents status queries so background review gates can inspect one run without polling the full history archive.
+- Make Agent Team a tool-agnostic concurrent review protocol, decouple models from rotating methodological roles, and add a neutral read-only analyst persona.
+- Remove Todo from the default toolkit bundle and loadout; users who want its progress UI can install `@maxiaochao/pi-todo` explicitly.
+
 ## 2026-10-08 - v0.10.5
 
 - bundle herdr-subagents v0.4.2: add Alt+P and /parent controls to return from child Agents

package/README.md

@@ -16,21 +16,44 @@ Update it:
 pi update npm:@maxiaochao/pi-toolkit
 ```
 
-The root package embeds the child-package source snapshots listed below. Install the complete toolkit or selected standalone children, not both.
+The root package embeds its enabled child-package source snapshots. Todo is intentionally excluded from the default toolkit and remains available as an opt-in standalone package.
+
+Existing toolkit users can pick up the change with:
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit
+```
+
+Restart Pi after updating. The `todo` tool and widget will no longer load. `pi update --extensions` has the same effect when updating all installed packages. Explicitly versioned sources remain pinned and must be changed or reinstalled without the old version suffix.
 
 ## Child packages
 
 | Package | Capability | Install | Update |
 |---|---|---|---|
-| [pi-todo](packages/todo/README.md) | Branch-local execution plans, guarded advancement, `/todos` history | `pi install npm:@maxiaochao/pi-todo` | `pi update npm:@maxiaochao/pi-todo` |
+| [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` |
 | [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` |
 | [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` |
 | [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` |
+| [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` |
 | [pi-worktree](packages/worktree/README.md) | Worktree CLI, completion, installer, and agent skill | `pi install npm:@maxiaochao/pi-worktree` | `pi update npm:@maxiaochao/pi-worktree` |
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
 
-Multiple standalone children may be installed together. Do not install a child alongside the complete toolkit because that exposes the same resource twice.
+Multiple standalone children may be installed together. `pi-todo` may also be installed alongside the complete toolkit because Todo is no longer bundled. Do not install another bundled child alongside the complete toolkit because that exposes the same resource twice.
+
+To keep Todo after updating the toolkit:
+
+```bash
+pi install npm:@maxiaochao/pi-todo
+```
+
+If Todo was already installed separately and should be removed completely:
+
+```bash
+pi remove npm:@maxiaochao/pi-todo
+```
+
+Use `--local` with install or remove when the package declaration belongs to a project's `.pi/settings.json` rather than personal settings.
 
 Root and child versions remain independent, but repository release tooling publishes a modified child and a new toolkit snapshot from the same commit. Run `pi update --extensions` to update all installed packages. Explicit version sources such as `npm:@maxiaochao/pi-toolkit@0.9.3` remain pinned.
 
@@ -64,7 +87,7 @@ bash scripts/install.sh
 | `html-artifact` | Build self-contained HTML explainers and diagrams |
 | `pdlog` | Decompress and inspect Pudu `.pdlog` files |
 | `herdr` | Control Herdr workspaces, tabs, panes, and agents |
-| `agent-team` | Run cross-vendor adversarial review through Herdr |
+| `agent-team` | Run tool-agnostic, cross-vendor adversarial review with independent concurrent agents |
 | `tapd` | Use the TAPD CLI for requirements, defects, tasks, and wikis |
 
 Package-specific skills, such as `pi-worktree`, are documented by their child package.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.5",
-  "description": "Personal pi coding agent toolkit: execution plans, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
+  "version": "0.10.7",
+  "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
     "packages/*"
@@ -12,10 +12,10 @@
   ],
   "files": [
     "extensions",
-    "packages/todo",
     "packages/cache-export",
     "packages/codex-edit",
     "packages/herdr-subagents",
+    "packages/scheduler",
     "packages/worktree",
     "themes",
     "README.md",
@@ -30,11 +30,11 @@
   },
   "pi": {
     "extensions": [
-      "./packages/todo/extensions/todo.ts",
       "./packages/cache-export/extensions/cache-export.ts",
       "./extensions/btw/index.ts",
       "./packages/codex-edit/extensions/codex-edit.ts",
-      "./packages/herdr-subagents/extensions/herdr-subagents.ts"
+      "./packages/herdr-subagents/extensions/herdr-subagents.ts",
+      "./packages/scheduler/extensions/scheduler.ts"
     ],
     "skills": [
       "./skills",
@@ -57,8 +57,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/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
-    "load-test": "pi -ne -e ./packages/todo/extensions/todo.ts && 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",
+    "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",
     "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/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2026-10-09 - v0.4.3
+
+- add per-run status, neutral analyst persona, and tool-agnostic Agent Team protocol
+- Add `herdr_subagents_control({ action: "status", runId })` for a compact snapshot of one queued, active, blocked, or settled run without loading the full history archive.
+- Add a neutral read-only `analyst` persona for tasks that assign models and methodological roles dynamically.
+
 ## 2026-10-08 - v0.4.2
 
 - add Alt+P and /parent controls to return from child Agents

package/packages/herdr-subagents/README.md

@@ -66,6 +66,14 @@ herdr_subagents({
 
 `tasks` is always a non-empty array: one item is a single task and multiple items form a batch. Set `background: true` for either form to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
 
+Background work normally relies on that terminal notification. When the user asks for progress or the parent must confirm a review gate before continuing, query only that run's compact snapshot:
+
+```text
+herdr_subagents_control({ action: "status", runId: "<run-id>" })
+```
+
+The snapshot reports the aggregate run state and every task's state, including a blocked question when present. It checks durable run state before queued state, never returns unrelated runs, and does not wait or trigger a parent turn. Do not poll full `history` for progress.
+
 A child missing required information reports `needs-input` with an exact question. The run becomes blocked, keeps its Herdr tab, pane, partial report, and Pi session, and returns control to the parent. Answer through the control tool to continue the original session:
 
 ```text
@@ -80,7 +88,7 @@ With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a tas
 
 ## History
 
-Run `/herdr-subagents history` or `herdr_subagents_control({ action: "history" })` to list compact project-local run and task reports after Herdr tabs close. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
+Run `/herdr-subagents history` or `herdr_subagents_control({ action: "history" })` to list the full compact project-local run and task archive after Herdr tabs close. History does not accept a run ID and is not a status interface. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
 
 Continue a saved conversation in a new Herdr tab with `herdr_subagents_control({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents_control({ action: "cleanup", runId: "<run-id>" })`. History has no automatic count-based eviction. The extension adds the runtime path to local Git excludes when available (and otherwise uses `.pi/.gitignore`) without overwriting unrelated rules.
 
@@ -192,6 +200,9 @@ The package includes these personas:
 | `worker` | write | `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` | Focused implementation work |
 | `explorer` | read | `read`, `bash`, `grep`, `find`, `ls` | Fast codebase investigation |
 | `reviewer` | read | `read`, `bash`, `grep`, `find`, `ls` | Correctness and maintainability review |
+| `analyst` | read | `read`, `bash`, `grep`, `find`, `ls` | Neutral analysis with the method and role supplied by each task |
+
+`analyst` deliberately does not bind a model or review method. Use the task-level `model` field when independent tasks need different models, and put roles such as auditor, replicator, or adversary in each task prompt.
 
 Persona definitions use Markdown frontmatter followed by the child system prompt. For example, save this as `.pi/herdr-subagents/agents/security-reviewer.md`:
 

package/packages/herdr-subagents/TESTING.md

@@ -10,18 +10,19 @@
 
 ## Cases
 
-- Resolve package, global, and project personas and validate frontmatter/configuration.
+- Resolve package, global, and project personas and validate frontmatter/configuration, including the neutral read-only `analyst` persona.
 - Run foreground tasks and FIFO bounded-concurrency batches through an injectable Herdr boundary.
 - Verify all paths use interactive Agent start/prompt without print mode, shell injection, markers, or pane reuse.
-- Force write-capable batches to serial execution while allowing bounded read-only parallelism.
+- Force write-capable batches to serial execution while allowing bounded read-only parallelism, including three concurrent `analyst` tasks with independent task-level models.
 - Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
 - Recover queued/running work after interruption without retrying post-prompt side effects, including truncated reports and recovery errors.
 - Verify the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, child `/parent` and `Alt+P` return controls, and stable display while another background run queues.
 - Verify Fleet divider/row formatting, warning/yellow running indicators, success/green completed indicators, persona and task projections, cumulative active duration across blocking/resume, exact Pi usage aggregation from assistant messages, tool results, standalone usage, compaction, and branch summaries, malformed/truncated JSONL tolerance, queued metric omission, and visible-column bounds at narrow widths.
 - Verify live token updates are file-event driven and polled on each running one-second tick, elapsed repainting exists only while work runs, and widget disposal closes watchers and timers.
 - Verify selected active/queued run cancellation, blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, idempotent missing-tab cleanup, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
+- Verify `status(runId)` isolates one run, projects queue-only state, prefers durable state over a stale queue record, exposes blocked questions, marks terminal states settled, rejects unknown IDs, and leaves full `history` semantics unchanged.
 - Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
 
 ## Latest baseline
 
-All 169 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.
+All 179 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.

package/packages/herdr-subagents/agents/analyst.md

@@ -0,0 +1,8 @@
+---
+name: analyst
+description: Neutral read-only analyst for dynamically assigned roles
+access: read
+tools: read, bash, grep, find, ls
+---
+
+Act as an independent analyst and follow the role and evaluation method in the task prompt. Do not modify project files. Separate direct evidence, inference, and unknowns, and report concrete evidence with useful paths.

package/packages/herdr-subagents/extensions/herdr-subagents.ts

@@ -259,7 +259,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.registerTool({
 		name: "herdr_subagents_control",
 		label: "Herdr Subagents Control",
-		description: "Inspect Herdr personas and run history, cancel active or queued work, answer a blocked task, resume a saved task, or remove a selected archived run. Use herdr_subagents to start new work.",
+		description: "Inspect Herdr personas, query one run by ID, list run history, cancel active or queued work, answer a blocked task, resume a saved task, or remove a selected archived run. Use status for one run and history only for the full archive. Use herdr_subagents to start new work.",
 		promptSnippet: "Inspect and control Herdr subagent runs",
 		parameters: HerdrSubagentsControlParams,
 

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [

package/packages/herdr-subagents/src/parameters.ts

@@ -16,8 +16,8 @@ export const HerdrSubagentsParams = Type.Object({
 }, { additionalProperties: false });
 
 export const HerdrSubagentsControlParams = Type.Object({
-	action: StringEnum(["list", "respond", "history", "resume", "cancel", "cleanup"] as const, { description: "Control operation to perform." }),
-	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by respond, resume, cancel, or cleanup." })),
+	action: StringEnum(["list", "status", "respond", "history", "resume", "cancel", "cleanup"] as const, { description: "Control operation to perform." }),
+	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by status, respond, resume, cancel, or cleanup." })),
 	answer: Type.Optional(Type.String({ minLength: 1, description: "Answer sent to a blocked task when action is respond." })),
 	task: Type.Optional(Type.Integer({ minimum: 1, description: "One-based task number selected for respond or resume." })),
 	prompt: Type.Optional(Type.String({ minLength: 1, description: "Follow-up prompt used by resume." })),

package/packages/herdr-subagents/src/status.ts

@@ -0,0 +1,95 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { loadQueuedRuns } from "./queued-runs.ts";
+import { isSettledRunStatus, readReport, readRunRecord, readTaskRecord, type RunStatus, type TaskStatus } from "./records.ts";
+import { findRunDirectory } from "./run-locator.ts";
+
+export interface RunStatusTask {
+	order: number;
+	name: string;
+	agent: string;
+	status: TaskStatus;
+	summary?: string;
+	question?: string;
+	error?: string;
+}
+
+export interface RunStatusSnapshot {
+	runId: string;
+	label: string;
+	status: RunStatus;
+	settled: boolean;
+	source: "run" | "queue";
+	queuedAt?: string;
+	startedAt?: string;
+	updatedAt?: string;
+	completedAt?: string;
+	question?: string;
+	error?: string;
+	tasks: RunStatusTask[];
+}
+
+async function loadDurableStatus(cwd: string, runId: string): Promise<RunStatusSnapshot | undefined> {
+	const runsDirectory = join(cwd, ".pi", "herdr-subagents", "runs");
+	const runDirectory = await findRunDirectory(runsDirectory, runId);
+	if (!runDirectory) return undefined;
+	const run = await readRunRecord(join(runDirectory, "run.json"));
+	const tasksDirectory = join(runDirectory, "tasks");
+	const tasks: RunStatusTask[] = [];
+	if (existsSync(tasksDirectory)) for (const entry of readdirSync(tasksDirectory).sort()) {
+		const taskDirectory = join(tasksDirectory, entry);
+		const task = await readTaskRecord(join(taskDirectory, "task.json"));
+		const reportFile = join(taskDirectory, "report.json");
+		const reportIsCurrent = task.status === "blocked" || isSettledRunStatus(task.status);
+		const report = reportIsCurrent && existsSync(reportFile) ? await readReport(reportFile) : undefined;
+		const question = report?.question ?? task.question;
+		const error = report?.error ?? task.error;
+		tasks.push({
+			order: task.order,
+			name: task.name ?? task.agent ?? `Task ${task.order}`,
+			agent: task.agent ?? "worker",
+			status: task.status,
+			...(report?.summary ? { summary: report.summary } : {}),
+			...(question ? { question } : {}),
+			...(error ? { error } : {}),
+		});
+	}
+	return {
+		runId: run.id,
+		label: run.label,
+		status: run.status,
+		settled: isSettledRunStatus(run.status),
+		source: "run",
+		...(run.startedAt ? { startedAt: run.startedAt } : {}),
+		...(run.updatedAt ? { updatedAt: run.updatedAt } : {}),
+		...(run.completedAt ? { completedAt: run.completedAt } : {}),
+		...(run.question ? { question: run.question } : {}),
+		...(run.error ? { error: run.error } : {}),
+		tasks: tasks.sort((left, right) => left.order - right.order),
+	};
+}
+
+export async function getSubagentRunStatus(cwd: string, runId: string): Promise<RunStatusSnapshot | undefined> {
+	const durable = await loadDurableStatus(cwd, runId);
+	if (durable) return durable;
+	const queued = (await loadQueuedRuns(cwd)).find((candidate) => candidate.runId === runId);
+	if (!queued) return undefined;
+	return {
+		runId: queued.runId,
+		label: queued.params.label ?? "batch",
+		status: "queued",
+		settled: false,
+		source: "queue",
+		queuedAt: queued.queuedAt,
+		tasks: queued.params.tasks.map((task, index) => ({ order: index + 1, name: task.name, agent: task.agent ?? "worker", status: "queued" })),
+	};
+}
+
+export function runStatusText(status: RunStatusSnapshot): string {
+	const lines = [`${status.runId} · ${status.label} · ${status.status} · ${status.tasks.length} tasks`];
+	for (const task of status.tasks) {
+		const detail = task.question ? ` — ${task.question}` : task.summary ? ` — ${task.summary}` : task.error ? ` — ${task.error}` : "";
+		lines.push(`  ${task.order}. ${task.name}: ${task.status}${detail}`);
+	}
+	return lines.join("\n");
+}

package/packages/herdr-subagents/src/tool.ts

@@ -8,6 +8,7 @@ import { HERDR_ACTIONS, validateControlParams, validateRunParams } from "./valid
 import type { OwnerIdentity } from "./ownership.ts";
 import { cancelActiveSubagentRuns } from "./reconcile.ts";
 import { cancelQueuedRuns, loadQueuedRuns } from "./queued-runs.ts";
+import { getSubagentRunStatus, runStatusText } from "./status.ts";
 
 export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
 
@@ -19,7 +20,7 @@ export interface HerdrSubagentsRunParams {
 }
 
 export interface HerdrSubagentsControlToolParams {
-	action: "list" | "respond" | "history" | "resume" | "cancel" | "cleanup";
+	action: "list" | "status" | "respond" | "history" | "resume" | "cancel" | "cleanup";
 	runId?: string;
 	answer?: string;
 	task?: number;
@@ -28,7 +29,7 @@ export interface HerdrSubagentsControlToolParams {
 
 /** Internal superset used by shared execution helpers. */
 export interface HerdrSubagentsToolParams {
-	action?: "list" | "respond" | "history" | "resume" | "cancel" | "cleanup";
+	action?: "list" | "status" | "respond" | "history" | "resume" | "cancel" | "cleanup";
 	prompt?: string;
 	agent?: string;
 	label?: string;
@@ -114,6 +115,16 @@ const errorResponse = (text: string, details: Record<string, unknown> = {}): Too
 });
 
 const actionHandlers = {
+	async status({ params, ctx }: ToolExecutionContext) {
+		try {
+			const runId = (params.runId as string).trim();
+			const status = await getSubagentRunStatus(ctx.cwd, runId);
+			if (!status) return errorResponse(`Unknown Subagent run '${runId}'.`, { action: "status", runId });
+			return { content: [{ type: "text", text: runStatusText(status) }], details: { action: "status", ...status } };
+		} catch (error) {
+			return errorResponse(error instanceof Error ? error.message : String(error), { action: "status", runId: params.runId });
+		}
+	},
 	async history({ ctx }: ToolExecutionContext) {
 		const history = await listSubagentHistory(ctx.cwd);
 		return { content: [{ type: "text", text: historyText(history) }], details: { action: "history", runs: history } };

package/packages/herdr-subagents/src/validation.ts

@@ -3,6 +3,7 @@ import type { HerdrSubagentsControlToolParams, HerdrSubagentsRunParams } from ".
 export const HERDR_ACTIONS = {
 	list: { allowed: ["action"], includeRunId: false },
 	history: { allowed: ["action"], includeRunId: false },
+	status: { allowed: ["action", "runId"], includeRunId: true },
 	cancel: { allowed: ["action", "runId"], includeRunId: true },
 	cleanup: { allowed: ["action", "runId"], includeRunId: true },
 	respond: { allowed: ["action", "runId", "answer", "task"], includeRunId: true },
@@ -19,7 +20,7 @@ export function validateControlParams(params: HerdrSubagentsControlToolParams):
 	if (!allowed) return "Provide a valid control action.";
 	const extra = Object.keys(params).find((key) => !allowed.includes(key as keyof HerdrSubagentsControlToolParams));
 	if (extra) return `Field '${extra}' is not valid with action '${params.action}'.`;
-	if ((params.action === "cancel" || params.action === "cleanup") && !params.runId?.trim()) return `runId is required for action '${params.action}'.`;
+	if ((params.action === "status" || params.action === "cancel" || params.action === "cleanup") && !params.runId?.trim()) return `runId is required for action '${params.action}'.`;
 	if (params.action === "respond" && (!params.runId?.trim() || !params.answer?.trim())) return "runId and answer are required for action 'respond'.";
 	if (params.action === "resume" && (!params.runId?.trim() || !params.task || !params.prompt?.trim())) return "runId, task, and prompt are required for action 'resume'.";
 	return undefined;

package/packages/herdr-subagents/tests/extension-contract.ts

@@ -251,6 +251,10 @@ export default function (_pi: ExtensionAPI) {
 		if (!controlSchema.properties?.[name]?.description) throw new Error(`control schema property '${name}' is missing or undocumented`);
 	}
 	if (!controlSchema.required?.includes("action")) throw new Error("herdr_subagents_control action must be required");
+	const controlActions = controlSchema.properties.action.enum ?? controlSchema.properties.action.anyOf?.map((entry: Record<string, unknown>) => entry.const);
+	if (!controlActions?.includes("status")) throw new Error("herdr_subagents_control action enum must include status");
+	if (!/status/.test(controlSchema.properties.runId.description)) throw new Error("control runId description must document status");
+	if (!/Use status for one run/.test(controlTool.description)) throw new Error("control tool description must distinguish status from history");
 	if (!/Foreground calls block/.test(tool.description) || !/background calls return a run ID immediately/.test(tool.description)) {
 		throw new Error("tool description does not distinguish foreground and background execution");
 	}

package/packages/herdr-subagents/tests/run-tests.mjs

@@ -141,14 +141,16 @@ function latestRunDirectory() {
 try {
 	check("run validation accepts one or more tasks", validateRunParams({ tasks: [{ name: "one", prompt: "do it" }], concurrency: 2, background: true }) === undefined);
 	check("control validation accepts supported calls", [
-		{ action: "list" }, { action: "history" }, { action: "cancel", runId: "run" }, { action: "cleanup", runId: "run" },
+		{ action: "list" }, { action: "history" }, { action: "status", runId: "run" }, { action: "cancel", runId: "run" }, { action: "cleanup", runId: "run" },
 		{ action: "respond", runId: "run", answer: "yes", task: 1 },
 		{ action: "resume", runId: "run", task: 1, prompt: "continue" },
 	].every((params) => validateControlParams(params) === undefined));
-	check("all supported actions have shared validation and rendering metadata", ["list", "history", "cancel", "cleanup", "respond", "resume"].every((action) => action in HERDR_ACTIONS));
+	check("all supported actions have shared validation and rendering metadata", ["list", "history", "status", "cancel", "cleanup", "respond", "resume"].every((action) => action in HERDR_ACTIONS));
 	check("split validation rejects missing tasks and invalid control fields", [
 		validateRunParams({ tasks: [] }),
 		validateControlParams({ action: "list", prompt: "not allowed" }),
+		validateControlParams({ action: "status" }),
+		validateControlParams({ action: "history", runId: "not-allowed" }),
 		validateControlParams({ action: "respond", runId: "run" }),
 		validateControlParams({ action: "resume", runId: "run", task: 1 }),
 	].every((message) => typeof message === "string" && message.length > 0));
@@ -404,6 +406,9 @@ try {
 	writeFileSync(join(agentsDir, "broken.md"), "not frontmatter");
 	const discovery = discoverPackageAgents(agentsDir);
 	check("persona discovery and diagnostics", discovery.agents.length === 1 && discovery.agents[0].name === "worker" && discovery.diagnostics.length === 1);
+	const packageDiscovery = discoverPackageAgents(join(process.cwd(), "agents"));
+	const analystPersona = packageDiscovery.agents.find((persona) => persona.name === "analyst");
+	check("built-in analyst is neutral and read-only", packageDiscovery.diagnostics.length === 0 && analystPersona?.access === "read" && analystPersona.model === undefined && analystPersona.tools?.join(",") === "read,bash,grep,find,ls" && /independent analyst/.test(analystPersona.systemPrompt) && /direct evidence, inference, and unknowns/.test(analystPersona.systemPrompt) && !/auditor|replicator|adversary/.test(analystPersona.systemPrompt));
 
 	const configRoot = join(root, "configuration");
 	const packageAgents = join(configRoot, "package-agents");
@@ -443,6 +448,18 @@ try {
 	const configuredStart = configuredHerdr.calls.find(([name]) => name === "startAgent")[1];
 	check("configured persona uses displayed effective values", !configuredRun.isError && configuredStart.args.includes("task/model") && configuredStart.args.includes("high") && configuredStart.args.includes("--skill") && configuredStart.args.includes("project-skill"));
 
+	const analystHerdr = fakeHerdr();
+	const analystBatch = await executeHerdrSubagents({ label: "independent-analysis", concurrency: 3, tasks: [
+		{ name: "sol-audit", prompt: "slow audit", agent: "analyst", model: "vendor/sol" },
+		{ name: "grok-replicate", prompt: "slow replicate", agent: "analyst", model: "vendor/grok" },
+		{ name: "opus-challenge", prompt: "slow challenge", agent: "analyst", model: "vendor/opus" },
+	] }, undefined, undefined, { cwd: root, model: { provider: "parent", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: analystHerdr });
+	const analystStarts = analystHerdr.calls.filter(([name]) => name === "startAgent").map(([, request]) => request);
+	const analystModels = analystStarts.map((request) => request.args[request.args.indexOf("--model") + 1]);
+	check("three read-only analyst tasks run concurrently", !analystBatch.isError && analystBatch.details.effectiveConcurrency === 3 && analystHerdr.maxActive === 3);
+	check("analyst tasks preserve independent model overrides", analystModels.join(",") === "vendor/sol,vendor/grok,vendor/opus");
+	check("completed analyst batch closes its run tab", analystHerdr.calls.at(-1)?.[0] === "closeTab");
+
 	const batchHerdr = fakeHerdr();
 	const batchUpdates = [];
 	const batch = await executeHerdrSubagents({ label: "reviews", concurrency: 2, tasks: [
@@ -603,10 +620,31 @@ try {
 	const stableHerdr = fakeHerdr();
 	const stable = await executeHerdrSubagents({ tasks: [{ name: "stable", prompt: "stable", agent: "explorer" }] }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: stableHerdr, runId: backgroundId });
 	check("preallocated background run id stays stable", stable.details.runId === backgroundId && readFileSync(join(stable.details.recordDirectory, "run.json"), "utf8").includes(backgroundId));
+	const stableStatus = await executeHerdrSubagents({ action: "status", runId: backgroundId }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents") });
+	check("status returns only one durable run with task details", !stableStatus.isError && stableStatus.details.runId === backgroundId && stableStatus.details.status === "completed" && stableStatus.details.settled === true && stableStatus.details.source === "run" && stableStatus.details.tasks[0].name === "stable" && !stableStatus.content[0].text.includes("run-one"));
+	await persistQueuedRun(root, backgroundId, { label: "stale-queue", tasks: [{ name: "wrong-source", prompt: "queued" }], background: true });
+	const durableFirstStatus = await executeHerdrSubagents({ action: "status", runId: backgroundId }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents") });
+	check("status prefers durable state over a stale queue record", durableFirstStatus.details.source === "run" && durableFirstStatus.details.label !== "stale-queue" && durableFirstStatus.details.tasks[0].name === "stable");
+	const queuedStatusId = "queued-status-id";
+	await persistQueuedRun(root, queuedStatusId, { label: "queued-status", tasks: [{ name: "waiting", prompt: "wait", agent: "reviewer" }], background: true });
+	const queuedStatus = await executeHerdrSubagents({ action: "status", runId: queuedStatusId }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents") });
+	check("status projects a queued run before durable records exist", !queuedStatus.isError && queuedStatus.details.source === "queue" && queuedStatus.details.status === "queued" && queuedStatus.details.settled === false && queuedStatus.details.tasks[0].status === "queued" && queuedStatus.details.tasks[0].agent === "reviewer");
+	const unknownStatus = await executeHerdrSubagents({ action: "status", runId: "unknown-status-id" }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents") });
+	check("status rejects unknown run IDs without falling back to history", unknownStatus.isError && unknownStatus.content[0].text === "Unknown Subagent run 'unknown-status-id'.");
+	const staleStatusRoot = join(root, "stale-status-report");
+	const staleStatusTaskDirectory = join(staleStatusRoot, ".pi", "herdr-subagents", "runs", "stale", "tasks", "01-task");
+	mkdirSync(staleStatusTaskDirectory, { recursive: true });
+	writeFileSync(join(staleStatusTaskDirectory, "..", "..", "run.json"), JSON.stringify({ id: "stale-status", label: "stale-status", status: "running", startedAt: "2026-10-08T00:00:00.000Z" }));
+	writeFileSync(join(staleStatusTaskDirectory, "task.json"), JSON.stringify({ id: "stale-task", runId: "stale-status", order: 1, name: "stale-task", agent: "reviewer", status: "running" }));
+	writeFileSync(join(staleStatusTaskDirectory, "report.json"), JSON.stringify({ status: "needs-input", summary: "Old blocked report.", question: "Old question?", documents: [] }));
+	const runningStatus = await executeHerdrSubagents({ action: "status", runId: "stale-status" }, undefined, undefined, { cwd: staleStatusRoot }, { agentsDirectory: join(process.cwd(), "agents") });
+	check("running status does not expose a stale report from an earlier blocked turn", runningStatus.details.tasks[0].status === "running" && !runningStatus.details.tasks[0].question && !runningStatus.details.tasks[0].summary && !runningStatus.content[0].text.includes("Old question"));
 
 	const blockedHerdr = fakeHerdr("blocked");
 	const blocked = await executeHerdrSubagents({ concurrency: 1, tasks: [{ name: "question", prompt: "inspect branch", agent: "explorer" }, { name: "after-answer", prompt: "continue queued", agent: "reviewer" }] }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: blockedHerdr });
 	check("needs-input returns foreground control and preserves tab", blocked.details.status === "blocked" && blocked.details.tasks[0].question === "Which branch should I inspect?" && !blockedHerdr.calls.some(([name]) => name === "closeTab"));
+	const blockedStatus = await executeHerdrSubagents({ action: "status", runId: blocked.details.runId }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents") });
+	check("status exposes blocked task questions for respond", blockedStatus.details.status === "blocked" && blockedStatus.details.settled === false && blockedStatus.details.tasks[0].question === "Which branch should I inspect?" && blockedStatus.content[0].text.includes("Which branch should I inspect?"));
 	const activeCleanup = await executeHerdrSubagents({ action: "cleanup", runId: blocked.details.runId }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents"), herdr: blockedHerdr });
 	check("cleanup refuses to delete an active blocked run", activeCleanup.isError && activeCleanup.content[0].text.includes("still active") && existsSync(blocked.details.recordDirectory));
 	const resumeUpdates = [];

package/packages/scheduler/CHANGELOG.md

@@ -0,0 +1,5 @@
+## 2026-10-09 - v0.1.0
+
+- add session-scoped interval prompts with Agent and user controls
+- Add session-scoped interval prompts controlled by both the Agent tool and `/schedule` command.
+- Add manual trigger, cancellation, missed-tick coalescing, and lightweight TUI status.

package/packages/scheduler/README.md

@@ -0,0 +1,57 @@
+# Pi Scheduler
+
+Session-scoped interval prompts for Pi. Scheduler does one thing: at a fixed interval, queue a prompt for the current main agent at a safe turn boundary.
+
+![Scheduler status and commands](docs/screenshot.png)
+
+![Scheduler demo](docs/demo.gif)
+
+## Why
+
+Use Scheduler when the agent should periodically re-check CI, logs, a review, or another changing condition. It is not Cron, a background process manager, or a durable workflow engine.
+
+## Install
+
+```bash
+pi install npm:@maxiaochao/pi-scheduler
+```
+
+Update it with `pi update npm:@maxiaochao/pi-scheduler`.
+
+## Agent tool
+
+```text
+schedule({ action: "add", every: "5m", prompt: "Check CI; report completion or failure." })
+schedule({ action: "list" })
+schedule({ action: "trigger", id: "schedule-1" })
+schedule({ action: "cancel", id: "schedule-1" })
+```
+
+## User command
+
+```text
+/schedule add 5m Check CI; report completion or failure.
+/schedule list
+/schedule trigger schedule-1
+/schedule cancel schedule-1
+```
+
+Manual trigger queues one prompt and does not move the regular next time. The TUI status line shows the active count and next trigger.
+
+## Semantics and limits
+
+- Intervals accept `s`, `m`, `h`, and `d`, from 1 second through 7 days.
+- Prompts use Pi `followUp`: an active agent turn finishes before the scheduled prompt runs.
+- At most one prompt per schedule remains pending; missed intervals coalesce instead of flooding the queue.
+- Schedules live only in the current session and are cleared on new/resume/fork/reload/quit.
+- Cancel stops future timer events. Pi cannot selectively withdraw a prompt already in its follow-up queue.
+- Timing is best-effort, not real-time. Recursive `setTimeout` uses absolute target times to avoid cumulative drift.
+- Calendar expressions, time zones, persistence, process monitoring, and script notifications are intentionally out of scope.
+
+## Remove
+
+```bash
+pi remove npm:@maxiaochao/pi-scheduler
+```
+
+Do not install both the standalone package and a toolkit release that already bundles Scheduler, or the tool and command will be registered twice.

package/packages/scheduler/TESTING.md

@@ -0,0 +1,19 @@
+# Testing Pi Scheduler
+
+Run from the repository root:
+
+```bash
+npm --prefix packages/scheduler test
+npm --prefix packages/scheduler run load-test
+npm pack ./packages/scheduler --dry-run
+```
+
+The deterministic core test uses a fake clock to verify duration parsing, absolute-time cadence, timed triggering, missed-tick coalescing, manual triggering, dropped-follow-up release, and cancellation. The extension test verifies tool/command parity, manual follow-up delivery, message-specific pending acknowledgement, settled-run fallback cleanup, TUI status, duplicate suppression, and shutdown timer cleanup.
+
+For a manual TUI check, run Pi with `-e ./packages/scheduler/extensions/scheduler.ts`, create a short schedule, confirm the status line appears, and verify the prompt starts only after the current turn settles.
+
+Regenerate package media with:
+
+```bash
+node scripts/capture-package-media.mjs
+```