@ilya-lesikov/pi-pi 0.9.0 → 0.11.0

package/3p/pi-subagents/src/settings.ts

@@ -0,0 +1,261 @@
+// Persistence for pi-subagents operational settings.
+// - Global:  ~/.pi/agent/subagents.json (via getAgentDir()) — manual defaults, never written here
+// - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { JoinMode, WidgetMode } from "./types.js";
+
+export interface SubagentsSettings {
+  maxConcurrent?: number;
+  /**
+   * 0 = unlimited — the extension's single source of truth for that convention:
+   * `normalizeMaxTurns()` in agent-runner.ts treats 0 → `undefined`, and the
+   * `/agents` → Settings input prompt explicitly says "0 = unlimited".
+   */
+  defaultMaxTurns?: number;
+  graceTurns?: number;
+  defaultJoinMode?: JoinMode;
+  /**
+   * Master switch for the schedule subagent feature. Defaults to `true`.
+   * When `false`: the `Agent` tool's `schedule` param + its guideline are
+   * stripped from the tool spec at registration (zero LLM-context cost), the
+   * scheduler doesn't bind to the session, and the `/agents → Scheduled jobs`
+   * menu entry is hidden. Schema-level removal applies at extension load
+   * (next pi session); runtime menu/runtime-fire short-circuit is immediate.
+   */
+  schedulingEnabled?: boolean;
+  /**
+   * When true, the effective model of each subagent spawn is validated
+   * against `enabledModels` from pi's settings — both global
+   * (`<agentDir>/settings.json`) and project-local (`<cwd>/.pi/settings.json`),
+   * with project overriding global (mirrors pi's SettingsManager deep-merge).
+   *
+   * scopeModels guards against runtime LLM choices, not user-level config.
+   * Out-of-scope handling reflects this:
+   *   - Caller-supplied via `Agent({ model: "..." })` (only when frontmatter
+   *     has no `model:`, since frontmatter is authoritative): hard error
+   *     returned to the orchestrator, listing the allowed models. The LLM
+   *     made an explicit out-of-scope choice and gets explicit feedback.
+   *   - Frontmatter-pinned: warning toast + the pinned model runs. The
+   *     agent's author/installer chose this; trust it.
+   *   - Parent-inherited (neither caller nor frontmatter sets a model):
+   *     warning toast + parent's model runs. The user chose the parent's
+   *     model when starting the session; trust it.
+   *
+   * No-op when pi's `enabledModels` is empty or absent — nothing to validate
+   * against. Defaults to false: subagents may use any model.
+   */
+  scopeModels?: boolean;
+  /**
+   * When true, the three built-in default agents (general-purpose, Explore, Plan)
+   * are not registered at startup. User-defined agents from .pi/agents/*.md are
+   * completely unaffected — only the hardcoded DEFAULT_AGENTS are suppressed.
+   * Defaults to false.
+   */
+  disableDefaultAgents?: boolean;
+  /**
+   * Which Agent tool description the LLM sees. "full" (default) is the rich
+   * Claude Code-style prompt; "compact" is a ~75% smaller version (one-line
+   * agent type list, terse usage notes) for small/local models where tool-spec
+   * tokens are expensive; "custom" reads `.pi/agent-tool-description.md`
+   * (project, falling back to `<agentDir>/agent-tool-description.md`) with
+   * `{{placeholder}}` substitution — a missing/empty file falls back to "full".
+   * The mode is read once at tool registration — changing it applies on the
+   * next pi session.
+   */
+  toolDescriptionMode?: ToolDescriptionMode;
+  /**
+   * Display mode for the persistent above-editor agent widget:
+   *   - `all`: show every agent (foreground + background).
+   *   - `background`: hide foreground agents — they already render inline as the
+   *     Agent tool result, so the widget would otherwise double-render them
+   *     (#118); everything else (background, queued, scheduled, RPC) stays.
+   *   - `off`: hide the widget entirely.
+   * Defaults to `background`. Pure-UI and applied live (toggling refreshes the
+   * widget).
+   */
+  widgetMode?: WidgetMode;
+}
+
+export type ToolDescriptionMode = "full" | "compact" | "custom";
+
+/** Setter hooks used by applySettings to wire persisted values into in-memory state. */
+export interface SettingsAppliers {
+  setMaxConcurrent: (n: number) => void;
+  setDefaultMaxTurns: (n: number) => void;
+  setGraceTurns: (n: number) => void;
+  setDefaultJoinMode: (mode: JoinMode) => void;
+  setSchedulingEnabled: (b: boolean) => void;
+  setScopeModels: (enabled: boolean) => void;
+  setDisableDefaultAgents: (b: boolean) => void;
+  setToolDescriptionMode: (mode: ToolDescriptionMode) => void;
+  setWidgetMode: (mode: WidgetMode) => void;
+}
+
+/** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
+export type SettingsEmit = (event: string, payload: unknown) => void;
+
+const VALID_JOIN_MODES: ReadonlySet<string> = new Set<JoinMode>(["async", "group", "smart"]);
+const VALID_TOOL_DESCRIPTION_MODES: ReadonlySet<string> = new Set<ToolDescriptionMode>(["full", "compact", "custom"]);
+const VALID_WIDGET_MODES: ReadonlySet<string> = new Set<WidgetMode>(["all", "background", "off"]);
+
+// Sanity ceilings — prevent hand-edited configs from asking for values that
+// make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
+// that any realistic power-user setting passes through.
+const MAX_CONCURRENT_CEILING = 1024;
+const MAX_TURNS_CEILING = 10_000;
+const GRACE_TURNS_CEILING = 1_000;
+
+/** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
+function sanitize(raw: unknown): SubagentsSettings {
+  if (!raw || typeof raw !== "object") return {};
+  const r = raw as Record<string, unknown>;
+  const out: SubagentsSettings = {};
+  if (
+    Number.isInteger(r.maxConcurrent) &&
+    (r.maxConcurrent as number) >= 1 &&
+    (r.maxConcurrent as number) <= MAX_CONCURRENT_CEILING
+  ) {
+    out.maxConcurrent = r.maxConcurrent as number;
+  }
+  if (
+    Number.isInteger(r.defaultMaxTurns) &&
+    (r.defaultMaxTurns as number) >= 0 &&
+    (r.defaultMaxTurns as number) <= MAX_TURNS_CEILING
+  ) {
+    out.defaultMaxTurns = r.defaultMaxTurns as number;
+  }
+  if (
+    Number.isInteger(r.graceTurns) &&
+    (r.graceTurns as number) >= 1 &&
+    (r.graceTurns as number) <= GRACE_TURNS_CEILING
+  ) {
+    out.graceTurns = r.graceTurns as number;
+  }
+  if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode)) {
+    out.defaultJoinMode = r.defaultJoinMode as JoinMode;
+  }
+  if (typeof r.schedulingEnabled === "boolean") {
+    out.schedulingEnabled = r.schedulingEnabled;
+  }
+  if (typeof r.scopeModels === "boolean") {
+    out.scopeModels = r.scopeModels;
+  }
+  if (typeof r.disableDefaultAgents === "boolean") {
+    out.disableDefaultAgents = r.disableDefaultAgents;
+  }
+  if (typeof r.toolDescriptionMode === "string" && VALID_TOOL_DESCRIPTION_MODES.has(r.toolDescriptionMode)) {
+    out.toolDescriptionMode = r.toolDescriptionMode as ToolDescriptionMode;
+  }
+  if (typeof r.widgetMode === "string" && VALID_WIDGET_MODES.has(r.widgetMode)) {
+    out.widgetMode = r.widgetMode as WidgetMode;
+  }
+  return out;
+}
+
+function globalPath(): string {
+  return join(getAgentDir(), "subagents.json");
+}
+
+function projectPath(cwd: string): string {
+  return join(cwd, ".pi", "subagents.json");
+}
+
+/**
+ * Read a settings file. Missing file is silent (returns `{}`). A file that
+ * exists but can't be parsed emits a warning to stderr so users aren't
+ * silently reverted to defaults — and still returns `{}` so startup proceeds.
+ */
+function readSettingsFile(path: string): SubagentsSettings {
+  if (!existsSync(path)) return {};
+  try {
+    return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);
+    return {};
+  }
+}
+
+/** Load merged settings: global provides defaults, project overrides. */
+export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+}
+
+/**
+ * Write project-local settings. Global is never touched from code.
+ * Returns `true` on success, `false` if the write (or mkdir) failed so the
+ * caller can surface a warning — persistence isn't fatal but isn't silent.
+ */
+export function saveSettings(s: SubagentsSettings, cwd: string = process.cwd()): boolean {
+  const path = projectPath(cwd);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(s, null, 2), "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Apply persisted settings to the in-memory state via caller-supplied setters. */
+export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers): void {
+  if (typeof s.maxConcurrent === "number") appliers.setMaxConcurrent(s.maxConcurrent);
+  if (typeof s.defaultMaxTurns === "number") appliers.setDefaultMaxTurns(s.defaultMaxTurns);
+  if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
+  if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
+  if (typeof s.schedulingEnabled === "boolean") appliers.setSchedulingEnabled(s.schedulingEnabled);
+  if (typeof s.scopeModels === "boolean") appliers.setScopeModels(s.scopeModels);
+  if (typeof s.disableDefaultAgents === "boolean") appliers.setDisableDefaultAgents(s.disableDefaultAgents);
+  if (s.toolDescriptionMode) appliers.setToolDescriptionMode(s.toolDescriptionMode);
+  if (s.widgetMode) appliers.setWidgetMode(s.widgetMode);
+}
+
+/**
+ * Format the user-facing toast for a settings mutation. Pure function —
+ * routes the success/failure of `saveSettings` into the right message + level
+ * so the UI layer (index.ts) stays a thin wire between input and notification.
+ */
+export function persistToastFor(
+  successMsg: string,
+  persisted: boolean,
+): { message: string; level: "info" | "warning" } {
+  return persisted
+    ? { message: successMsg, level: "info" }
+    : { message: `${successMsg} (session only; failed to persist)`, level: "warning" };
+}
+
+/**
+ * Load merged settings, apply them to in-memory state, and emit the
+ * `subagents:settings_loaded` lifecycle event. Returns the loaded settings so
+ * callers can log/inspect. Extension init wires this once.
+ */
+export function applyAndEmitLoaded(
+  appliers: SettingsAppliers,
+  emit: SettingsEmit,
+  cwd: string = process.cwd(),
+): SubagentsSettings {
+  const settings = loadSettings(cwd);
+  applySettings(settings, appliers);
+  emit("subagents:settings_loaded", { settings });
+  return settings;
+}
+
+/**
+ * Persist a settings snapshot, emit the `subagents:settings_changed` event
+ * (regardless of persist outcome so listeners see the in-memory change), and
+ * return the toast the UI should display. Event payload carries the `persisted`
+ * flag so listeners can react to write failures.
+ */
+export function saveAndEmitChanged(
+  snapshot: SubagentsSettings,
+  successMsg: string,
+  emit: SettingsEmit,
+  cwd: string = process.cwd(),
+): { message: string; level: "info" | "warning" } {
+  const persisted = saveSettings(snapshot, cwd);
+  emit("subagents:settings_changed", { settings: snapshot, persisted });
+  return persistToastFor(successMsg, persisted);
+}

