@by-lua/lspec-subagents 1.0.1

package/src/schedule-store.ts

@@ -0,0 +1,153 @@
+/**
+ * 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";
+    this.load();
+  }
+
+  /** Create the backing directory lazily — only when we're about to persist. */
+  private ensureDir(): void {
+    mkdirSync(dirname(this.filePath), { recursive: true });
+  }
+
+  /** 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 {
+    this.ensureDir();
+    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 {
+    // No-op fast path — an unknown id changes nothing, so don't lock or touch
+    // disk (which would otherwise lazily create the backing directory).
+    if (!this.jobs.has(id)) return 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 {
+    // No-op fast path — see update().
+    if (!this.jobs.has(id)) return false;
+    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 */ }
+    }
+  }
+}

package/src/schedule.ts

@@ -0,0 +1,365 @@
+/**
+ * schedule.ts — `SubagentScheduler`: timer-driven dispatcher of scheduled subagents.
+ *
+ * Mirrors the engine shape of pi-cron-schedule/src/scheduler.ts:
+ *   - two-Map split (jobs = croner Cron, intervals = setInterval/setTimeout)
+ *   - addJob/removeJob/updateJob/scheduleJob/unscheduleJob/executeJob
+ *   - static parsers for cron / "+10m" / "5m" / ISO formats
+ *
+ * Differences vs pi-cron-schedule:
+ *   - Persistence is via ScheduleStore (PID-locked, session-scoped, atomic).
+ *   - `executeJob` calls `manager.spawn(..., { bypassQueue: true })` instead
+ *     of dispatching a user message — schedule fires bypass maxConcurrent so
+ *     a 5-minute interval can't be deferred behind 4 long-running agents.
+ *   - Result delivery is implicit: spawn → background completion → existing
+ *     `subagent-notification` followUp path. No new delivery code.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Cron } from "croner";
+import { nanoid } from "nanoid";
+import type { AgentManager } from "./agent-manager.js";
+import { resolveModel } from "./model-resolver.js";
+import type { ScheduleStore } from "./schedule-store.js";
+import type { IsolationMode, ScheduledSubagent, SubagentType, ThinkingLevel } from "./types.js";
+
+/** Event emitted on `pi.events` for cross-extension consumers. */
+export type ScheduleChangeEvent =
+  | { type: "added"; job: ScheduledSubagent }
+  | { type: "removed"; jobId: string }
+  | { type: "updated"; job: ScheduledSubagent }
+  | { type: "fired"; jobId: string; agentId: string; name: string }
+  | { type: "error"; jobId: string; error: string };
+
+/** Params accepted at job creation — ID, timestamps, and state are derived. */
+export interface NewJobInput {
+  name: string;
+  description: string;
+  schedule: string;
+  subagent_type: SubagentType;
+  prompt: string;
+  model?: string;
+  thinking?: ThinkingLevel;
+  max_turns?: number;
+  isolated?: boolean;
+  isolation?: IsolationMode;
+}
+
+export class SubagentScheduler {
+  private jobs = new Map<string, Cron>();
+  private intervals = new Map<string, NodeJS.Timeout>();
+  private store: ScheduleStore | undefined;
+  private pi: ExtensionAPI | undefined;
+  private ctx: ExtensionContext | undefined;
+  private manager: AgentManager | undefined;
+
+  /** Start the scheduler: bind to a session's store and arm enabled jobs. */
+  start(pi: ExtensionAPI, ctx: ExtensionContext, manager: AgentManager, store: ScheduleStore): void {
+    this.pi = pi;
+    this.ctx = ctx;
+    this.manager = manager;
+    this.store = store;
+
+    for (const job of store.list()) {
+      if (job.enabled) this.scheduleJob(job);
+    }
+  }
+
+  /** Stop all timers; drop refs. Safe to call repeatedly. */
+  stop(): void {
+    for (const cron of this.jobs.values()) cron.stop();
+    this.jobs.clear();
+    for (const t of this.intervals.values()) clearTimeout(t);
+    this.intervals.clear();
+    this.store = undefined;
+    this.pi = undefined;
+    this.ctx = undefined;
+    this.manager = undefined;
+  }
+
+  /** True if start() has bound a store and the scheduler is active. */
+  isActive(): boolean {
+    return this.store !== undefined;
+  }
+
+  list(): ScheduledSubagent[] {
+    return this.store?.list() ?? [];
+  }
+
+  /**
+   * Build a `ScheduledSubagent` from user input. Validates the schedule
+   * format and tags `scheduleType`. Throws on invalid input.
+   */
+  buildJob(input: NewJobInput): ScheduledSubagent {
+    const detected = SubagentScheduler.detectSchedule(input.schedule);
+    return {
+      id: nanoid(10),
+      name: input.name,
+      description: input.description,
+      schedule: detected.normalized,
+      scheduleType: detected.type,
+      intervalMs: detected.intervalMs,
+      subagent_type: input.subagent_type,
+      prompt: input.prompt,
+      model: input.model,
+      thinking: input.thinking,
+      max_turns: input.max_turns,
+      isolated: input.isolated,
+      isolation: input.isolation,
+      enabled: true,
+      createdAt: new Date().toISOString(),
+      runCount: 0,
+    };
+  }
+
+  /** Add a job, persist, and arm if enabled. Returns the stored job. */
+  addJob(input: NewJobInput): ScheduledSubagent {
+    const store = this.requireStore();
+    if (store.hasName(input.name)) {
+      throw new Error(`A scheduled job named "${input.name}" already exists.`);
+    }
+    const job = this.buildJob(input);
+    store.add(job);
+    if (job.enabled) this.scheduleJob(job);
+    this.emit({ type: "added", job });
+    return job;
+  }
+
+  removeJob(id: string): boolean {
+    const store = this.requireStore();
+    if (!store.get(id)) return false;
+    this.unscheduleJob(id);
+    const ok = store.remove(id);
+    if (ok) this.emit({ type: "removed", jobId: id });
+    return ok;
+  }
+
+  /** Toggle / mutate a job. Re-arms based on the new `enabled` state. */
+  updateJob(id: string, patch: Partial<ScheduledSubagent>): ScheduledSubagent | undefined {
+    const store = this.requireStore();
+    const updated = store.update(id, patch);
+    if (!updated) return undefined;
+    this.unscheduleJob(id);
+    if (updated.enabled) this.scheduleJob(updated);
+    this.emit({ type: "updated", job: updated });
+    return updated;
+  }
+
+  /** Next-run time as ISO, or undefined if not currently armed. */
+  getNextRun(jobId: string): string | undefined {
+    const cron = this.jobs.get(jobId);
+    if (cron) return cron.nextRun()?.toISOString();
+    const job = this.store?.get(jobId);
+    if (!job?.enabled) return undefined;
+    if (job.scheduleType === "once") return job.schedule;
+    if (job.scheduleType === "interval" && job.intervalMs) {
+      // Before the first fire there's no `lastRun`, so fall back to "now" —
+      // accurate at create time (setInterval was just armed) and within
+      // intervalMs of correct in any pre-first-fire view.
+      const base = job.lastRun ? new Date(job.lastRun).getTime() : Date.now();
+      return new Date(base + job.intervalMs).toISOString();
+    }
+    return undefined;
+  }
+
+  // ── Scheduling primitives ────────────────────────────────────────────
+
+  private scheduleJob(job: ScheduledSubagent): void {
+    const store = this.store;
+    if (!store) return;
+    try {
+      if (job.scheduleType === "interval" && job.intervalMs) {
+        const t = setInterval(() => this.executeJob(job.id), job.intervalMs);
+        this.intervals.set(job.id, t);
+      } else if (job.scheduleType === "once") {
+        const target = new Date(job.schedule).getTime();
+        const delay = target - Date.now();
+        if (delay > 0) {
+          const t = setTimeout(() => {
+            this.executeJob(job.id);
+            // Auto-disable one-shots after they fire (mirrors pi-cron-schedule)
+            store.update(job.id, { enabled: false });
+            const updated = store.get(job.id);
+            if (updated) this.emit({ type: "updated", job: updated });
+          }, delay);
+          this.intervals.set(job.id, t);
+        } else {
+          // Past timestamp — disable, mark error, never fire
+          store.update(job.id, { enabled: false, lastStatus: "error" });
+          this.emit({ type: "error", jobId: job.id, error: `Scheduled time ${job.schedule} is in the past` });
+        }
+      } else {
+        const cron = new Cron(job.schedule, () => this.executeJob(job.id));
+        this.jobs.set(job.id, cron);
+      }
+    } catch (err) {
+      this.emit({ type: "error", jobId: job.id, error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+
+  private unscheduleJob(id: string): void {
+    const cron = this.jobs.get(id);
+    if (cron) {
+      cron.stop();
+      this.jobs.delete(id);
+    }
+    const t = this.intervals.get(id);
+    if (t) {
+      clearTimeout(t);
+      clearInterval(t);
+      this.intervals.delete(id);
+    }
+  }
+
+  /**
+   * Fire a job: persist running state, spawn (bypassing the concurrency
+   * queue), persist completion. Fire-and-forget: the timer tick returns
+   * immediately so other jobs keep firing.
+   */
+  private executeJob(id: string): void {
+    const store = this.store;
+    const pi = this.pi;
+    const ctx = this.ctx;
+    const manager = this.manager;
+    if (!store || !pi || !ctx || !manager) return;
+    const job = store.get(id);
+    if (!job?.enabled) return;
+
+    store.update(id, { lastStatus: "running" });
+
+    // Resolve model at fire time — registry contents may have changed since the
+    // job was created (auth added/removed). Fall back silently to spawn-default
+    // if resolution fails; the spawn path handles undefined model gracefully.
+    let resolvedModel: any | undefined;
+    if (job.model) {
+      const r = resolveModel(job.model, ctx.modelRegistry);
+      if (typeof r !== "string") resolvedModel = r;
+    }
+
+    let agentId: string;
+    try {
+      agentId = manager.spawn(pi, ctx, job.subagent_type, job.prompt, {
+        description: job.description,
+        isBackground: true,
+        bypassQueue: true,
+        model: resolvedModel,
+        maxTurns: job.max_turns,
+        isolated: job.isolated,
+        thinkingLevel: job.thinking,
+        isolation: job.isolation,
+      });
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      store.update(id, { lastRun: new Date().toISOString(), lastStatus: "error" });
+      this.emit({ type: "error", jobId: id, error });
+      return;
+    }
+
+    this.emit({ type: "fired", jobId: id, agentId, name: job.name });
+
+    const record = manager.getRecord(agentId);
+    const finalize = (status: "success" | "error") => {
+      const next = this.getNextRun(id);
+      const current = store.get(id);
+      store.update(id, {
+        lastRun: new Date().toISOString(),
+        lastStatus: status,
+        runCount: (current?.runCount ?? 0) + 1,
+        nextRun: next,
+      });
+    };
+
+    // AgentManager's promise resolves either way (its .catch returns ""), so we
+    // can't infer success/failure from the promise — read record.status instead.
+    // Terminal states: completed/steered = success; error/aborted/stopped = error.
+    if (record?.promise) {
+      record.promise
+        .then(() => {
+          const r = manager.getRecord(agentId);
+          const failed = r?.status === "error" || r?.status === "aborted" || r?.status === "stopped";
+          finalize(failed ? "error" : "success");
+        })
+        .catch(() => finalize("error"));
+    } else {
+      // Spawn returned without a promise (defensive — bypassQueue path always sets one).
+      finalize("success");
+    }
+  }
+
+  private emit(event: ScheduleChangeEvent): void {
+    if (this.pi) this.pi.events.emit("subagents:scheduled", event);
+  }
+
+  private requireStore(): ScheduleStore {
+    if (!this.store) throw new Error("Scheduler not started — no active session.");
+    return this.store;
+  }
+
+  // ── Format detection / parsers (statics — pure) ──────────────────────
+
+  /**
+   * Sniff a schedule string and tag its type. Throws on invalid input.
+   * Order matters: relative ("+10m") and interval ("5m") both match digit+unit;
+   * relative requires the leading "+" to disambiguate.
+   */
+  static detectSchedule(s: string): { type: "cron" | "once" | "interval"; intervalMs?: number; normalized: string } {
+    const trimmed = s.trim();
+    // "+10m" — relative one-shot
+    const rel = SubagentScheduler.parseRelativeTime(trimmed);
+    if (rel !== null) return { type: "once", normalized: rel };
+    // "5m" — interval
+    const ivl = SubagentScheduler.parseInterval(trimmed);
+    if (ivl !== null) return { type: "interval", intervalMs: ivl, normalized: trimmed };
+    // ISO timestamp — one-shot. Reject past timestamps upfront so we never
+    // create a dead-on-arrival record (scheduleJob's safety net still catches
+    // micro-races from `+0s`-style relatives).
+    if (/^\d{4}-\d{2}-\d{2}T/.test(trimmed)) {
+      const d = new Date(trimmed);
+      if (!Number.isNaN(d.getTime())) {
+        if (d.getTime() <= Date.now()) {
+          throw new Error(`Scheduled time ${d.toISOString()} is in the past.`);
+        }
+        return { type: "once", normalized: d.toISOString() };
+      }
+    }
+    // Cron — 6-field
+    const cronCheck = SubagentScheduler.validateCronExpression(trimmed);
+    if (cronCheck.valid) return { type: "cron", normalized: trimmed };
+    throw new Error(
+      `Invalid schedule "${s}". Use 6-field cron (e.g. "0 0 9 * * 1" — 9am every Monday), interval ("5m"/"1h"), or one-shot ("+10m" / ISO).`
+    );
+  }
+
+  /** 6-field cron — 'second minute hour dom month dow'. */
+  static validateCronExpression(expr: string): { valid: boolean; error?: string } {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 6) {
+      return {
+        valid: false,
+        error: `Cron must have 6 fields (second minute hour dom month dow), got ${fields.length}. Example: "0 0 9 * * 1" for 9am every Monday.`,
+      };
+    }
+    try {
+      // Croner validates by construction.
+      new Cron(expr, () => {});
+      return { valid: true };
+    } catch (e) {
+      return { valid: false, error: e instanceof Error ? e.message : "Invalid cron expression" };
+    }
+  }
+
+  /** "+10s"/"+5m"/"+1h"/"+2d" → ISO timestamp. */
+  static parseRelativeTime(s: string): string | null {
+    const m = s.match(/^\+(\d+)(s|m|h|d)$/);
+    if (!m) return null;
+    const ms = parseInt(m[1], 10) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as "s" | "m" | "h" | "d"];
+    return new Date(Date.now() + ms).toISOString();
+  }
+
+  /** "10s"/"5m"/"1h"/"2d" → milliseconds. */
+  static parseInterval(s: string): number | null {
+    const m = s.match(/^(\d+)(s|m|h|d)$/);
+    if (!m) return null;
+    return parseInt(m[1], 10) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as "s" | "m" | "h" | "d"];
+  }
+}

package/src/settings.ts

@@ -0,0 +1,186 @@
+// 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 "@mariozechner/pi-coding-agent";
+import type { JoinMode } 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;
+}
+
+/** 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;
+}
+
+/** 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"]);
+
+// 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;
+  }
+  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);
+}
+
+/**
+ * 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);
+}