@tintinweb/pi-subagents 0.6.3 → 0.7.0

package/src/index.ts

@@ -24,6 +24,8 @@ import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
+import { SubagentScheduler } from "./schedule.js";
+import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, type SubagentsSettings, saveAndEmitChanged } from "./settings.js";
 import { type AgentConfig, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType } from "./types.js";
 import {
@@ -40,6 +42,8 @@ import {
   SPINNER,
   type UICtx,
 } from "./ui/agent-widget.js";
+import { showSchedulesMenu } from "./ui/schedule-menu.js";
+import { addUsage, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage } from "./usage.js";
 
 // ---- Shared helpers ----
 
@@ -48,10 +52,10 @@ function textResult(msg: string, details?: AgentDetails) {
   return { content: [{ type: "text" as const, text: msg }], details: details as any };
 }
 
-/** Safe token formatting — wraps session.getSessionStats() in try-catch. */
-function safeFormatTokens(session: { getSessionStats(): { tokens: { total: number } } } | undefined): string {
-  if (!session) return "";
-  try { return formatTokens(session.getSessionStats().tokens.total); } catch { return ""; }
+/** Format an agent's lifetime token total, or "" when zero. */
+function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): string {
+  const t = getLifetimeTotal(o.lifetimeUsage);
+  return t > 0 ? formatTokens(t) : "";
 }
 
 /**
@@ -59,7 +63,15 @@ function safeFormatTokens(session: { getSessionStats(): { tokens: { total: numbe
  * Used by both foreground and background paths to avoid duplication.
  */
 function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
-  const state: AgentActivity = { activeTools: new Map(), toolUses: 0, turnCount: 1, maxTurns, tokens: "", responseText: "", session: undefined };
+  const state: AgentActivity = {
+    activeTools: new Map(),
+    toolUses: 0,
+    turnCount: 1,
+    maxTurns,
+    responseText: "",
+    session: undefined,
+    lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+  };
 
   const callbacks = {
     onToolActivity: (activity: { type: "start" | "end"; toolName: string }) => {
@@ -71,7 +83,6 @@ function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
         }
         state.toolUses++;
       }
-      state.tokens = safeFormatTokens(state.session);
       onStreamUpdate?.();
     },
     onTextDelta: (_delta: string, fullText: string) => {
@@ -85,6 +96,10 @@ function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
     onSessionCreated: (session: any) => {
       state.session = session;
     },
+    onAssistantUsage: (usage: { input: number; output: number; cacheWrite: number }) => {
+      addUsage(state.lifetimeUsage, usage);
+      onStreamUpdate?.();
+    },
   };
 
   return { state, callbacks };
@@ -120,13 +135,10 @@ function escapeXml(s: string): string {
 function formatTaskNotification(record: AgentRecord, resultMaxLen: number): string {
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
-  let totalTokens = 0;
-  try {
-    if (record.session) {
-      const stats = record.session.getSessionStats();
-      totalTokens = stats.tokens?.total ?? 0;
-    }
-  } catch { /* session stats unavailable */ }
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+  const contextPercent = getSessionContextPercent(record.session);
+  const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
+  const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
 
   const resultPreview = record.result
     ? record.result.length > resultMaxLen
@@ -142,7 +154,7 @@ function formatTaskNotification(record: AgentRecord, resultMaxLen: number): stri
     `<status>${escapeXml(status)}</status>`,
     `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
     `<result>${escapeXml(resultPreview)}</result>`,
-    `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses><duration_ms>${durationMs}</duration_ms></usage>`,
+    `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
     `</task-notification>`,
   ].filter(Boolean).join('\n');
 }
