minimal-agent 0.10.0 → 0.12.0

package/plugins/cron-runner/src/commands.ts

@@ -0,0 +1,373 @@
+import { getWorkingDir } from '../../../src/plugin-sdk.js';
+import { formatDateTime } from './cronTime.js';
+import {
+  createTask,
+  deleteTask,
+  getTask,
+  listMissed,
+  listTasks,
+  recentRuns,
+  updateTask,
+  upsertTask,
+} from './store.js';
+import type { CronTask } from './types.js';
+import type { Scheduler } from './scheduler.js';
+import { validateCron, validateIsoDate } from './schema.js';
+
+export async function handleCronCommand(
+  commandName: string,
+  args: string,
+  scheduler: Scheduler | null,
+): Promise<string> {
+  if (commandName === 'crons') return await formatTaskList(await listTasks());
+
+  const argv = tokenize(args);
+  const action = argv.shift() ?? 'list';
+  if (action === 'list') return await formatTaskList(await listTasks());
+  if (action === 'create') return await createFromArgs(argv);
+  if (action === 'pause' || action === 'resume') return await setStatus(argv[0], action === 'resume' ? 'active' : 'paused');
+  if (action === 'delete' || action === 'remove') return await remove(argv[0]);
+  if (action === 'show') return await show(argv[0]);
+  if (action === 'run') return await runNow(argv[0], scheduler);
+  if (action === 'missed') return await formatMissed();
+  if (action === 'help') return helpText();
+  const shortcut = await createFromShortcut(action, argv);
+  if (shortcut) return shortcut;
+  if (/^\d+\S*$/.test(action)) {
+    return `无效间隔：${action}。支持 1m、2h、1d、1w（最小 1 分钟）。`;
+  }
+  return `未知 /cron 子命令：${action}\n\n${helpText()}`;
+}
+
+async function createFromArgs(argv: string[]): Promise<string> {
+  const opts = parseOptions(argv);
+  const cron = opts.cron;
+  const name = opts.name;
+  const prompt = opts.prompt;
+  const workflow = opts.workflow;
+  if (!cron || !name || (!prompt && !workflow)) {
+    return helpText();
+  }
+  const cronValidation = validateCron(cron);
+  if (!cronValidation.ok) {
+    return `无效 cron 表达式：${cron}\n${cronValidation.error}`;
+  }
+  const maxTurns = opts.maxTurns ? Number.parseInt(opts.maxTurns, 10) : undefined;
+  if (opts.maxTurns && (!Number.isFinite(maxTurns) || maxTurns! <= 0)) {
+    return `无效 maxTurns：${opts.maxTurns}`;
+  }
+  const maxRuns = opts.maxRuns ? Number.parseInt(opts.maxRuns, 10) : undefined;
+  if (opts.maxRuns && (!Number.isFinite(maxRuns) || maxRuns! <= 0)) {
+    return `无效 max-runs：${opts.maxRuns}（须是正整数，跑满这么多次后自动暂停）`;
+  }
+  if (opts.expiresAt) {
+    const expiresAtValidation = validateIsoDate(opts.expiresAt, 'expires-at');
+    if (!expiresAtValidation.ok) return expiresAtValidation.error;
+  }
+  const task = createTask({
+    name,
+    ...(opts.description ? { description: opts.description } : {}),
+    cron,
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || 'local',
+    cwd: getWorkingDir(),
+    ...(opts.model ? { model: opts.model } : {}),
+    ...(maxTurns ? { maxTurns } : {}),
+    kind: opts.once === 'true' ? 'once' : 'recurring',
+    ...(opts.permanent === 'true' ? { permanent: true } : {}),
+    ...(opts.expiresAt ? { expiresAt: opts.expiresAt } : {}),
+    ...(maxRuns ? { maxRuns } : {}),
+    sessionMode: opts.freshSession === 'true' ? 'fresh' : 'persistent',
+    action: workflow
+      ? { type: 'workflow', command: workflow }
+      : { type: 'prompt', prompt: prompt! },
+  });
+  await upsertTask(task);
+  return `已创建 cron：${task.id}\n${await formatTask(task)}`;
+}
+
+async function createFromShortcut(
+  head: string,
+  rest: string[],
+): Promise<string | null> {
+  const parsed = parseShortcutSchedule(head, rest);
+  if (!parsed) return null;
+  if ('error' in parsed) return parsed.error;
+  const task = createTask({
+    name: parsed.name,
+    ...(parsed.description ? { description: parsed.description } : {}),
+    ...(parsed.cron ? { cron: parsed.cron } : {}),
+    ...(parsed.intervalMs ? { intervalMs: parsed.intervalMs, anchorAt: new Date().toISOString() } : {}),
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || 'local',
+    cwd: getWorkingDir(),
+    action: parsed.action,
+  });
+  await upsertTask(task);
+  return `已创建 cron：${task.id}\n${await formatTask(task)}`;
+}
+
+export function parseShortcutSchedule(
+  head: string,
+  rest: string[],
+):
+  | ({
+      cron?: string;
+      intervalMs?: number;
+    } & {
+      action: CronTask['action'];
+      description?: string;
+      name: string;
+    })
+  | { error: string }
+  | null {
+  const intervalMs = parseIntervalShortcut(head);
+  let actionTokens = rest;
+  let cron: string | undefined;
+
+  if (!intervalMs) {
+    const time = rest[0];
+    if (!time) return null;
+    const parsedTime = parseClockTime(time);
+    if (!parsedTime) return null;
+    actionTokens = rest.slice(1);
+    const { hour, minute } = parsedTime;
+    const cronTime = `${minute} ${hour}`;
+    if (head === '每天' || head === '每日') cron = `${cronTime} * * *`;
+    else if (head === '工作日') cron = `${cronTime} * * 1-5`;
+    else {
+      const weekly = head.match(/^每周([一二三四五六日天])$/);
+      if (!weekly) return null;
+      cron = `${cronTime} * * ${weekdayNumber(weekly[1]!)}`;
+    }
+  }
+
+  const parsedAction = parseShortcutAction(actionTokens);
+  if ('error' in parsedAction) return parsedAction;
+  return {
+    ...(cron ? { cron } : {}),
+    ...(intervalMs ? { intervalMs } : {}),
+    ...parsedAction,
+  };
+}
+
+export function parseIntervalShortcut(text: string): number | null {
+  const match = text.match(/^(\d+)(m|min|分钟|h|小时|d|天|w|周)$/i);
+  if (!match) return null;
+  const value = Number.parseInt(match[1]!, 10);
+  if (!Number.isFinite(value) || value <= 0) return null;
+  const unit = match[2]!.toLowerCase();
+  const multiplier =
+    unit === 'w' || unit === '周'
+      ? 7 * 24 * 60 * 60_000
+      : unit === 'd' || unit === '天'
+        ? 24 * 60 * 60_000
+        : unit === 'h' || unit === '小时'
+          ? 60 * 60_000
+          : 60_000;
+  const intervalMs = value * multiplier;
+  return Number.isSafeInteger(intervalMs) && intervalMs >= 60_000 ? intervalMs : null;
+}
+
+function parseShortcutAction(tokens: string[]):
+  | { action: CronTask['action']; description?: string; name: string }
+  | { error: string } {
+  if (tokens.length === 0) {
+    return { error: '请在时间后面写提示词或 workflow。\n例如：/cron 1d /workflow daily-news.yaml 生成中文新闻稿' };
+  }
+  const markerIndex = tokens.findIndex((token) => token === '/workflow' || token === 'workflow');
+  if (markerIndex < 0) {
+    const prompt = tokens.join(' ').trim();
+    return { action: { type: 'prompt', prompt }, name: deriveName(prompt) };
+  }
+  const workflowName = tokens[markerIndex + 1];
+  if (!workflowName) return { error: 'workflow 标记后缺少 YAML 名称。' };
+  const description = tokens.slice(0, markerIndex).join(' ').trim();
+  const command = serializeTokens(tokens.slice(markerIndex + 1));
+  return {
+    action: { type: 'workflow', command },
+    ...(description ? { description } : {}),
+    name: description || deriveName(workflowName.replace(/\.ya?ml$/i, '')),
+  };
+}
+
+function serializeTokens(tokens: string[]): string {
+  return tokens
+    .map((token) => (/\s|["'\\]/.test(token) ? JSON.stringify(token) : token))
+    .join(' ');
+}
+
+function parseClockTime(text: string): { hour: number; minute: number } | null {
+  const match = text.match(/^(\d{1,2})[:：](\d{1,2})$/);
+  if (!match) return null;
+  const hour = Number.parseInt(match[1]!, 10);
+  const minute = Number.parseInt(match[2]!, 10);
+  if (hour < 0 || hour > 23 || minute < 0 || minute > 59) return null;
+  return { hour, minute };
+}
+
+function weekdayNumber(day: string): number {
+  return ({ 日: 0, 天: 0, 一: 1, 二: 2, 三: 3, 四: 4, 五: 5, 六: 6 } as Record<string, number>)[day] ?? 1;
+}
+
+function deriveName(prompt: string): string {
+  const compact = prompt.replace(/\s+/g, ' ').trim();
+  return compact.length > 18 ? `${compact.slice(0, 18)}...` : compact || 'cron task';
+}
+
+async function setStatus(id: string | undefined, status: CronTask['status']): Promise<string> {
+  if (!id) return '请提供任务 id。';
+  const task = await getTask(id);
+  if (!task) return `未找到任务：${id}`;
+  await updateTask(task.id, (latest) => ({ ...latest, status }));
+  return `已${status === 'active' ? '恢复' : '暂停'} ${task.id}`;
+}
+
+async function remove(id: string | undefined): Promise<string> {
+  if (!id) return '请提供任务 id。';
+  return (await deleteTask(id)) ? `已删除 ${id}` : `未找到任务：${id}`;
+}
+
+async function show(id: string | undefined): Promise<string> {
+  if (!id) return '请提供任务 id。';
+  const task = await getTask(id);
+  if (!task) return `未找到任务：${id}`;
+  const runs = await recentRuns(task.id, 5);
+  const runLines =
+    runs.length === 0
+      ? '最近运行：无'
+      : `最近运行：\n${runs.map((r) => `- ${formatDateTime(r.startedAt)} ${r.status}${r.error ? ` · ${r.error}` : ''}`).join('\n')}`;
+  return `${await formatTask(task)}\n${runLines}`;
+}
+
+async function runNow(id: string | undefined, scheduler: Scheduler | null): Promise<string> {
+  if (!id) return '请提供任务 id。';
+  if (!scheduler) return 'cron scheduler 尚未启动；请在 TUI 中运行。';
+  const task = await getTask(id);
+  if (!task) return `未找到任务：${id}`;
+  void scheduler.runTaskNow(task.id);
+  return `已开始手动运行 ${task.id}`;
+}
+
+async function formatMissed(): Promise<string> {
+  const missed = await listMissed(20);
+  if (missed.length === 0) return '暂无错过任务。';
+  return [
+    '错过任务：',
+    ...missed.map(
+      (m) =>
+        `- ${m.taskId} · ${m.taskName} · ${m.reason === 'overlap' ? '运行重叠' : m.reason === 'binding_unavailable' ? '会话绑定失效' : '宿主离线'}跳过 ${m.missedCount} 次 · 计划 ${formatDateTime(m.scheduledFor)} · ${m.actionPreview}`,
+    ),
+  ].join('\n');
+}
+
+async function formatTaskList(tasks: CronTask[]): Promise<string> {
+  if (tasks.length === 0) return '暂无 cron 任务。';
+  const missed = await listMissed(1);
+  const header = missed.length > 0 ? `提示：有错过任务，可用 /cron missed 查看。\n\n` : '';
+  const body = await Promise.all(tasks.map(formatTask));
+  return `${header}${body.join('\n\n')}`;
+}
+
+async function formatTask(task: CronTask): Promise<string> {
+  const action =
+    task.action.type === 'workflow'
+      ? `/workflow ${task.action.command}`
+      : task.action.prompt;
+  const runs = await recentRuns(task.id, 1);
+  const recent = runs[0]
+    ? `${runs[0].status}${runs[0].error ? ` · ${runs[0].error}` : ''}`
+    : '-';
+  return [
+    `${task.id} · ${task.name}`,
+    `状态：${task.status === 'active' ? '活跃' : '暂停'}`,
+    `类型：${task.kind === 'once' ? '一次性' : task.maxRuns ? `限 ${task.maxRuns} 次` : '重复'}`,
+    `下次运行：${formatDateTime(task.schedule.nextRunAt)}`,
+    `上次运行时间：${formatDateTime(task.stats.lastRunAt)}`,
+    `详情：${task.description ?? '-'}`,
+    `运行环境：${task.runtime.environment}`,
+    `项目：${task.runtime.cwd}`,
+    `重复次数：${task.stats.runCount}${task.maxRuns ? `/${task.maxRuns}（跑满自动暂停）` : ''}`,
+    `跳过次数：${task.stats.skippedCount}`,
+    `会话：${task.runtime.sessionMode === 'fresh' ? '每次全新' : '持续会话'}`,
+    `模型：${task.runtime.model ?? '-'}`,
+    `最近结果：${recent}`,
+    `计划：${task.schedule.human} (${task.schedule.type === 'cron' ? `${task.schedule.cron}, ${task.schedule.timezone}` : `锚点 ${formatDateTime(task.schedule.anchorAt)}`})`,
+    `动作：${action}`,
+  ].join('\n');
+}
+
+function helpText(): string {
+  return [
+    '用法：',
+    '/cron 120m 整理最近 AI 新闻',
+    '/cron 1d 整理每日国际新闻 /workflow daily-news.yaml 生成中文新闻稿',
+    '/cron 1m 检查学生作业 workflow inspect-homework.yaml 摄像头画面在 camera.jpg',
+    '/cron 每天 6:07 写国际 AI 晨间简报',
+    '/cron 工作日 6:07 写过去 48 小时国际 AI 大事',
+    '/cron 每周一 6:07 整理国际 AI 超级个体创业案例',
+    '/cron create --name "晨间简报" --cron "7 6 * * 2-6,0" --prompt "写国际 AI 简报"',
+    '/cron create --name "提醒" --cron "5 13 * * *" --prompt "执行提醒" --once',
+    '/cron create --name "周报" --cron "7 6 * * 1" --workflow "plan \\"整理周报\\"" --permanent',
+    '/cron create --name "定时PPT" --cron "0 */2 * * *" --workflow "ppt.yaml 做个X方案" --max-runs 5',
+    '/cron create --name "独立日报" --cron "7 6 * * *" --workflow "daily-news.yaml" --fresh-session',
+    '/cron list',
+    '/cron pause <id>',
+    '/cron resume <id>',
+    '/cron run <id>',
+    '/cron show <id>',
+    '/cron missed',
+    '/cron delete <id>',
+  ].join('\n');
+}
+
+function tokenize(input: string): string[] {
+  const out: string[] = [];
+  let cur = '';
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]!;
+    if (quote) {
+      if (ch === '\\' && i + 1 < input.length) {
+        cur += input[++i]!;
+      } else if (ch === quote) {
+        quote = null;
+      } else {
+        cur += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (cur) {
+        out.push(cur);
+        cur = '';
+      }
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+function parseOptions(argv: string[]): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i]!;
+    if (!key.startsWith('--')) continue;
+    const value = argv[i + 1];
+    if (!value || value.startsWith('--')) {
+      map[toCamel(key.slice(2))] = 'true';
+      continue;
+    }
+    map[toCamel(key.slice(2))] = value;
+    i++;
+  }
+  return map;
+}
+
+function toCamel(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}

package/plugins/cron-runner/src/cronTime.ts

@@ -0,0 +1,155 @@
+export interface CronFields {
+  minute: number[];
+  hour: number[];
+  dayOfMonth: number[];
+  month: number[];
+  dayOfWeek: number[];
+}
+
+const FIELD_RANGES = [
+  { min: 0, max: 59 },
+  { min: 0, max: 23 },
+  { min: 1, max: 31 },
+  { min: 1, max: 12 },
+  { min: 0, max: 6 },
+] as const;
+
+function expandField(field: string, min: number, max: number): number[] | null {
+  const out = new Set<number>();
+  for (const raw of field.split(',')) {
+    const part = raw.trim();
+    const stepMatch = part.match(/^\*(?:\/(\d+))?$/);
+    if (stepMatch) {
+      const step = stepMatch[1] ? Number.parseInt(stepMatch[1], 10) : 1;
+      if (step < 1) return null;
+      for (let i = min; i <= max; i += step) out.add(i);
+      continue;
+    }
+
+    const rangeMatch = part.match(/^(\d+)-(\d+)(?:\/(\d+))?$/);
+    if (rangeMatch) {
+      const lo = Number.parseInt(rangeMatch[1]!, 10);
+      const hi = Number.parseInt(rangeMatch[2]!, 10);
+      const step = rangeMatch[3] ? Number.parseInt(rangeMatch[3], 10) : 1;
+      const isDow = min === 0 && max === 6;
+      const effMax = isDow ? 7 : max;
+      if (lo > hi || step < 1 || lo < min || hi > effMax) return null;
+      for (let i = lo; i <= hi; i += step) out.add(isDow && i === 7 ? 0 : i);
+      continue;
+    }
+
+    if (/^\d+$/.test(part)) {
+      let n = Number.parseInt(part, 10);
+      if (min === 0 && max === 6 && n === 7) n = 0;
+      if (n < min || n > max) return null;
+      out.add(n);
+      continue;
+    }
+
+    return null;
+  }
+  return out.size > 0 ? Array.from(out).sort((a, b) => a - b) : null;
+}
+
+export function parseCronExpression(expr: string): CronFields | null {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) return null;
+  const expanded = parts.map((p, i) => expandField(p, FIELD_RANGES[i]!.min, FIELD_RANGES[i]!.max));
+  if (expanded.some((v) => v === null)) return null;
+  return {
+    minute: expanded[0]!,
+    hour: expanded[1]!,
+    dayOfMonth: expanded[2]!,
+    month: expanded[3]!,
+    dayOfWeek: expanded[4]!,
+  } as CronFields;
+}
+
+export function nextCronRunMs(cron: string, fromMs = Date.now()): number | null {
+  const fields = parseCronExpression(cron);
+  if (!fields) return null;
+  const next = computeNextCronRun(fields, new Date(fromMs));
+  return next ? next.getTime() : null;
+}
+
+export function computeNextCronRun(fields: CronFields, from: Date): Date | null {
+  const t = new Date(from.getTime());
+  t.setSeconds(0, 0);
+  t.setMinutes(t.getMinutes() + 1);
+
+  for (let i = 0; i < 366 * 24 * 60; i++) {
+    if (cronFieldsMatchDate(fields, t)) {
+      return new Date(t.getTime());
+    }
+    t.setMinutes(t.getMinutes() + 1);
+  }
+  return null;
+}
+
+export function cronFieldsMatchDate(fields: CronFields, date: Date): boolean {
+  const domMatches = fields.dayOfMonth.includes(date.getDate());
+  const dowMatches = fields.dayOfWeek.includes(date.getDay());
+  const domWild = fields.dayOfMonth.length === 31;
+  const dowWild = fields.dayOfWeek.length === 7;
+  const dayMatches =
+    domWild && dowWild
+      ? true
+      : domWild
+        ? dowMatches
+        : dowWild
+          ? domMatches
+          : domMatches || dowMatches;
+  return (
+    fields.month.includes(date.getMonth() + 1) &&
+    dayMatches &&
+    fields.hour.includes(date.getHours()) &&
+    fields.minute.includes(date.getMinutes())
+  );
+}
+
+export function cronToHuman(cron: string): string {
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length !== 5) return cron;
+  const [minute, hour, dom, month, dow] = parts;
+  if (minute === '*' && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+    return '每分钟'; // 全通配 = 每分钟一次（否则会掉进下面「每天 * *」的无意义分支）
+  }
+  const time =
+    /^\d+$/.test(minute) && /^\d+$/.test(hour)
+      ? `${hour.padStart(2, '0')}:${minute.padStart(2, '0')}`
+      : `${minute} ${hour}`;
+  if (/^\d+$/.test(minute) && hour === '*') return `每小时 ${minute.padStart(2, '0')} 分`;
+  const hourStep = hour.match(/^\*\/(\d+)$/);
+  if (/^\d+$/.test(minute) && hourStep && dom === '*' && month === '*' && dow === '*') {
+    return `每 ${hourStep[1]} 小时 ${minute.padStart(2, '0')} 分`;
+  }
+  const minuteStep = minute.match(/^\*\/(\d+)$/);
+  if (minuteStep && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+    return `每 ${minuteStep[1]} 分钟`;
+  }
+  if (dom === '*' && month === '*' && dow === '*') return `每天 ${time}`;
+  if (dom === '*' && month === '*' && dow === '1-5') return `工作日 ${time}`;
+  if (dom === '*' && month === '*' && dow) return `每周 ${formatDow(dow)} ${time}`;
+  return cron;
+}
+
+export function formatDateTime(msOrIso?: number | string): string {
+  if (msOrIso === undefined) return '-';
+  const d = typeof msOrIso === 'number' ? new Date(msOrIso) : new Date(msOrIso);
+  if (Number.isNaN(d.getTime())) return '-';
+  return d.toLocaleString('zh-CN', {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    weekday: 'short',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+function formatDow(dow: string): string {
+  const names = ['周日', '周一', '周二', '周三', '周四', '周五', '周六'];
+  const fields = parseCronExpression(`0 0 * * ${dow}`)?.dayOfWeek;
+  if (!fields) return dow;
+  return fields.map((d) => names[d]).join('、');
+}

package/plugins/cron-runner/src/lock.ts

@@ -0,0 +1,79 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+interface SchedulerLock {
+  owner: string;
+  pid: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export function schedulerLockFile(root: string): string {
+  return join(root, 'scheduler.lock');
+}
+
+export async function tryAcquireSchedulerLock(
+  file: string,
+  owner: string,
+): Promise<boolean> {
+  await mkdir(dirname(file), { recursive: true });
+  const lock: SchedulerLock = {
+    owner,
+    pid: process.pid,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  if (await tryCreateExclusive(file, lock)) return true;
+
+  const existing = await readLock(file);
+  if (!existing) return await tryCreateExclusive(file, lock);
+  if (existing.owner === owner) {
+    await writeFile(file, JSON.stringify({ ...existing, pid: process.pid, updatedAt: lock.updatedAt }, null, 2), 'utf8');
+    return true;
+  }
+  if (isPidAlive(existing.pid)) return false;
+  await rm(file, { force: true });
+  return await tryCreateExclusive(file, lock);
+}
+
+export async function releaseSchedulerLock(file: string, owner: string): Promise<void> {
+  const existing = await readLock(file);
+  if (!existing || existing.owner !== owner) return;
+  await rm(file, { force: true });
+}
+
+async function tryCreateExclusive(file: string, lock: SchedulerLock): Promise<boolean> {
+  try {
+    await writeFile(file, JSON.stringify(lock, null, 2), { encoding: 'utf8', flag: 'wx' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readLock(file: string): Promise<SchedulerLock | null> {
+  try {
+    const parsed = JSON.parse(await readFile(file, 'utf8')) as Partial<SchedulerLock>;
+    if (
+      typeof parsed.owner !== 'string' ||
+      typeof parsed.pid !== 'number' ||
+      typeof parsed.createdAt !== 'string' ||
+      typeof parsed.updatedAt !== 'string'
+    ) {
+      return null;
+    }
+    return parsed as SchedulerLock;
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}