@cad0p/pi-subagents-tintinweb 0.14.2 → 0.22.0

package/src/prompts.ts

@@ -110,6 +110,77 @@ ${envBlock}`;
   return activeAgentTag + replaceHeader + worktreeSection + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 
+/** One-line tool snippets keyed by tool name, as pi's `<tools>` section prints them. */
+export type ToolSnippets = Record<string, string>;
+
+/** The line pi puts after the tool list in a `<tools>` section. */
+const TOOLS_TRAILER =
+  "In addition to the tools above, you may have access to other custom tools depending on the project.";
+
+/**
+ * Replace the `<tools>` block of an inherited prompt with one describing the tools
+ * THIS agent declares.
+ *
+ * An append-mode agent inherits the parent's prompt verbatim, `<tools>` block
+ * included — so a child that lacks `codemode`, `tool_search`, or an extension tool the
+ * parent has is told it has them and then calls a tool that does not exist. pi cannot
+ * rebuild the block for us: the child's prompt arrives as `systemPromptOverride`, i.e.
+ * as a custom prompt, and pi only generates `<tools>` for its own default prompt.
+ *
+ * Snippets come from `snippets` (pi's built-in tool definitions and the child's own
+ * extension tools) and, as a fallback, from the inherited block, which is the only
+ * place a tool this fork knows nothing about is described. `snippets` wins on a name
+ * both have. A tool without a snippet is left out, as pi does, and an agent declaring
+ * no tools at all loses the block entirely rather than advertising an empty list.
+ *
+ * A prompt with no block at all gets one prepended: a parent running a custom system
+ * prompt has none, and the child's prompt is a custom prompt to pi, so pi will not add
+ * one either — an agent that declares tools and advertises none is the same lie in the
+ * other direction.
+ */
+export function retargetToolsSection(
+  prompt: string,
+  toolNames: readonly string[],
+  snippets: ToolSnippets = {},
+): string {
+  // Tolerate CRLF: pi writes `\n`, but an inherited custom prompt may not, and a
+  // failed match would leave the child with no block at all.
+  const match = /<tools>\r?\n([\s\S]*?)\r?\n<\/tools>(?:\r?\n){0,2}/.exec(prompt);
+
+  const inherited = new Map<string, string>();
+  if (match) {
+    for (const line of match[1].split(/\r?\n/)) {
+      const entry = /^- ([^:]+): (.+?)\r?$/.exec(line);
+      if (entry) inherited.set(entry[1], entry[2]);
+    }
+  }
+
+  const lines: string[] = [];
+  for (const name of toolNames) {
+    const snippet = snippets[name] ?? inherited.get(name);
+    if (snippet) lines.push(`- ${name}: ${snippet}`);
+  }
+
+  const block = lines.length > 0 ? `<tools>\n${lines.join("\n")}\n\n${TOOLS_TRAILER}\n</tools>` : "";
+
+  if (!match) {
+    // A prompt that already mentions `<tools` in a shape this parser does not
+    // recognise — same-line content, an attribute, a fenced XML example — must
+    // not gain a second, contradictory block. Leaving it alone under-advertises;
+    // duplicating it advertises two different lists.
+    if (prompt.includes("<tools")) return prompt;
+    // Append rather than prepend. Append mode exists so the parent prompt stays a
+    // byte-identical prefix of the child's (KV-cache reuse, see buildAgentPrompt),
+    // and a leading block would break that for exactly the parents that have no
+    // block to replace. It also keeps `<active_agent>` first in replace mode.
+    return block ? `${prompt}\n\n${block}` : prompt;
+  }
+
+  // The match consumed the separator that followed `</tools>`; put one back when
+  // a block is written, and none when the block is stripped.
+  return prompt.slice(0, match.index) + (block ? `${block}\n\n` : "") + prompt.slice(match.index + match[0].length);
+}
+
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */
 const genericBase = `# Role
 You are a general-purpose coding agent for complex, multi-step tasks.

package/src/result-report.ts