package/3p/pi-subagents/src/skill-loader.ts

@@ -1,79 +1,102 @@
 /**
- * skill-loader.ts — Preload specific skill files and inject their content into the system prompt.
+ * skill-loader.ts — Preload named skills.
  *
- * When skills is a string[], reads each named skill from .pi/skills/ or ~/.pi/skills/
- * and returns their content for injection into the agent's system prompt.
+ * Roots, in precedence order:
+ *   - <cwd>/.pi/skills           (project, Pi's standard)
+ *   - <cwd>/.agents/skills       (project, cross-tool Agent Skills spec — https://agentskills.io)
+ *   - getAgentDir()/skills       (user, default ~/.pi/agent/skills — Pi's standard)
+ *   - ~/.agents/skills           (user, cross-tool Agent Skills spec)
+ *   - ~/.pi/skills               (legacy global, pre-Pi)
+ *
+ * Layout per root:
+ *   - <root>/<name>.md            (flat file at the top level)
+ *   - <root>/.../<name>/SKILL.md  (directory skill, may be nested — Pi's standard)
+ *
+ * Recursion skips dotfile entries and node_modules. A directory that itself contains
+ * SKILL.md is a skill — we don't descend into it (Pi: skills don't nest).
+ *
+ * Symlinks are rejected for security (deviation from Pi, which follows them).
  */
 