@@ -150,14 +162,14 @@ function formatTaskNotification(record: AgentRecord, resultMaxLen: number): stri
 /** Build AgentDetails from a base + record-specific fields. */
 function buildDetails(
   base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
-  record: { toolUses: number; startedAt: number; completedAt?: number; status: string; error?: string; id?: string; session?: any },
+  record: { toolUses: number; startedAt: number; completedAt?: number; status: string; error?: string; id?: string; session?: any; lifetimeUsage: LifetimeUsage },
   activity?: AgentActivity,
   overrides?: Partial<AgentDetails>,
 ): AgentDetails {
   return {
     ...base,
     toolUses: record.toolUses,
-    tokens: safeFormatTokens(record.session),
+    tokens: formatLifetimeTokens(record),
     turnCount: activity?.turnCount,
     maxTurns: activity?.maxTurns,
     durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
@@ -170,10 +182,7 @@ function buildDetails(
 
 /** Build notification details for the custom message renderer. */
 function buildNotificationDetails(record: AgentRecord, resultMaxLen: number, activity?: AgentActivity): NotificationDetails {
-  let totalTokens = 0;
-  try {
-    if (record.session) totalTokens = record.session.getSessionStats().tokens?.total ?? 0;
-  } catch {}
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
 
   return {
     id: record.id,
@@ -337,17 +346,15 @@ export default function (pi: ExtensionAPI) {
   /** Helper: build event data for lifecycle events from an AgentRecord. */
   function buildEventData(record: AgentRecord) {
     const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
-    let tokens: { input: number; output: number; total: number } | undefined;
-    try {
-      if (record.session) {
-        const stats = record.session.getSessionStats();
-        tokens = {
-          input: stats.tokens?.input ?? 0,
-          output: stats.tokens?.output ?? 0,
-          total: stats.tokens?.total ?? 0,
-        };
-      }
-    } catch { /* session stats unavailable */ }
+    // All three fields are lifetime-accumulated (Σ over every assistant message_end),
+    // so they survive compaction together — input + output ≤ total always.
+    // tokens is omitted when nothing was ever produced (e.g. agent errored before
+    // any message_end fired), preserving prior payload shape.
+    const u = record.lifetimeUsage;
+    const total = getLifetimeTotal(u);
+    const tokens = total > 0
+      ? { input: u.input, output: u.output, total }
+      : undefined;
     return {
       id: record.id,
       type: record.type,
@@ -408,6 +415,16 @@ export default function (pi: ExtensionAPI) {
       type: record.type,
       description: record.description,
     });
+  }, (record, info) => {
+    // Emit compacted event when agent's session compacts (preserves count on record).
+    pi.events.emit("subagents:compacted", {
+      id: record.id,
+      type: record.type,
+      description: record.description,
+      reason: info.reason,
+      tokensBefore: info.tokensBefore,
+      compactionCount: record.compactionCount,
+    });
   });
 
   // Expose manager via Symbol.for() global registry for cross-package access.
@@ -424,13 +441,38 @@ export default function (pi: ExtensionAPI) {
   // --- Cross-extension RPC via pi.events ---
   let currentCtx: ExtensionContext | undefined;
 
-  // Capture ctx from session_start for RPC spawn handler
+  // ---- Subagent scheduler ----
+  // Session-scoped: store is constructed inside session_start once sessionId
+  // is available. Mirrors pi-chonky-tasks's session-scoped task store —
+  // schedules reset on /new, restore on /resume.
+  const scheduler = new SubagentScheduler();
+
+  function startScheduler(ctx: ExtensionContext) {
+    try {
+      const sessionId = ctx.sessionManager?.getSessionId?.();
+      if (!sessionId) return;  // sessionId not yet available — try again on next event
+      const path = resolveStorePath(ctx.cwd, sessionId);
+      const store = new ScheduleStore(path);
+      scheduler.start(pi, ctx, manager, store);
+      pi.events.emit("subagents:scheduler_ready", { sessionId, jobCount: store.list().length });
+    } catch (err) {
+      // Scheduling is non-essential — log and move on so the rest of the
+      // extension keeps working if e.g. .pi/ is unwritable.
+      console.warn("[pi-subagents] Failed to start scheduler:", err);
+    }
+  }
+
+  // Capture ctx from session_start for RPC spawn handler + start the scheduler.
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
-    manager.clearCompleted();           // preserve existing behavior
+    manager.clearCompleted();
+    if (isSchedulingEnabled() && !scheduler.isActive()) startScheduler(ctx);
   });
 
-  pi.on("session_before_switch", () => { manager.clearCompleted(); });
+  pi.on("session_before_switch", () => {
+    manager.clearCompleted();
+    scheduler.stop();
+  });
 
   const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
     events: pi.events,
@@ -450,6 +492,7 @@ export default function (pi: ExtensionAPI) {
     unsubPingRpc();
     currentCtx = undefined;
     delete (globalThis as any)[MANAGER_KEY];
+    scheduler.stop();
     manager.abortAll();
     for (const timer of pendingNudges.values()) clearTimeout(timer);
     pendingNudges.clear();
@@ -464,6 +507,16 @@ export default function (pi: ExtensionAPI) {
   function getDefaultJoinMode(): JoinMode { return defaultJoinMode; }
   function setDefaultJoinMode(mode: JoinMode) { defaultJoinMode = mode; }
 
+  // Master switch for the schedule subagent feature. Defaults to enabled.
+  // Read once at extension init (before tool registration) so the Agent tool's
+  // param schema reflects the persisted setting. Runtime toggles via /agents
+  // → Settings short-circuit the menu entry + the execute-time addJob path
+  // immediately, but the schema-level removal only takes effect on next
+  // extension load (next pi session). Documented in CHANGELOG/README.
+  let schedulingEnabled = true;
+  function isSchedulingEnabled(): boolean { return schedulingEnabled; }
+  function setSchedulingEnabled(b: boolean) { schedulingEnabled = b; }
+
   // ---- Batch tracking for smart join mode ----
   // Collects background agent IDs spawned in the current turn for smart grouping.
   // Uses a debounced timer: each new agent resets the 100ms window so that all
@@ -557,12 +610,35 @@ export default function (pi: ExtensionAPI) {
       setDefaultMaxTurns,
       setGraceTurns,
       setDefaultJoinMode,
+      setSchedulingEnabled,
     },
     (event, payload) => pi.events.emit(event, payload),
   );
 
   // ---- Agent tool ----
 
+  // Schedule param + its guideline are gated on `schedulingEnabled` (read once
+  // at registration; flipping the setting later requires next pi session for
+  // the schema to update). Defining the shape once and spreading it via Partial
+  // preserves Type.Object's inference when present and produces a
+  // `schedule`-free schema when absent — zero LLM-context cost in disabled mode.
+  const scheduleParamShape = {
+    schedule: Type.Optional(
+      Type.String({
+        description:
+          'Opt-in only — fire later instead of now. Omit to run immediately (the default, almost always correct). ' +
+          'Formats: 6-field cron ("0 0 9 * * 1" = 9am Mon), interval ("5m"/"1h"), one-shot ("+10m" or ISO). ' +
+          'Forces run_in_background; incompatible with inherit_context and resume. Returns job ID.',
+      }),
+    ),
+  };
+  const scheduleParam: Partial<typeof scheduleParamShape> =
+    isSchedulingEnabled() ? scheduleParamShape : {};
+
+  const scheduleGuideline = isSchedulingEnabled()
+    ? `\n- Use \`schedule\` only when the user explicitly asked for scheduled / recurring / delayed execution (e.g. "every Monday", "in an hour"). Don't auto-schedule from vague intent like "monitor X" — run once now or ask.`
+    : "";
+
   pi.registerTool(defineTool({
     name: "Agent",
     label: "Agent",
@@ -586,7 +662,7 @@ Guidelines:
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.
-- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).`,
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).${scheduleGuideline}`,
     parameters: Type.Object({
       prompt: Type.String({
         description: "The task for the agent to perform.",
@@ -639,6 +715,7 @@ Guidelines:
           description: 'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
         }),
       ),
+      ...scheduleParam,
     }),
 
     // ---- Custom rendering: Claude Code style ----
@@ -792,6 +869,47 @@ Guidelines:
         tags: agentTags.length > 0 ? agentTags : undefined,
       };
 
+      // ---- Schedule: register a job, don't spawn now ----
+      if (params.schedule) {
+        if (!isSchedulingEnabled()) {
+          return textResult("Scheduling is disabled in this project. Enable via /agents → Settings → Scheduling.");
+        }
+        if (params.resume) {
+          return textResult("Cannot combine `schedule` with `resume` — schedules create fresh agents.");
+        }
+        if (params.inherit_context) {
+          return textResult("Cannot combine `schedule` with `inherit_context` — there is no parent conversation at fire time.");
+        }
+        if (params.run_in_background === false) {
+          return textResult("Cannot combine `schedule` with `run_in_background: false` — scheduled jobs always run in background.");
+        }
+        if (!scheduler.isActive()) {
+          return textResult("Scheduler is not active in this session yet. Try again after the session has fully started.");
+        }
+        try {
+          const job = scheduler.addJob({
+            name: params.description as string,
+            description: params.description as string,
+            schedule: params.schedule as string,
+            subagent_type: subagentType,
+            prompt: params.prompt as string,
+            model: params.model as string | undefined,
+            thinking: thinking,
+            max_turns: effectiveMaxTurns,
+            isolated: isolated,
+            isolation: isolation,
+          });
+          const next = scheduler.getNextRun(job.id);
+          return textResult(
+            `Scheduled "${job.name}" (id: ${job.id}, type: ${job.scheduleType}). ` +
+            `Next run: ${next ?? "(unknown)"}. ` +
+            `Manage via /agents → Scheduled jobs.`,
+          );
+        } catch (err) {
+          return textResult(err instanceof Error ? err.message : String(err));
+        }
+      }
+
       // Resume existing agent
       if (params.resume) {
         const existing = manager.getRecord(params.resume);
@@ -898,7 +1016,7 @@ Guidelines:
         const details: AgentDetails = {
           ...detailBase,
           toolUses: fgState.toolUses,
-          tokens: fgState.tokens,
+          tokens: formatLifetimeTokens(fgState),
           turnCount: fgState.turnCount,
           maxTurns: fgState.maxTurns,
           durationMs: Date.now() - startedAt,
@@ -944,6 +1062,7 @@ Guidelines:
         inheritContext,
         thinkingLevel: thinking,
         isolation,
+        signal,
         ...fgCallbacks,
       });
 
@@ -956,7 +1075,7 @@ Guidelines:
       }
 
       // Get final token count
-      const tokenText = safeFormatTokens(fgState.session);
+      const tokenText = formatLifetimeTokens(fgState);
 
       const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
 
@@ -1019,12 +1138,17 @@ Guidelines:
 
       const displayName = getDisplayName(record.type);
       const duration = formatDuration(record.startedAt, record.completedAt);
-      const tokens = safeFormatTokens(record.session);
-      const toolStats = tokens ? `Tool uses: ${record.toolUses} | ${tokens}` : `Tool uses: ${record.toolUses}`;
+      const tokens = formatLifetimeTokens(record);
+      const contextPercent = getSessionContextPercent(record.session);
+      const statsParts = [`Tool uses: ${record.toolUses}`];
+      if (tokens) statsParts.push(tokens);
+      if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
+      if (record.compactionCount) statsParts.push(`Compactions: ${record.compactionCount}`);
+      statsParts.push(`Duration: ${duration}`);
 
       let output =
         `Agent: ${record.id}\n` +
-        `Type: ${displayName} | Status: ${record.status} | ${toolStats} | Duration: ${duration}\n` +
+        `Type: ${displayName} | Status: ${record.status} | ${statsParts.join(" | ")}\n` +
         `Description: ${record.description}\n\n`;
 
       if (record.status === "running") {
@@ -1088,7 +1212,17 @@ Guidelines:
       try {
         await steerAgent(record.session, params.message);
         pi.events.emit("subagents:steered", { id: record.id, message: params.message });
-        return textResult(`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.`);
+        const tokens = formatLifetimeTokens(record);
+        const contextPercent = getSessionContextPercent(record.session);
+        const stateParts: string[] = [];
+        if (tokens) stateParts.push(tokens);
+        stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);
+        if (contextPercent !== null) stateParts.push(`context ${Math.round(contextPercent)}% full`);
+        if (record.compactionCount) stateParts.push(`${record.compactionCount} compaction${record.compactionCount === 1 ? "" : "s"}`);
+        return textResult(
+          `Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
+          `Current state: ${stateParts.join(" · ")}`,
+        );
       } catch (err) {
         return textResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`);
       }
@@ -1140,6 +1274,12 @@ Guidelines:
       options.push(`Agent types (${allNames.length})`);
     }
 
+    // Scheduled jobs entry (always present when scheduler is active)
+    if (scheduler.isActive()) {
+      const jobCount = scheduler.list().length;
+      options.push(`Scheduled jobs (${jobCount})`);
+    }
+
     // Actions
     options.push("Create new agent");
     options.push("Settings");
@@ -1163,6 +1303,9 @@ Guidelines:
     } else if (choice.startsWith("Agent types (")) {
       await showAllAgentsList(ctx);
       await showAgentsMenu(ctx);
+    } else if (choice.startsWith("Scheduled jobs (")) {
+      await showSchedulesMenu(ctx, scheduler);
+      await showAgentsMenu(ctx);
     } else if (choice === "Create new agent") {
       await showCreateWizard(ctx);
     } else if (choice === "Settings") {
@@ -1626,6 +1769,7 @@ ${systemPrompt}
       defaultMaxTurns: getDefaultMaxTurns() ?? 0,
       graceTurns: getGraceTurns(),
       defaultJoinMode: getDefaultJoinMode(),
+      schedulingEnabled: isSchedulingEnabled(),
     };
   }
 
@@ -1635,6 +1779,7 @@ ${systemPrompt}
       `Default max turns (current: ${getDefaultMaxTurns() ?? "unlimited"})`,
       `Grace turns (current: ${getGraceTurns()})`,
       `Join mode (current: ${getDefaultJoinMode()})`,
+      `Scheduling (current: ${isSchedulingEnabled() ? "enabled" : "disabled"})`,
     ]);
     if (!choice) return;
 