@@ -0,0 +1,170 @@
+/**
+ * result-report.ts — the `get_subagent_result` report, shared by the top-level
+ * tool and the nested delegation tools.
+ *
+ * Both surfaces must describe a run the same way: the turn/max-turns header, the
+ * latest checkpoint, the artifact paths, and the honest status note on partial
+ * output. A nested parent reads the same shape as the main session, so the
+ * report lives here rather than inside the extension entry point (which the
+ * nested tools cannot import).
+ */
+
+import { existsSync } from "node:fs";
+import { checkpointsFilePath } from "./checkpoint.js";
+import { DEFAULT_SHOW_COST } from "./settings.js";
+import { getStatusNote, partialOutputSuffix } from "./status-note.js";
+import { toSingleLine } from "./text-safety.js";
+import type { AgentRecord } from "./types.js";
+import { formatCost, formatDuration, formatTokens, getDisplayName } from "./ui/agent-widget.js";
+import { getLifetimeCost, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage } from "./usage.js";
+
+/**
+ * Whether the report shows an estimated cost beside the token count — the
+ * user's `showCost` setting, mirrored here by `index.ts`'s applier.
+ *
+ * Module state rather than a parameter because BOTH report callers must agree:
+ * the top-level `get_subagent_result` and its nested twin (nested-tools.ts),
+ * which a child session builds without access to the parent's settings. One
+ * source beats threading the same flag through two independent tool factories.
+ */
+let showCost = DEFAULT_SHOW_COST;
+
+/** Mirror the live `showCost` setting into the report renderer. */
+export function setReportShowCost(b: boolean): void { showCost = b; }
+
+/** Format an agent's lifetime token total, or "" when zero. */
+export function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): string {
+  const t = getLifetimeTotal(o.lifetimeUsage);
+  return t > 0 ? formatTokens(t) : "";
+}
+
+/** A record's artifact paths, each gated on the file actually existing.
+ *  `checkpointsFileOk` is latching-true, so existsSync covers out-of-band deletion. */
+function reportPaths(record: AgentRecord): { checkpointsPath?: string; transcriptPath?: string } {
+  const candidate = checkpointsFilePath(record.outputFile);
+  return {
+    checkpointsPath: record.checkpointsFileOk && candidate && existsSync(candidate) ? candidate : undefined,
+    transcriptPath: record.outputFile && existsSync(record.outputFile) ? record.outputFile : undefined,
+  };
+}
+
+/** The full report for a record — running, queued, or terminal. */
+export function renderAgentReport(record: AgentRecord): string {
+  const { checkpointsPath, transcriptPath } = reportPaths(record);
+  if (record.status === "running") return renderRunning(record, checkpointsPath, transcriptPath);
+  if (record.status === "queued") return renderQueued(record);
+  return renderTerminal(record, checkpointsPath, transcriptPath, record.status === "error");
+}
+
+/** Queued subagent: no file paths, result body, or footer — nothing produced yet. */
+export function renderQueued(record: AgentRecord): string {
+  const displayName = toSingleLine(getDisplayName(record.type));
+  return (
+    `Agent: ${toSingleLine(record.id)} (queued — not started yet)\n` +
+    `Type: ${displayName} | Description: ${toSingleLine(record.description)}\n\n` +
+    `This agent is waiting to start. It will begin running when a concurrent-agent slot frees up.`
+  );
+}
+
+/** Running subagent: header (turn/elapsed), latest checkpoint, file paths, polling-discouragement footer. */
+function renderRunning(
+  record: AgentRecord,
+  checkpointsPath: string | undefined,
+  transcriptPath: string | undefined,
+): string {
+  const displayName = toSingleLine(getDisplayName(record.type));
+  const turn = record.turnCount ?? 0;
+  const maxTurns = record.effectiveMaxTurns;
+  const elapsedSeconds = Math.round((Date.now() - record.startedAt) / 1000);
+  const turnLabel = maxTurns != null ? `turn ${turn}/${maxTurns}` : `turn ${turn}`;
+
+  let output =
+    `Agent: ${toSingleLine(record.id)} (still running — ${turnLabel}, ${elapsedSeconds}s elapsed)\n` +
+    `Type: ${displayName} | Description: ${toSingleLine(record.description)}\n\n`;
+
+  if (record.lastCheckpoint) {
+    output +=
+      `Latest checkpoint (turn ${record.lastCheckpoint.turn}):\n` +
+      `  ${record.lastCheckpoint.summary}\n\n`;
+    output += fileSection(checkpointsPath, transcriptPath, footerForPaths(checkpointsPath, transcriptPath, true));
+  } else {
+    output += `No checkpoint yet — the subagent hasn't called the checkpoint tool.\n\n`;
+    output += fileSection(checkpointsPath, transcriptPath,
+      "  grep or read the transcript for detail on what it's doing. Do not poll repeatedly.");
+  }
+  return output;
+}
+
+/** Completed/errored subagent: completed header, result or error block, latest checkpoint, file paths. */
+function renderTerminal(
+  record: AgentRecord,
+  checkpointsPath: string | undefined,
+  transcriptPath: string | undefined,
+  errored: boolean,
+): string {
+  const header = completedHeader(record);
+  const body = errored
+    ? `Error: ${record.error}${partialOutputSuffix(record)}`
+    : record.result?.trim() || "No output.";
+
+  let output = `${header}\n\n${body}`;
+  if (record.lastCheckpoint) {
+    output +=
+      `\n\nLatest checkpoint (turn ${record.lastCheckpoint.turn}):\n` +
+      `  ${record.lastCheckpoint.summary}`;
+  }
+  output += "\n\n" + fileSection(checkpointsPath, transcriptPath, footerForPaths(checkpointsPath, transcriptPath, false));
+  return output;
+}
+
+/** Shared header for completed/errored shapes (Status + stats + status note). */
+function completedHeader(record: AgentRecord): string {
+  const displayName = toSingleLine(getDisplayName(record.type));
+  const duration = formatDuration(record.startedAt, record.completedAt);
+  const tokens = formatLifetimeTokens(record);
+  const contextPercent = getSessionContextPercent(record.session);
+  const statsParts = [`Tool uses: ${record.toolUses}`];
+  if (tokens) statsParts.push(tokens);
+  // Labelled field, like its pipe-separated neighbours. Omitted entirely when
+  // there is no cost to show: an unpriced model would otherwise read `Cost:
+  // $0.00`, which claims the run was measured and free rather than never priced.
+  const cost = showCost ? formatCost(getLifetimeCost(record.lifetimeUsage)) : "";
+  if (cost) statsParts.push(`Cost: ${cost}`);
+  if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
+  if (record.compactionCount) statsParts.push(`Compactions: ${record.compactionCount}`);
+  statsParts.push(`Duration: ${duration}`);
+  return (
+    `Agent: ${toSingleLine(record.id)}\n` +
+    `Type: ${displayName} | Status: ${toSingleLine(record.status)}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
+    `Description: ${toSingleLine(record.description)}`
+  );
+}
+
+/** The checkpoint-history / full-transcript path block, aligned to a shared column, plus the footer. */
+function fileSection(
+  checkpointsPath: string | undefined,
+  transcriptPath: string | undefined,
+  footer: string,
+): string {
+  let s = "";
+  if (checkpointsPath) s += `Checkpoint history: ${toSingleLine(checkpointsPath)}\n`;
+  if (transcriptPath) s += `Full transcript:   ${toSingleLine(transcriptPath)}\n`;
+  s += footer;
+  return s;
+}
+
+/** Footer matching the paths actually rendered (existsSync can suppress either independently). */
+function footerForPaths(
+  checkpointsPath: string | undefined,
+  transcriptPath: string | undefined,
+  running: boolean,
+): string {
+  const suffix = running ? " Do not poll repeatedly." : "";
+  if (checkpointsPath && transcriptPath) {
+    return `  grep or read the checkpoints / transcript for more detail.${suffix}`;
+  }
+  if (checkpointsPath) {
+    return `  grep or read the checkpoints file for more detail.${suffix}`;
+  }
+  return `  grep or read the transcript for more detail.${suffix}`;
+}

package/src/schedule-store.ts

@@ -12,11 +12,117 @@
 
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { ScheduledSubagent, ScheduleStoreData } from "./types.js";
+import { isValidType } from "./agent-types.js";
+import { SubagentScheduler } from "./schedule.js";
+import type { IsolationMode, ScheduledSubagent, ScheduleStoreData, SubagentType, ThinkingLevel } from "./types.js";
 
 const LOCK_RETRY_MS = 50;
 const LOCK_MAX_RETRIES = 100;
 
+const SCHEDULE_TYPES: readonly string[] = ["cron", "once", "interval"];
+const LAST_STATUSES: readonly string[] = ["success", "error", "running"];
+const ISOLATION_MODES: readonly string[] = ["worktree"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Coerce one parsed store entry into a `ScheduledSubagent`, dropping optional
+ * fields whose type is wrong. Returns undefined when the record cannot run or
+ * be managed — no usable id, or a wrong-typed load-bearing field — so load()
+ * can preserve it on disk without exposing it to the scheduler.
+ */
+function sanitizeJob(raw: unknown): ScheduledSubagent | undefined {
+  if (!isRecord(raw)) return undefined;
+  const { id, name, description, schedule, scheduleType, subagent_type, prompt } = raw;
+  if (typeof id !== "string" || id.length === 0) return undefined;
+  if (
+    typeof name !== "string" ||
+    typeof description !== "string" ||
+    typeof schedule !== "string" ||
+    typeof subagent_type !== "string" ||
+    typeof prompt !== "string" ||
+    typeof scheduleType !== "string" ||
+    !SCHEDULE_TYPES.includes(scheduleType)
+  ) {
+    return undefined;
+  }
+  // Records that cannot run as declared must not appear active: a bad cron
+  // would arm nothing while the menu shows it as healthy, and an unregistered
+  // type silently falls back to a write-capable config at spawn time.
+  if (scheduleType === "cron" && !SubagentScheduler.validateCronExpression(schedule).valid) return undefined;
+  if (!isValidType(subagent_type)) return undefined;
+  return {
+    id,
+    name,
+    description,
+    schedule,
+    scheduleType: scheduleType as ScheduledSubagent["scheduleType"],
+    intervalMs: typeof raw.intervalMs === "number" && Number.isFinite(raw.intervalMs) ? raw.intervalMs : undefined,
+    subagent_type: subagent_type as SubagentType,
+    prompt,
+    model: typeof raw.model === "string" ? raw.model : undefined,
+    thinking: typeof raw.thinking === "string" ? (raw.thinking as ThinkingLevel) : undefined,
+    max_turns: typeof raw.max_turns === "number" && Number.isFinite(raw.max_turns) ? raw.max_turns : undefined,
+    isolated: typeof raw.isolated === "boolean" ? raw.isolated : undefined,
+    isolation: typeof raw.isolation === "string" && ISOLATION_MODES.includes(raw.isolation) ? (raw.isolation as IsolationMode) : undefined,
+    // A non-boolean flag cannot be trusted to mean "arm me": load disabled and
+    // keep the record visible so the user can fix or cancel it.
+    enabled: raw.enabled === true,
+    createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "",
+    lastRun: typeof raw.lastRun === "string" ? raw.lastRun : undefined,
+    lastStatus: typeof raw.lastStatus === "string" && LAST_STATUSES.includes(raw.lastStatus) ? (raw.lastStatus as ScheduledSubagent["lastStatus"]) : undefined,
+    nextRun: typeof raw.nextRun === "string" ? raw.nextRun : undefined,
+    runCount: typeof raw.runCount === "number" && Number.isFinite(raw.runCount) ? raw.runCount : 0,
+  };
+}
+
+/** Stable per-entry summary for the warn-once signature. */
+function skipSignature(raw: unknown): string {
+  if (isRecord(raw) && typeof raw.id === "string") return raw.id || "(empty-id)";
+  return typeof raw === "object" && raw !== null ? "object" : typeof raw;
+}
+
+/**
+ * Deepest JSON nesting a preserved record may have. A real scheduled job is a
+ * flat object; anything past a handful of levels is hand-written or corrupt.
+ * The bound is deliberately far below the smallest JSON.stringify stack
+ * ceiling observed on the supported engines (~6k nesting frames on the Node
+ * 22/24 main thread; worker threads are much higher), so an accepted record
+ * can always be re-serialized and the drop decision does not depend on the
+ * ambient stack depth.
+ */
+export const MAX_PRESERVED_DEPTH = 64;
+
+/**
+ * True when `value` nests no deeper than `budget` JSON levels. Recursion is
+ * bounded by `budget`, so an arbitrarily deep value cannot overflow this
+ * check itself (JSON.parse accepts far more nesting than stringify).
+ */
+function isWithinDepth(value: unknown, budget: number): boolean {
+  if (!Array.isArray(value) && !isRecord(value)) return true;
+  if (budget <= 0) return false;
+  const children = Array.isArray(value) ? value : Object.values(value);
+  for (const child of children) {
+    if (!isWithinDepth(child, budget - 1)) return false;
+  }
+  return true;
+}
+
+/**
+ * Queue a record for verbatim re-write on save, but only when it nests no
+ * deeper than MAX_PRESERVED_DEPTH. Preserved records come straight from
+ * JSON.parse output, so the depth bound is the whole serializability
+ * guarantee: parsed values cannot carry cycles, BigInt, getters, or a
+ * `toJSON`. Returns false when the record was dropped.
+ */
+function preserveRecord(raw: unknown, into: unknown[]): boolean {
+  if (!isWithinDepth(raw, MAX_PRESERVED_DEPTH)) return false;
+  into.push(raw);
+  return true;
+}
+
 function isProcessRunning(pid: number): boolean {
   try { process.kill(pid, 0); return true; } catch { return false; }
 }
@@ -58,6 +164,47 @@ export class ScheduleStore {
   private filePath: string;
   private lockPath: string;
   private jobs = new Map<string, ScheduledSubagent>();
+  /** Raw entries load() could not sanitize; written back on save so no user data is erased. */
+  private skipped: unknown[] = [];
+  /**
+   * Raw records shadowed by an earlier duplicate id; written back verbatim in
+   * their own list so a freed id can never re-promote them to live jobs.
+   */
+  private shadowed: unknown[] = [];
+  /** Records dropped at load instead of preserved verbatim — too deeply nested. */
+  private droppedCount = 0;
+  private jobsContainerInvalid = false;
+  private fileShapeInvalid = false;
+  /** Signature of the last skip set we warned about, so repeated locked loads stay quiet. */
+  private warnedSkips: string | undefined;
+  /** Ids the last locked load promoted into the live set; drained once the lock is gone. */
+  private pendingPromoted: string[] = [];
+  /**
+   * Called by load() while the store lock is held, with the ids that were live
+   * in the previous cache but are no longer live after an existing-file reload:
+   * the record no longer sanitizes into a live job (for example an
+   * unregistered agent type, an unparseable cron, a wrong-typed load-bearing
+   * field, or an invalid `scheduleType`), the `jobs` container is not an array
+   * (every live id is reclassified at once), or the record is no longer the
+   * file's live entry (deleted by another writer, or dropped for exceeding the
+   * depth bound). The scheduler binds this to clear timers that would
+   * otherwise keep ticking a record the live set no longer contains, so the
+   * callback must not write to the store (the lock is not re-entrant). Never
+   * called when load() keeps the previous state: a missing file (the kept
+   * in-memory state is re-written by the next save, so a mid-session deletion
+   * only sticks if the session ends before that write) or corrupt JSON.
+   */
+  onReclassified: ((ids: string[]) => void) | undefined;
+  /**
+   * Called from withLock() after the mutation lock is released, with the ids
+   * that were not live in the previous cache but are live after the reload —
+   * records promoted out of `skipped` once their agent type is registered
+   * again, or records another writer added to the file. The scheduler binds
+   * this to arm enabled records that hold no timer. Never called when load()
+   * keeps the previous state (missing or corrupt file), and never while the
+   * lock is held, so the callback may safely mutate the store.
+   */
+  onPromoted: ((ids: string[]) => void) | undefined;
 
   constructor(filePath: string) {
     this.filePath = filePath;
@@ -70,22 +217,123 @@ export class ScheduleStore {
     mkdirSync(dirname(this.filePath), { recursive: true });
   }
 
-  /** Load from disk into the in-memory cache. Silent on parse errors. */
+  /**
+   * Load from disk into the in-memory cache. A stray record must not abort the
+   * scan (later valid entries would vanish and the next save erase them), so
+   * entries that fail validation are skipped and kept in `this.skipped` for
+   * the next save to write back. A record that duplicates a live id is kept
+   * verbatim in `this.shadowed` and is never promoted. Corrupt JSON keeps the
+   * current in-memory state rather than clearing it.
+   */
   private load(): void {
+    // A reload that keeps the previous state must not preserve an earlier
+    // promotion report: withLock drains pendingPromoted even when one of the
+    // kept-state early returns below fires, and records that were live before
+    // and after the reload are not promotions.
+    this.pendingPromoted = [];
     if (!existsSync(this.filePath)) return;
+    let parsed: unknown;
     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 */ }
+      parsed = JSON.parse(readFileSync(this.filePath, "utf-8"));
+    } catch {
+      return; // corrupt JSON — keep the current in-memory state
+    }
+    const previousLiveIds = [...this.jobs.keys()];
+    const data = isRecord(parsed) ? parsed : {};
+    const rawJobs = data.jobs;
+    const entries = Array.isArray(rawJobs) ? rawJobs : [];
+    const rawShadowed = data.shadowed;
+    const jobs = new Map<string, ScheduledSubagent>();
+    const skipped: unknown[] = [];
+    const shadowed: unknown[] = [];
+    let dropped = 0;
+    for (const raw of entries) {
+      const job = sanitizeJob(raw);
+      if (!job) {
+        if (!preserveRecord(raw, skipped)) dropped++;
+        continue;
+      }
+      if (jobs.has(job.id)) {
+        // First record wins. The shadowed duplicate goes to its own list, so a
+        // later load can never promote it back to live even if the id is freed.
+        if (!preserveRecord(raw, shadowed)) dropped++;
+        continue;
+      }
+      jobs.set(job.id, job);
+    }
+    // Shadowed records are never candidates for the live set — that is the
+    // point of the separate list.
+    for (const raw of Array.isArray(rawShadowed) ? rawShadowed : []) {
+      if (!preserveRecord(raw, shadowed)) dropped++;
+    }
+    this.jobs = jobs;
+    this.skipped = skipped;
+    this.shadowed = shadowed;
+    this.droppedCount = dropped;
+    this.jobsContainerInvalid = rawJobs !== undefined && !Array.isArray(rawJobs);
+    this.fileShapeInvalid = !isRecord(parsed);
+    this.warnAboutSkips();
+    // A record that left the live set must not keep a timer armed: the timer
+    // would keep firing a record the store no longer considers live, and a
+    // later load (e.g. after the agent type returns) would re-promote it.
+    const reclassified = previousLiveIds.filter(id => !jobs.has(id));
+    if (reclassified.length > 0) this.onReclassified?.(reclassified);
+    // Promotion is reported after the lock (see withLock): arming a promoted
+    // record can write to the store on the arm-guard branches, which cannot
+    // run while withLock holds the non-re-entrant lock.
+    const previousLive = new Set(previousLiveIds);
+    this.pendingPromoted = [...jobs.keys()].filter(id => !previousLive.has(id));
+  }
+
+  /** Warn once per distinct invalid-entry summary — load() runs before every mutation. */
+  private warnAboutSkips(): void {
+    const signature = [
+      this.skipped.map(skipSignature).join(","),
+      this.shadowed.map(skipSignature).join(","),
+      `dropped:${this.droppedCount}`,
+      `container:${this.jobsContainerInvalid}`,
+      `file:${this.fileShapeInvalid}`,
+    ].join("|");
+    if (signature === this.warnedSkips) return;
+    this.warnedSkips = signature;
+    const details: string[] = [];
+    if (this.skipped.length > 0) details.push(`${this.skipped.length} invalid scheduled-job record(s) kept on disk`);
+    if (this.shadowed.length > 0) details.push(`${this.shadowed.length} shadowed duplicate record(s) retained verbatim on disk and discarded when their id is deleted`);
+    if (this.droppedCount > 0) details.push(`${this.droppedCount} scheduled-job record(s) dropped (too deeply nested)`);
+    if (this.jobsContainerInvalid) details.push("the jobs container is not an array and will be rewritten");
+    if (this.fileShapeInvalid) details.push("the file is not a versioned store object and will be rewritten");
+    if (details.length === 0) return;
+    console.warn(`[pi-subagents] ${this.filePath}: ${details.join("; ")}. Repair or remove invalid entries there.`);
   }
 
   /** Atomic write via temp file + rename (POSIX-atomic). */
   private save(): void {
-    const data: ScheduleStoreData = { version: 1, jobs: [...this.jobs.values()] };
+    // Preserved entries are written back verbatim so an unrelated mutation
+    // cannot silently erase a record the user can still repair by hand.
+    // Shadowed duplicates live under their own key: never promoted, never armed.
+    const data: ScheduleStoreData = {
+      version: 1,
+      jobs: [...this.jobs.values(), ...(this.skipped as ScheduledSubagent[])],
+      shadowed: this.shadowed as ScheduledSubagent[],
+    };
+    let json: string;
+    try {
+      json = JSON.stringify(data, null, 2);
+    } catch (err) {
+      // Fail before touching the file: the previous contents stay intact and a
+      // clear error reaches the caller instead of a bare RangeError.
+      throw new Error(
+        `Failed to serialize schedule store ${this.filePath}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
     const tmp = this.filePath + ".tmp";
-    writeFileSync(tmp, JSON.stringify(data, null, 2));
-    renameSync(tmp, this.filePath);
+    try {
+      writeFileSync(tmp, json);
+      renameSync(tmp, this.filePath);
+    } catch (err) {
+      try { unlinkSync(tmp); } catch { /* ignore */ }
+      throw err;
+    }
   }
 
   /** Acquire lock → reload → mutate → save → release. */
@@ -99,6 +347,27 @@ export class ScheduleStore {
       return result;
     } finally {
       releaseLock(this.lockPath);
+      this.drainPromoted();
+    }
+  }
+
+  /**
+   * Report ids the last load promoted, now that the lock is gone. The mutation
+   * has either committed or already failed by the time this runs: it is called
+   * from withLock's `finally` after the lock is released, so a callback throw
+   * must not replace the mutation's own outcome. A callback failure aborts
+   * that report — the warning names the affected ids, and they are not
+   * re-reported; a later start() re-arms the live enabled records.
+   */
+  private drainPromoted(): void {
+    const ids = this.pendingPromoted;
+    if (ids.length === 0) return;
+    this.pendingPromoted = [];
+    try {
+      this.onPromoted?.(ids);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`[pi-subagents] ${this.filePath}: onPromoted callback failed for [${ids.join(", ")}]: ${message}`);
     }
   }
 