+import type { Dirent } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { isUnsafeName, safeReadFile } from "./memory.js";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
 
 export interface PreloadedSkill {
   name: string;
   content: string;
 }
 
-/**
- * Attempt to load named skills from project and global skill directories.
- * Looks for: <dir>/<name>.md, <dir>/<name>.txt, <dir>/<name>
- *
- * @param skillNames  List of skill names to preload.
- * @param cwd         Working directory for project-level skills.
- * @returns Array of loaded skills (missing skills are skipped with a warning comment).
- */
 export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
-  const results: PreloadedSkill[] = [];
+  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+}
 
-  for (const name of skillNames) {
-    // Unlike memory (which throws on unsafe names because it's part of agent setup),
-    // skills are optional — skip gracefully to avoid blocking agent startup.
-    if (isUnsafeName(name)) {
-      results.push({ name, content: `(Skill "${name}" skipped: name contains path traversal characters)` });
-      continue;
-    }
-    const content = findAndReadSkill(name, cwd);
-    if (content !== undefined) {
-      results.push({ name, content });
-    } else {
-      // Include a note about missing skills so the agent knows it was requested but not found
-      results.push({ name, content: `(Skill "${name}" not found in .pi/skills/ or ~/.pi/skills/)` });
-    }
+function loadSkillContent(name: string, cwd: string): string {
+  if (isUnsafeName(name)) {
+    return `(Skill "${name}" skipped: name contains path traversal characters)`;
   }
+  const roots = [
+    join(cwd, ".pi", "skills"), // project — Pi standard
+    join(cwd, ".agents", "skills"), // project — Agent Skills spec
+    join(getAgentDir(), "skills"), // user — Pi standard
+    join(homedir(), ".agents", "skills"), // user — Agent Skills spec
+    join(homedir(), ".pi", "skills"), // legacy global, pre-Pi
+  ];
+  for (const root of roots) {
+    const content = findInRoot(root, name);
+    if (content !== undefined) return content;
+  }
+  return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
+}
 
-  return results;
+function findInRoot(root: string, name: string): string | undefined {
+  if (isSymlink(root)) return undefined; // reject symlinked roots entirely
+  const flat = safeReadFile(join(root, `${name}.md`))?.trim();
+  if (flat !== undefined) return flat;
+  return findSkillDirectory(root, name);
 }
 
-/**
- * Search for a skill file in project and global directories.
- * Project-level takes priority over global.
- */
-function findAndReadSkill(name: string, cwd: string): string | undefined {
-  const projectDir = join(cwd, ".pi", "skills");
-  const globalDir = join(homedir(), ".pi", "skills");
+/** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
+function findSkillDirectory(root: string, name: string): string | undefined {
+  if (!existsSync(root)) return undefined;
+  const queue: string[] = [root];
 
-  // Try project first, then global
-  for (const dir of [projectDir, globalDir]) {
-    const content = tryReadSkillFile(dir, name);
-    if (content !== undefined) return content;
-  }
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) continue;
 
-  return undefined;
-}
+    let entries: Dirent<string>[];
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
 
-/**
- * Try to read a skill file from a directory.
- * Tries extensions in order: .md, .txt, (no extension)
- */
-function tryReadSkillFile(dir: string, name: string): string | undefined {
-  const extensions = [".md", ".txt", ""];
+    // Deterministic byte-order traversal — locale-independent.
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
-  for (const ext of extensions) {
-    const path = join(dir, name + ext);
-    // safeReadFile rejects symlinks to prevent reading arbitrary files
-    const content = safeReadFile(path);
-    if (content !== undefined) return content.trim();
-  }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+
+      // Symlinked dirs already filtered by entry.isDirectory() — Dirent uses lstat semantics.
+      const path = join(current, entry.name);
+      const skillMd = join(path, "SKILL.md");
+      const isSkillDir = existsSync(skillMd);
 
+      if (isSkillDir) {
+        if (entry.name === name) {
+          const content = safeReadFile(skillMd)?.trim();
+          if (content !== undefined) return content;
+        }
+        continue; // Pi rule: skills don't nest — don't descend into a skill dir
+      }
+
+      queue.push(path);
+    }
+  }
   return undefined;
 }