@@ -1685,6 +1830,27 @@ ${systemPrompt}
         setDefaultJoinMode(mode);
         notifyApplied(ctx, `Default join mode set to ${mode}`);
       }
+    } else if (choice.startsWith("Scheduling")) {
+      const val = await ctx.ui.select(
+        "Schedule subagent feature",
+        [
+          "enabled — Agent tool accepts a `schedule` param; /agents → Scheduled jobs visible",
+          "disabled — `schedule` removed from Agent tool spec (no LLM-context cost); menu hidden",
+        ],
+      );
+      if (val) {
+        const enabled = val.startsWith("enabled");
+        if (enabled === isSchedulingEnabled()) {
+          ctx.ui.notify(`Scheduling already ${enabled ? "enabled" : "disabled"}.`, "info");
+        } else {
+          setSchedulingEnabled(enabled);
+          if (!enabled) scheduler.stop();  // immediate kill — outstanding fires stop ticking
+          notifyApplied(
+            ctx,
+            `Scheduling ${enabled ? "enabled" : "disabled"}. Tool spec change takes effect on next pi session.`,
+          );
+        }
+      }
     }
   }
 

package/src/schedule-store.ts

@@ -0,0 +1,143 @@
+/**
+ * schedule-store.ts — File-backed store for scheduled subagents.
+ *
+ * Session-scoped: each pi session owns its own schedules at
+ * `<cwd>/.pi/subagent-schedules/<sessionId>.json`. `/new` starts a fresh
+ * empty store; `/resume` reloads.
+ *
+ * Concurrency model lifted from pi-chonky-tasks/src/task-store.ts: every
+ * mutation acquires a PID-based exclusion lock, re-reads the latest state
+ * from disk, applies the change, atomic-writes via temp+rename, releases.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ScheduledSubagent, ScheduleStoreData } from "./types.js";
+
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_RETRIES = 100;
+
+function isProcessRunning(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function acquireLock(lockPath: string): void {
+  for (let i = 0; i < LOCK_MAX_RETRIES; i++) {
+    try {
+      writeFileSync(lockPath, `${process.pid}`, { flag: "wx" });
+      return;
+    } catch (e: any) {
+      if (e.code === "EEXIST") {
+        try {
+          const pid = parseInt(readFileSync(lockPath, "utf-8"), 10);
+          if (pid && !isProcessRunning(pid)) {
+            unlinkSync(lockPath);
+            continue;
+          }
+        } catch { /* ignore — try again */ }
+        const start = Date.now();
+        while (Date.now() - start < LOCK_RETRY_MS) { /* busy wait */ }
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw new Error(`Failed to acquire schedule lock: ${lockPath}`);
+}
+
+function releaseLock(lockPath: string): void {
+  try { unlinkSync(lockPath); } catch { /* ignore */ }
+}
+
+/** Resolve the storage path for a session-scoped store. */
+export function resolveStorePath(cwd: string, sessionId: string): string {
+  return join(cwd, ".pi", "subagent-schedules", `${sessionId}.json`);
+}
+
+export class ScheduleStore {
+  private filePath: string;
+  private lockPath: string;
+  private jobs = new Map<string, ScheduledSubagent>();
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+    this.lockPath = filePath + ".lock";
+    mkdirSync(dirname(filePath), { recursive: true });
+    this.load();
+  }
+
+  /** Load from disk into the in-memory cache. Silent on parse errors. */
+  private load(): void {
+    if (!existsSync(this.filePath)) return;
+    try {
+      const data: ScheduleStoreData = JSON.parse(readFileSync(this.filePath, "utf-8"));
+      this.jobs.clear();
+      for (const j of data.jobs ?? []) this.jobs.set(j.id, j);
+    } catch { /* corrupt — start fresh, next save rewrites */ }
+  }
+
+  /** Atomic write via temp file + rename (POSIX-atomic). */
+  private save(): void {
+    const data: ScheduleStoreData = { version: 1, jobs: [...this.jobs.values()] };
+    const tmp = this.filePath + ".tmp";
+    writeFileSync(tmp, JSON.stringify(data, null, 2));
+    renameSync(tmp, this.filePath);
+  }
+
+  /** Acquire lock → reload → mutate → save → release. */
+  private withLock<T>(fn: () => T): T {
+    acquireLock(this.lockPath);
+    try {
+      this.load();
+      const result = fn();
+      this.save();
+      return result;
+    } finally {
+      releaseLock(this.lockPath);
+    }
+  }
+
+  /** Read-only — returns a snapshot of the in-memory cache. */
+  list(): ScheduledSubagent[] {
+    return [...this.jobs.values()];
+  }
+
+  /** Read-only check — uses the cache. */
+  hasName(name: string, exceptId?: string): boolean {
+    for (const j of this.jobs.values()) {
+      if (j.id !== exceptId && j.name === name) return true;
+    }
+    return false;
+  }
+
+  get(id: string): ScheduledSubagent | undefined {
+    return this.jobs.get(id);
+  }
+
+  add(job: ScheduledSubagent): void {
+    this.withLock(() => {
+      this.jobs.set(job.id, job);
+    });
+  }
+
+  update(id: string, patch: Partial<ScheduledSubagent>): ScheduledSubagent | undefined {
+    return this.withLock(() => {
+      const existing = this.jobs.get(id);
+      if (!existing) return undefined;
+      const updated = { ...existing, ...patch };
+      this.jobs.set(id, updated);
+      return updated;
+    });
+  }
+
+  remove(id: string): boolean {
+    return this.withLock(() => this.jobs.delete(id));
+  }
+
+  /** Delete the backing file (used when no jobs remain, optional cleanup). */
+  deleteFileIfEmpty(): void {
+    if (this.jobs.size === 0 && existsSync(this.filePath)) {
+      try { unlinkSync(this.filePath); } catch { /* ignore */ }
+    }
+  }
+}