@@ -139,14 +408,32 @@ export class ScheduleStore {
   }
 
   remove(id: string): boolean {
-    // No-op fast path — see update().
-    if (!this.jobs.has(id)) return false;
-    return this.withLock(() => this.jobs.delete(id));
+    // No-op fast path — see update(). A record can be live, or already
+    // reclassified into a preserved list by an earlier load, so check all
+    // three before deciding there is nothing to remove.
+    const sameId = (raw: unknown) => isRecord(raw) && raw.id === id;
+    const known = this.jobs.has(id) || this.skipped.some(sameId) || this.shadowed.some(sameId);
+    if (!known) return false;
+    return this.withLock(() => {
+      // The user deleted this id, so purge every top-level record whose id
+      // matches from every list: a record that load() reclassified
+      // mid-mutation (e.g. its agent type was invalidated) must not survive in
+      // `skipped` and get re-promoted once the type is back, and a shadowed
+      // duplicate must go with its live twin. A same-id record nested inside a
+      // preserved container is left verbatim — it is inert, because every load
+      // rejects the wrapper and sends it back to `skipped`.
+      const removedLive = this.jobs.delete(id);
+      const skippedBefore = this.skipped.length;
+      const shadowedBefore = this.shadowed.length;
+      this.skipped = this.skipped.filter(raw => !sameId(raw));
+      this.shadowed = this.shadowed.filter(raw => !sameId(raw));
+      return removedLive || this.skipped.length !== skippedBefore || this.shadowed.length !== shadowedBefore;
+    });
   }
 
   /** Delete the backing file (used when no jobs remain, optional cleanup). */
   deleteFileIfEmpty(): void {
-    if (this.jobs.size === 0 && existsSync(this.filePath)) {
+    if (this.jobs.size === 0 && this.skipped.length === 0 && this.shadowed.length === 0 && existsSync(this.filePath)) {
       try { unlinkSync(this.filePath); } catch { /* ignore */ }
     }
   }