package/3p/pi-subagents/src/status-note.ts

@@ -0,0 +1,25 @@
+/**
+ * status-note.ts — Parenthetical status note appended to agent result text.
+ */
+
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export function getStatusNote(status: string): string {
+  switch (status) {
+    case "stopped":
+      return " (STOPPED BY THE USER before completion — output is partial; the task was NOT finished)";
+    case "aborted":
+      return " (aborted — hit the turn limit before completion; output may be incomplete)";
+    case "steered":
+      return " (wrapped up at the turn limit — output may be partial)";
+    default:
+      return "";
+  }
+}

package/3p/pi-subagents/src/types.ts

@@ -2,8 +2,9 @@
  * types.ts — Type definitions for the subagent system.
  */
 
-import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { LifetimeUsage } from "./usage.js";
 
 export type { ThinkingLevel };
 
@@ -25,15 +26,25 @@ export interface AgentConfig {
   displayName?: string;
   description: string;
   builtinToolNames?: string[];
+  /** Raw `ext:` selector entries from the `tools:` CSV, e.g. ["ext:foo", "ext:bar/x"].
+   * Presence of any entry flips extension tools to an explicit allowlist. */
+  extSelectors?: string[];
   /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
   disallowedTools?: string[];
   /** true = inherit all, string[] = only listed, false = none */
   extensions: true | string[] | false;
+  /** Extension-name denylist applied after the `extensions:` include set. Exclude wins.
+   * Plain canonical names only (case-insensitive); no paths, no wildcard. */
+  excludeExtensions?: string[];
   /** true = inherit all, string[] = only listed, false = none */
   skills: true | string[] | false;
   model?: string;
   thinking?: ThinkingLevel;
   maxTurns?: number;
+  /** Persist this subagent as a normal pi session instead of keeping it in memory only. */
+  persistSession?: boolean;
+  /** Optional session directory used when persistSession is true. Omitted = pi's normal session location. */
+  sessionDir?: string;
   systemPrompt: string;
   promptMode: "replace" | "append";
   /** Default for spawn: fork parent conversation. undefined = caller decides. */
@@ -56,6 +67,15 @@ export interface AgentConfig {
 
 export type JoinMode = 'async' | 'group' | 'smart';
 
+/**
+ * Display mode for the persistent above-editor agent widget.
+ * - `all`: show every agent (foreground + background).
+ * - `background`: hide foreground agents (they already render inline as the
+ *   Agent tool result, #118); show background/queued/scheduled/RPC.
+ * - `off`: hide the widget entirely.
+ */
+export type WidgetMode = 'all' | 'background' | 'off';
+
 export interface AgentRecord {
   id: string;
   type: SubagentType;
@@ -76,19 +96,47 @@ export interface AgentRecord {
   /** Steering messages queued before the session was ready. */
   pendingSteers?: string[];
   /** Worktree info if the agent is running in an isolated worktree. */
-  worktree?: { path: string; branch: string };
+  worktree?: { path: string; branch: string; baseSha: string; workPath: string };
   /** Worktree cleanup result after agent completion. */
   worktreeResult?: { hasChanges: boolean; branch?: string };
   /** The tool_use_id from the original Agent tool call. */
   toolCallId?: string;
-  /** Whether the subagents:first_tool event has been emitted for this run. */
-  firstToolEmitted?: boolean;
-  /** Whether the subagents:first_turn event has been emitted for this run. */
-  firstTurnEmitted?: boolean;
   /** Path to the streaming output transcript file. */
   outputFile?: string;
   /** Cleanup function for the output file stream subscription. */
   outputCleanup?: () => void;
+  /**
+   * Lifetime usage breakdown, accumulated via `message_end` events. Survives
+   * compaction. Total = input + output + cacheWrite (cacheRead deliberately
+   * excluded — see issue #38). Initialized to zeros at spawn.
+   */
+  lifetimeUsage: LifetimeUsage;
+  /** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
+  compactionCount: number;
+  /**
+   * Whether this agent was spawned to run in the background. Tri-state, set at
+   * spawn from `SpawnOptions.isBackground`: `true` = background, `false` =
+   * foreground (has an inline Agent tool-result surface), `undefined` = the
+   * caller never declared it (e.g. a cross-extension RPC spawn, which is detached
+   * and has no inline surface). The widget's background-only filter keys off this
+   * — and excludes only explicit `false`, so `undefined` agents stay visible.
+   * Reliable across ALL spawn paths, unlike the UI-only `invocation` snapshot,
+   * which only the Agent-tool path populates.
+   */
+  isBackground?: boolean;
+  /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
+  invocation?: AgentInvocation;
+}
+
+export interface AgentInvocation {
+  /** Short display name, e.g. "haiku" — only set when different from parent. */
+  modelName?: string;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  runInBackground?: boolean;
+  isolation?: IsolationMode;
 }
 
 /** Details attached to custom notification messages for visual rendering. */
@@ -113,3 +161,46 @@ export interface EnvInfo {
   branch: string;
   platform: string;
 }
+
+/**
+ * A subagent spawn registered to fire on a schedule.
+ *
+ * Stored at `<cwd>/.pi/subagent-schedules/<sessionId>.json`. Session-scoped:
+ * survives `/resume` but resets on `/new`, mirroring pi-chonky-tasks.
+ */
+export interface ScheduledSubagent {
+  id: string;
+  /** Unique within store. Defaults to `description`. */
+  name: string;
+  description: string;
+  /** Raw user input — cron expr | "+10m" | ISO | "5m". */
+  schedule: string;
+  scheduleType: "cron" | "once" | "interval";
+  /** Computed at create time for interval/once. */
+  intervalMs?: number;
+
+  // spawn params (subset of Agent tool params; no inherit_context, no resume)
+  subagent_type: SubagentType;
+  prompt: string;
+  model?: string;
+  thinking?: ThinkingLevel;
+  max_turns?: number;
+  isolated?: boolean;
+  isolation?: IsolationMode;
+
+  // state
+  enabled: boolean;
+  /** ISO timestamp. */
+  createdAt: string;
+  lastRun?: string;
+  lastStatus?: "success" | "error" | "running";
+  /** Refreshed on every fire and on store load. */
+  nextRun?: string;
+  runCount: number;
+}
+
+export interface ScheduleStoreData {
+  /** For future migrations. */
+  version: 1;
+  jobs: ScheduledSubagent[];
+}