@jacfrost/autopm 0.0.1

package/src/autopm/loop-commands.js

@@ -0,0 +1,924 @@
+import path from 'node:path';
+
+import { schedulerDiagnostic } from './scheduler/contracts.js';
+import { runAutoPmSchedulerJob } from './scheduler/runner.js';
+import { buildRuntimeStateForJob, normalizeSchedule } from './scheduler/schedule.js';
+import {
+  readAutoPmSchedulerStore,
+  writeAutoPmSchedulerState,
+  writeAutoPmSchedulerStore,
+} from './scheduler/store.js';
+
+const SOURCE_OF_TRUTH = 'autopm-scheduler-store';
+const SUPPORTED_ACTIONS = Object.freeze(['status', 'list', 'add', 'show', 'edit', 'remove', 'pause', 'resume', 'run']);
+const MUTATING_ACTIONS = new Set(['add', 'edit', 'remove', 'pause', 'resume', 'run']);
+const SECRET_ARG_NAME_PATTERN = /(?:^|[-_])(api[-_]?key|authorization|auth[-_]?token|access[-_]?token|refresh[-_]?token|secret|password|passwd|credential|token)(?:$|[-_])/i;
+const SAFE_FLAG_NAME_PATTERN = /^--[A-Za-z][A-Za-z0-9-]{0,63}$/;
+const SECRET_VALUE_PATTERNS = Object.freeze([
+  /Bearer\s+[A-Za-z0-9._~+/=-]+/gi,
+  /sk-[A-Za-z0-9_-]{12,}/g,
+  /\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API[-_]?KEY|AUTHORIZATION|CREDENTIAL)[A-Z0-9_]*)\s*[:=]\s*([^\s,;"'`]+|["'`][^"'`]*["'`])/gi,
+  /("(?:token|secret|password|apiKey|api_key|authorization|credential)"\s*:\s*")[^"]+(")/gi,
+]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function uniqueStrings(values) {
+  return [...new Set((Array.isArray(values) ? values : []).filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+function redactText(value) {
+  let text = String(value ?? '');
+  for (const pattern of SECRET_VALUE_PATTERNS) {
+    pattern.lastIndex = 0;
+    text = text.replace(pattern, (...args) => {
+      if (pattern.source.startsWith('("')) return `${args[1]}[REDACTED]${args[2]}`;
+      if (args.length > 3 && typeof args[1] === 'string') return `${args[1]}=[REDACTED]`;
+      if (/^Bearer/i.test(args[0])) return 'Bearer [REDACTED]';
+      return '[REDACTED]';
+    });
+  }
+  return text;
+}
+
+function safeFlagName(value) {
+  const raw = String(value ?? '');
+  const equalsIndex = raw.indexOf('=');
+  const name = equalsIndex >= 0 ? raw.slice(0, equalsIndex) : raw;
+  if (!SAFE_FLAG_NAME_PATTERN.test(name) || SECRET_ARG_NAME_PATTERN.test(name)) return '--[redacted]';
+  return name;
+}
+
+function safeArgumentValue(value) {
+  const raw = String(value ?? '');
+  if (SECRET_ARG_NAME_PATTERN.test(raw)) return '[REDACTED]';
+  return redactText(raw);
+}
+
+function sanitizeValue(value, seen = new WeakSet(), key = '') {
+  if (typeof value === 'string') return redactText(value);
+  if (typeof value === 'number' || typeof value === 'boolean' || value === null) return value;
+  if (typeof value === 'bigint') return String(value);
+  if (typeof value === 'undefined') return null;
+  if (typeof value === 'function' || typeof value === 'symbol') return `[${typeof value}]`;
+  if (Array.isArray(value)) return value.slice(0, 100).map((item) => sanitizeValue(item, seen));
+  if (!isPlainObject(value)) return redactText(value instanceof Error ? value.message : String(value));
+  if (seen.has(value)) return '[circular]';
+
+  seen.add(value);
+  const output = {};
+  for (const [childKey, child] of Object.entries(value).slice(0, 100)) {
+    if (SECRET_ARG_NAME_PATTERN.test(childKey)) {
+      output[childKey] = '[REDACTED]';
+      continue;
+    }
+    output[childKey] = sanitizeValue(child, seen, childKey);
+  }
+  seen.delete(value);
+  return key && SECRET_ARG_NAME_PATTERN.test(key) ? '[REDACTED]' : output;
+}
+
+function diagnostic(code, severity, message, details = {}, diagnosticPath = '$') {
+  return schedulerDiagnostic({
+    code,
+    severity,
+    message,
+    path: diagnosticPath,
+    details: sanitizeValue(details),
+  });
+}
+
+function errorRecord(code, message, details = {}, diagnosticPath = '$') {
+  return diagnostic(code, 'error', message, details, diagnosticPath);
+}
+
+function normalizeDiagnostics(records, severity) {
+  if (!Array.isArray(records)) return [];
+  return records
+    .filter((record) => isPlainObject(record) && typeof record.code === 'string' && record.code.length > 0)
+    .map((record) => diagnostic(record.code, record.severity ?? severity, record.message ?? record.code, record.details ?? {}, record.path ?? '$'));
+}
+
+function diagnosticsBySeverity(records, severity) {
+  return normalizeDiagnostics(records, severity).filter((record) => record.severity === severity);
+}
+
+function codesFor(records, severity) {
+  return uniqueStrings(normalizeDiagnostics(records, severity)
+    .filter((record) => record.severity === severity)
+    .map((record) => record.code));
+}
+
+function tokenizeArgs(args) {
+  const input = String(args ?? '');
+  const tokens = [];
+  let current = '';
+  let quote = null;
+  let hasCurrent = false;
+  let escaping = false;
+
+  for (const char of input) {
+    if (escaping) {
+      current += char;
+      hasCurrent = true;
+      escaping = false;
+      continue;
+    }
+    if (char === '\\') {
+      escaping = true;
+      hasCurrent = true;
+      continue;
+    }
+    if (quote !== null) {
+      if (char === quote) {
+        quote = null;
+        hasCurrent = true;
+      } else {
+        current += char;
+        hasCurrent = true;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      hasCurrent = true;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (hasCurrent) {
+        tokens.push(current);
+        current = '';
+        hasCurrent = false;
+      }
+      continue;
+    }
+    current += char;
+    hasCurrent = true;
+  }
+
+  if (escaping) current += '\\';
+  if (quote !== null) {
+    return {
+      ok: false,
+      code: 'CLI_ARG_PARSE_FAILED',
+      message: 'AutoPM loop scheduler arguments contain an unterminated quoted string.',
+    };
+  }
+  if (hasCurrent) tokens.push(current);
+  return { ok: true, tokens };
+}
+
+function parseFailure(code, message, details = {}, action = 'status') {
+  return {
+    ok: false,
+    schedulerAction: action,
+    error: errorRecord(code, message, details),
+  };
+}
+
+function isMutableFlag(flag) {
+  return ['--title', '--schedule', '--description', '--task', '--message', '--enabled', '--disabled'].includes(flag);
+}
+
+function readFlagValue(tokens, index, flag) {
+  const nextIndex = index + 1;
+  const value = tokens[nextIndex];
+  if (typeof value !== 'string' || value.trim() === '' || value.startsWith('--')) {
+    return { ok: false, flag };
+  }
+  return { ok: true, value, nextIndex };
+}
+
+function applyFlag(parsed, flag, value) {
+  const keyByFlag = {
+    '--id': 'id',
+    '--title': 'title',
+    '--schedule': 'schedule',
+    '--description': 'description',
+    '--task': 'task',
+    '--message': 'message',
+  };
+  const key = keyByFlag[flag];
+  if (!key) return false;
+  parsed[key] = value;
+  return true;
+}
+
+function validateParsedArgs(parsed) {
+  if (parsed.schedulerAction === 'add') {
+    if (!parsed.id) return parseFailure('CLI_ARG_JOB_ID_REQUIRED', '/loop add requires --id <job-id>.', { flag: '--id' }, 'add');
+    if (!parsed.title) return parseFailure('CLI_ARG_TITLE_REQUIRED', '/loop add requires --title <title>.', { flag: '--title' }, 'add');
+    if (!parsed.schedule) return parseFailure('CLI_ARG_SCHEDULE_REQUIRED', '/loop add requires --schedule <schedule>.', { flag: '--schedule' }, 'add');
+  }
+
+  if (['pause', 'resume'].includes(parsed.schedulerAction) && !parsed.id) {
+    return parseFailure('CLI_ARG_JOB_ID_REQUIRED', `/loop ${parsed.schedulerAction} requires a job id or --id <job-id>.`, { flag: '--id' }, parsed.schedulerAction);
+  }
+
+  if (['show', 'edit', 'remove', 'run'].includes(parsed.schedulerAction) && !parsed.id) {
+    return parseFailure('CLI_ARG_JOB_ID_REQUIRED', `/loop ${parsed.schedulerAction} requires a job id or --id <job-id>.`, { flag: '--id' }, parsed.schedulerAction);
+  }
+
+  if (parsed.schedulerAction === 'edit' && parsed.mutableFlagCount === 0) {
+    return parseFailure('CLI_ARG_EDIT_FIELD_REQUIRED', '/loop edit requires at least one mutable field flag.', {}, 'edit');
+  }
+
+  return parsed;
+}
+
+export function parseAutoPmLoopCommandArgs(command = 'loop', args = '') {
+  const tokenized = tokenizeArgs(args);
+  if (!tokenized.ok) return parseFailure(tokenized.code, tokenized.message);
+
+  const parsed = {
+    ok: true,
+    command,
+    schedulerAction: null,
+    json: false,
+    id: undefined,
+    title: undefined,
+    schedule: undefined,
+    description: undefined,
+    task: undefined,
+    message: undefined,
+    enabled: undefined,
+    mutableFlagCount: 0,
+  };
+
+  for (let index = 0; index < tokenized.tokens.length; index += 1) {
+    const token = tokenized.tokens[index];
+
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+
+    if (token === '--enabled' || token === '--disabled') {
+      parsed.enabled = token === '--enabled';
+      parsed.mutableFlagCount += 1;
+      continue;
+    }
+
+    const equalsIndex = token.indexOf('=');
+    const flag = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;
+    if (flag.startsWith('--')) {
+      if (equalsIndex >= 0) {
+        const value = token.slice(equalsIndex + 1);
+        if (value.trim() === '') {
+          return parseFailure('CLI_ARG_VALUE_MISSING', `Flag ${safeFlagName(flag)} requires a non-empty value.`, { flag: safeFlagName(flag) }, parsed.schedulerAction ?? 'status');
+        }
+        if (!applyFlag(parsed, flag, value)) {
+          return parseFailure('CLI_ARG_UNSUPPORTED_FLAG', 'Unsupported AutoPM loop scheduler flag.', { flag: safeFlagName(flag) }, parsed.schedulerAction ?? 'status');
+        }
+        if (isMutableFlag(flag)) parsed.mutableFlagCount += 1;
+        continue;
+      }
+
+      const read = readFlagValue(tokenized.tokens, index, token);
+      if (!read.ok) {
+        return parseFailure('CLI_ARG_VALUE_MISSING', `Flag ${safeFlagName(token)} requires a non-empty value.`, { flag: safeFlagName(token) }, parsed.schedulerAction ?? 'status');
+      }
+      if (!applyFlag(parsed, token, read.value)) {
+        return parseFailure('CLI_ARG_UNSUPPORTED_FLAG', 'Unsupported AutoPM loop scheduler flag.', { flag: safeFlagName(token) }, parsed.schedulerAction ?? 'status');
+      }
+      if (isMutableFlag(token)) parsed.mutableFlagCount += 1;
+      index = read.nextIndex;
+      continue;
+    }
+
+    if (parsed.schedulerAction === null) {
+      if (!SUPPORTED_ACTIONS.includes(token)) {
+        return parseFailure('CLI_ARG_UNSUPPORTED_ACTION', 'Unsupported AutoPM loop scheduler action.', { action: safeArgumentValue(token) }, 'status');
+      }
+      parsed.schedulerAction = token;
+      continue;
+    }
+
+    if (['show', 'edit', 'remove', 'pause', 'resume', 'run'].includes(parsed.schedulerAction) && !parsed.id) {
+      parsed.id = token.trim();
+      continue;
+    }
+
+    return parseFailure('CLI_ARG_EXTRA_POSITIONAL', 'AutoPM loop scheduler commands do not accept extra positional arguments.', { token: safeArgumentValue(token) }, parsed.schedulerAction);
+  }
+
+  parsed.schedulerAction ??= 'status';
+  return validateParsedArgs(parsed);
+}
+
+function resolveProjectRoot(projectRoot, ctx) {
+  const value = typeof projectRoot === 'function' ? projectRoot(ctx) : projectRoot;
+  return path.resolve(typeof value === 'string' && value.trim() !== '' ? value : process.cwd());
+}
+
+function parseClock(value) {
+  if (value instanceof Date) return new Date(value.getTime());
+  if (typeof value === 'string' || typeof value === 'number') {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime())) return date;
+  }
+  return new Date();
+}
+
+function safeNextActionFor(command, action, status, jobId = null) {
+  if (status === 'error') {
+    return {
+      command: `/${command} status`,
+      label: 'Inspect scheduler status',
+      source: 'autopm-loop-scheduler-command',
+      rationale: 'Inspect redacted scheduler diagnostics before retrying the command.',
+    };
+  }
+  if (action === 'add' || action === 'edit' || action === 'pause' || action === 'resume' || action === 'run') {
+    return {
+      command: `/${command} show ${jobId ?? '<job-id>'}`,
+      label: 'Inspect scheduled job',
+      source: 'autopm-loop-scheduler-command',
+      rationale: 'Confirm persisted job definition, enabled state, next trigger, and latest run result.',
+    };
+  }
+  if (action === 'remove') {
+    return {
+      command: `/${command} list`,
+      label: 'List scheduled jobs',
+      source: 'autopm-loop-scheduler-command',
+      rationale: 'Confirm the scheduler job list after removal.',
+    };
+  }
+  return {
+    command: `/${command} list`,
+    label: 'List scheduled jobs',
+    source: 'autopm-loop-scheduler-command',
+    rationale: 'Inspect configured AutoPM scheduled jobs and next trigger times.',
+  };
+}
+
+function toRuntimeState(job, previousState, options) {
+  const state = buildRuntimeStateForJob(job, {
+    previousState,
+    now: options.now,
+    maxLookaheadMinutes: options.maxLookaheadMinutes,
+  });
+  return {
+    id: state.id ?? job.id,
+    nextRunAt: state.nextRunAt,
+    lastRunAt: state.lastRunAt,
+    lastStatus: state.lastStatus,
+    lastSummary: state.lastSummary,
+    failureCount: state.failureCount,
+    diagnostics: state.diagnostics,
+  };
+}
+
+function rebuildRuntimeStates(jobs, previousStates, options) {
+  return jobs.map((job) => toRuntimeState(job, previousStates[job.id] ?? {}, options));
+}
+
+function findJob(read, id) {
+  return read.jobs.find((job) => job.id === id) ?? null;
+}
+
+function normalizeJobSchedule(scheduleInput) {
+  const normalized = normalizeSchedule(scheduleInput);
+  if (!normalized.ok || !normalized.schedule) {
+    return {
+      ok: false,
+      diagnostics: normalized.diagnostics,
+      errorCodes: normalized.errorCodes,
+      warningCodes: normalized.warningCodes,
+      schedule: null,
+    };
+  }
+  return normalized;
+}
+
+function commandStatus(diagnostics, fallback = 'ok') {
+  if (diagnostics.some((record) => record.severity === 'error')) return 'error';
+  if (diagnostics.some((record) => record.severity === 'warning')) return 'warn';
+  return fallback;
+}
+
+function schedulerEnvelope({
+  command = 'loop',
+  action = 'status',
+  status = 'ok',
+  generatedAt = new Date().toISOString(),
+  jobs = [],
+  job = null,
+  artifactPathsRead = [],
+  artifactPathsWritten = [],
+  warnings = [],
+  errors = [],
+  durableStateChanged = false,
+  safeNextAction = null,
+  json = false,
+  text = null,
+  extra = {},
+}) {
+  const warningRecords = diagnosticsBySeverity(warnings, 'warning');
+  const errorRecords = diagnosticsBySeverity(errors, 'error');
+  const allDiagnostics = [...warningRecords, ...errorRecords];
+  const envelope = sanitizeValue({
+    command,
+    subcommand: action,
+    schedulerAction: action,
+    implemented: true,
+    delegatedLegacyCommand: null,
+    sourceOfTruth: SOURCE_OF_TRUTH,
+    status,
+    jobCount: Array.isArray(jobs) ? jobs.length : 0,
+    jobs,
+    job,
+    artifactPathsRead: uniqueStrings(artifactPathsRead),
+    artifactPathsWritten: uniqueStrings(artifactPathsWritten),
+    warningCodes: uniqueStrings([...codesFor(warningRecords, 'warning'), ...(extra.warningCodes ?? [])]),
+    errorCodes: uniqueStrings([...codesFor(errorRecords, 'error'), ...(extra.errorCodes ?? [])]),
+    warnings: warningRecords,
+    errors: errorRecords,
+    diagnostics: allDiagnostics,
+    generatedAt,
+    durableStateChanged: durableStateChanged === true,
+    safeNextAction,
+    nextAction: safeNextAction?.command ?? null,
+    text,
+  });
+  if (json === true) envelope.json = true;
+  for (const [key, value] of Object.entries(extra)) {
+    if (['warningCodes', 'errorCodes'].includes(key)) continue;
+    envelope[key] = sanitizeValue(value);
+  }
+  return envelope;
+}
+
+function parseErrorEnvelope(command, parsed) {
+  const action = parsed.schedulerAction ?? 'status';
+  return schedulerEnvelope({
+    command,
+    action,
+    status: 'error',
+    errors: [parsed.error],
+    durableStateChanged: false,
+    safeNextAction: safeNextActionFor(command, action, 'error'),
+    text: renderText({ action, status: 'error', jobs: [], errors: [parsed.error], warnings: [] }),
+  });
+}
+
+function adapterErrorEnvelope(command, action, code, message, details = {}, { json = false } = {}) {
+  const error = errorRecord(code, message, details);
+  return schedulerEnvelope({
+    command,
+    action,
+    status: 'error',
+    errors: [error],
+    durableStateChanged: false,
+    safeNextAction: safeNextActionFor(command, action, 'error'),
+    json,
+    text: renderText({ action, status: 'error', jobs: [], errors: [error], warnings: [] }),
+  });
+}
+
+function readErrorEnvelope(command, action, read, parsed) {
+  return schedulerEnvelope({
+    command,
+    action,
+    status: 'error',
+    jobs: [],
+    artifactPathsRead: read.artifactPathsRead,
+    artifactPathsWritten: [],
+    warnings: read.diagnostics,
+    errors: read.diagnostics,
+    durableStateChanged: false,
+    safeNextAction: safeNextActionFor(command, action, 'error'),
+    json: parsed.json,
+    text: renderText({ action, status: 'error', jobs: [], errors: read.diagnostics, warnings: read.diagnostics }),
+  });
+}
+
+function jobNotFoundEnvelope(command, action, read, parsed) {
+  const error = errorRecord('AUTOPM_SCHEDULER_JOB_NOT_FOUND', 'AutoPM scheduler job was not found.', { id: parsed.id });
+  return schedulerEnvelope({
+    command,
+    action,
+    status: 'error',
+    jobs: read.jobs,
+    artifactPathsRead: read.artifactPathsRead,
+    errors: [error],
+    durableStateChanged: false,
+    safeNextAction: safeNextActionFor(command, action, 'error', parsed.id),
+    json: parsed.json,
+    text: renderText({ action, status: 'error', jobs: read.jobs, errors: [error], warnings: [] }),
+  });
+}
+
+function scheduleErrorEnvelope(command, action, read, parsed, normalized) {
+  return schedulerEnvelope({
+    command,
+    action,
+    status: 'error',
+    jobs: read.jobs,
+    artifactPathsRead: read.artifactPathsRead,
+    warnings: normalized.diagnostics,
+    errors: normalized.diagnostics,
+    durableStateChanged: false,
+    safeNextAction: safeNextActionFor(command, action, 'error', parsed.id),
+    json: parsed.json,
+    text: renderText({ action, status: 'error', jobs: read.jobs, errors: normalized.diagnostics, warnings: normalized.diagnostics }),
+  });
+}
+
+function formatSchedule(schedule) {
+  if (!isPlainObject(schedule)) return 'unknown';
+  if (schedule.kind === 'cron') return `cron ${schedule.expression}${schedule.timezone ? ` (${schedule.timezone})` : ''}`;
+  if (schedule.kind === 'interval') return `every ${schedule.everyMinutes} minute${schedule.everyMinutes === 1 ? '' : 's'}`;
+  if (schedule.kind === 'once') return `at ${schedule.runAt}`;
+  if (schedule.kind === 'manual') return 'manual';
+  return schedule.kind ?? 'unknown';
+}
+
+function lastStatusFor(job, states) {
+  const state = states?.[job.id];
+  return typeof state?.lastStatus === 'string' ? state.lastStatus : 'never';
+}
+
+function nextRunFor(job, states) {
+  const state = states?.[job.id];
+  return typeof state?.nextRunAt === 'string' ? state.nextRunAt : 'none';
+}
+
+function lastRunFor(job, states) {
+  const state = states?.[job.id];
+  return typeof state?.lastRunAt === 'string' ? state.lastRunAt : 'none';
+}
+
+function lastSummaryFor(job, states) {
+  const state = states?.[job.id];
+  return typeof state?.lastSummary === 'string' && state.lastSummary.trim() !== '' ? state.lastSummary : 'none';
+}
+
+function renderRows(jobs, states = {}) {
+  if (!Array.isArray(jobs) || jobs.length === 0) return ['(no scheduled jobs)'];
+  return [
+    'ID | Title | Schedule | Next trigger | Enabled | Last status',
+    ...jobs.map((job) => [
+      job.id,
+      job.title,
+      formatSchedule(job.schedule),
+      nextRunFor(job, states),
+      job.enabled === false ? 'no' : 'yes',
+      lastStatusFor(job, states),
+    ].join(' | ')),
+  ];
+}
+
+function renderText({ action, status, jobs = [], job = null, states = {}, warnings = [], errors = [] }) {
+  const header = `AutoPM scheduled jobs: ${status}`;
+  const diagnostics = normalizeDiagnostics([...warnings, ...errors], 'warning');
+  const diagnosticLine = diagnostics.length > 0
+    ? [`diagnostics: ${uniqueStrings(diagnostics.map((record) => record.code)).join(', ')}`]
+    : [];
+
+  if (action === 'show' && job) {
+    return [
+      header,
+      ...diagnosticLine,
+      `id: ${job.id}`,
+      `title: ${job.title}`,
+      `schedule: ${formatSchedule(job.schedule)}`,
+      `nextTrigger: ${nextRunFor(job, states)}`,
+      `enabled: ${job.enabled === false ? 'no' : 'yes'}`,
+      `lastStatus: ${lastStatusFor(job, states)}`,
+      `lastRunAt: ${lastRunFor(job, states)}`,
+      `lastSummary: ${lastSummaryFor(job, states)}`,
+      `task: ${job.task}`,
+    ].join('\n');
+  }
+
+  return [
+    header,
+    ...diagnosticLine,
+    ...renderRows(jobs, states),
+  ].join('\n');
+}
+
+function sortedJobs(jobs) {
+  return [...jobs].sort((a, b) => String(a.id).localeCompare(String(b.id)));
+}
+
+function writableReadOrError(command, action, read, parsed) {
+  if (read.errorCodes.length > 0 || read.status === 'error') return readErrorEnvelope(command, action, read, parsed);
+  return null;
+}
+
+async function executeReadOnly(command, action, read, parsed) {
+  const jobs = sortedJobs(read.jobs);
+  const job = action === 'show' ? findJob(read, parsed.id) : null;
+  if (action === 'show' && job === null) return jobNotFoundEnvelope(command, action, read, parsed);
+  const diagnostics = read.diagnostics;
+  const status = commandStatus(diagnostics, jobs.length === 0 && action === 'status' && read.initialized === false ? 'warn' : 'ok');
+  return schedulerEnvelope({
+    command,
+    action,
+    status,
+    jobs,
+    job,
+    artifactPathsRead: read.artifactPathsRead,
+    warnings: diagnostics,
+    errors: diagnostics,
+    durableStateChanged: false,
+    safeNextAction: safeNextActionFor(command, action, status, parsed.id),
+    json: parsed.json,
+    text: renderText({ action, status, jobs, job, states: read.jobStates, warnings: diagnostics, errors: diagnostics }),
+    extra: {
+      initialized: read.initialized,
+      schedulerDir: read.schedulerDir,
+      jobsPath: read.jobsPath,
+      statePath: read.statePath,
+    },
+  });
+}
+
+function makeJobFromParsed(parsed, nowIso, previous = null) {
+  return {
+    id: parsed.id,
+    title: parsed.title ?? previous?.title,
+    description: parsed.description ?? previous?.description ?? '',
+    enabled: parsed.enabled ?? previous?.enabled ?? true,
+    schedule: parsed.normalizedSchedule ?? previous?.schedule,
+    task: parsed.task ?? previous?.task ?? parsed.message ?? previous?.message ?? parsed.title ?? previous?.title,
+    message: parsed.message ?? previous?.message ?? parsed.task ?? previous?.task ?? parsed.title ?? previous?.title,
+    createdAt: previous?.createdAt ?? nowIso,
+    updatedAt: nowIso,
+    diagnostics: [],
+  };
+}
+
+function normalizeParsedScheduleIfPresent(parsed) {
+  if (typeof parsed.schedule !== 'string') return { ok: true, parsed };
+  const normalized = normalizeJobSchedule(parsed.schedule);
+  if (!normalized.ok) return normalized;
+  parsed.normalizedSchedule = normalized.schedule;
+  return { ok: true, parsed };
+}
+
+async function executeMutating(command, action, read, parsed, options) {
+  const preflight = writableReadOrError(command, action, read, parsed);
+  if (preflight) return preflight;
+
+  const nowIso = options.now.toISOString();
+  const jobs = [...read.jobs];
+  const existingIndex = parsed.id ? jobs.findIndex((job) => job.id === parsed.id) : -1;
+  const existing = existingIndex >= 0 ? jobs[existingIndex] : null;
+
+  if (action === 'add' && existing !== null) {
+    const error = errorRecord('AUTOPM_SCHEDULER_JOB_ALREADY_EXISTS', 'AutoPM scheduler job id already exists.', { id: parsed.id });
+    return schedulerEnvelope({
+      command,
+      action,
+      status: 'error',
+      jobs: sortedJobs(jobs),
+      artifactPathsRead: read.artifactPathsRead,
+      errors: [error],
+      durableStateChanged: false,
+      safeNextAction: safeNextActionFor(command, action, 'error', parsed.id),
+      json: parsed.json,
+      text: renderText({ action, status: 'error', jobs, errors: [error] }),
+    });
+  }
+
+  if (action !== 'add' && existing === null) return jobNotFoundEnvelope(command, action, read, parsed);
+
+  if (action === 'remove') {
+    jobs.splice(existingIndex, 1);
+  } else if (action === 'pause' || action === 'resume') {
+    jobs[existingIndex] = { ...existing, enabled: action === 'resume', updatedAt: nowIso };
+  } else {
+    const scheduleResult = normalizeParsedScheduleIfPresent(parsed);
+    if (!scheduleResult.ok) return scheduleErrorEnvelope(command, action, read, parsed, scheduleResult);
+    const nextJob = makeJobFromParsed(parsed, nowIso, action === 'edit' ? existing : null);
+    if (action === 'add') jobs.push(nextJob);
+    else jobs[existingIndex] = nextJob;
+  }
+
+  const jobStates = rebuildRuntimeStates(jobs, read.jobStates, options);
+  let write;
+  try {
+    write = writeAutoPmSchedulerStore({ projectRoot: options.projectRoot, jobs: sortedJobs(jobs), jobStates, generatedAt: nowIso });
+  } catch (error) {
+    return adapterErrorEnvelope(
+      command,
+      action,
+      error?.code ?? 'AUTOPM_SCHEDULER_WRITE_FAILED',
+      'AutoPM scheduler command failed while writing scheduler state.',
+      { reason: error instanceof Error ? error.message : String(error) },
+      { json: parsed.json },
+    );
+  }
+
+  const writtenJobs = sortedJobs(jobs);
+  const writtenStateById = Object.fromEntries(jobStates.map((state) => [state.id, state]));
+  const selectedJob = parsed.id ? writtenJobs.find((job) => job.id === parsed.id) ?? null : null;
+  const diagnostics = write.diagnostics;
+  const status = commandStatus(diagnostics, 'ok');
+  return schedulerEnvelope({
+    command,
+    action,
+    status,
+    jobs: writtenJobs,
+    job: selectedJob,
+    artifactPathsRead: read.artifactPathsRead,
+    artifactPathsWritten: write.artifactPathsWritten,
+    warnings: diagnostics,
+    errors: diagnostics,
+    durableStateChanged: true,
+    safeNextAction: safeNextActionFor(command, action, status, parsed.id),
+    json: parsed.json,
+    text: renderText({ action: action === 'remove' ? 'list' : action, status, jobs: writtenJobs, job: selectedJob, states: writtenStateById, warnings: diagnostics, errors: diagnostics }),
+    extra: {
+      initialized: true,
+      schedulerDir: write.schedulerDir,
+      jobsPath: write.jobsPath,
+      statePath: write.statePath,
+    },
+  });
+}
+
+function persistableRuntimeState(state) {
+  return {
+    id: state.id,
+    nextRunAt: state.nextRunAt,
+    lastRunAt: state.lastRunAt,
+    lastStatus: state.lastStatus,
+    lastSummary: state.lastSummary,
+    failureCount: state.failureCount,
+    diagnostics: Array.isArray(state.diagnostics) ? state.diagnostics : [],
+  };
+}
+
+function rebuildRuntimeStatesWithReplacement(jobs, previousStates, replacement, options) {
+  return jobs.map((job) => {
+    if (job.id === replacement.id) return persistableRuntimeState(replacement);
+    const existing = previousStates[job.id];
+    return existing ? persistableRuntimeState(existing) : toRuntimeState(job, {}, options);
+  });
+}
+
+async function executeRun(command, read, parsed, options, ctx) {
+  const action = 'run';
+  const preflight = writableReadOrError(command, action, read, parsed);
+  if (preflight) return preflight;
+
+  const job = findJob(read, parsed.id);
+  if (job === null) return jobNotFoundEnvelope(command, action, read, parsed);
+
+  const runResult = await runAutoPmSchedulerJob(job, {
+    previousState: read.jobStates[job.id] ?? {},
+    now: options.now,
+    completedAt: options.completedAt ?? options.now,
+    runId: typeof options.runId === 'function' ? options.runId(job, options.now) : options.runId,
+    executeLocalPayload: options.executeLocalPayload,
+    maxLookaheadMinutes: options.maxLookaheadMinutes,
+    signal: ctx?.signal,
+  });
+
+  if (!runResult.runtimeState) {
+    return schedulerEnvelope({
+      command,
+      action,
+      status: 'error',
+      jobs: sortedJobs(read.jobs),
+      job,
+      artifactPathsRead: read.artifactPathsRead,
+      errors: runResult.diagnostics,
+      durableStateChanged: false,
+      safeNextAction: safeNextActionFor(command, action, 'error', parsed.id),
+      json: parsed.json,
+      text: renderText({ action: 'show', status: 'error', jobs: sortedJobs(read.jobs), job, states: read.jobStates, errors: runResult.diagnostics }),
+      extra: { run: runResult.run },
+    });
+  }
+
+  const stateRecords = rebuildRuntimeStatesWithReplacement(read.jobs, read.jobStates, runResult.runtimeState, options);
+  let write;
+  try {
+    write = writeAutoPmSchedulerState({ projectRoot: options.projectRoot, jobs: stateRecords });
+  } catch (error) {
+    return adapterErrorEnvelope(
+      command,
+      action,
+      error?.code ?? 'AUTOPM_SCHEDULER_STATE_WRITE_FAILED',
+      'AutoPM scheduler run failed while writing runtime state.',
+      { reason: error instanceof Error ? error.message : String(error), runId: runResult.run?.runId },
+      { json: parsed.json },
+    );
+  }
+
+  const writtenJobs = sortedJobs(read.jobs);
+  const writtenStateById = Object.fromEntries(stateRecords.map((state) => [state.id, state]));
+  const diagnostics = [...runResult.diagnostics, ...write.diagnostics];
+  const status = commandStatus(diagnostics, runResult.status);
+  return schedulerEnvelope({
+    command,
+    action,
+    status,
+    jobs: writtenJobs,
+    job,
+    artifactPathsRead: read.artifactPathsRead,
+    artifactPathsWritten: write.artifactPathsWritten,
+    warnings: diagnostics,
+    errors: diagnostics,
+    durableStateChanged: true,
+    safeNextAction: safeNextActionFor(command, action, status, parsed.id),
+    json: parsed.json,
+    text: renderText({ action: 'show', status, jobs: writtenJobs, job, states: writtenStateById, warnings: diagnostics, errors: diagnostics }),
+    extra: {
+      initialized: true,
+      schedulerDir: read.schedulerDir,
+      jobsPath: read.jobsPath,
+      statePath: read.statePath,
+      run: runResult.run,
+      runId: runResult.run?.runId ?? null,
+    },
+  });
+}
+
+function ensureNotAborted(signal) {
+  if (signal?.aborted) {
+    const error = new Error('AutoPM loop scheduler command aborted before producing a complete result.');
+    error.name = 'AbortError';
+    throw error;
+  }
+}
+
+export async function executeInternalAutoPmLoopToolCommand(command = 'loop', args = '', options = {}, ctx = {}) {
+  const now = parseClock(options.now);
+  const parsed = parseAutoPmLoopCommandArgs(command, args);
+  if (!parsed.ok) return parseErrorEnvelope(command, parsed);
+
+  const projectRoot = resolveProjectRoot(options.projectRoot, ctx);
+  const action = parsed.schedulerAction;
+
+  try {
+    ensureNotAborted(ctx?.signal);
+    const read = readAutoPmSchedulerStore({ projectRoot, generatedAt: now.toISOString() });
+    ensureNotAborted(ctx?.signal);
+
+    if (!MUTATING_ACTIONS.has(action)) return executeReadOnly(command, action, read, parsed);
+
+    if (action === 'run') {
+      const result = await executeRun(command, read, parsed, {
+        projectRoot,
+        now,
+        completedAt: options.completedAt,
+        runId: options.runId,
+        executeLocalPayload: options.executeLocalPayload,
+        maxLookaheadMinutes: options.maxLookaheadMinutes,
+      }, ctx);
+      ensureNotAborted(ctx?.signal);
+      return result;
+    }
+
+    const result = await executeMutating(command, action, read, parsed, {
+      projectRoot,
+      now,
+      maxLookaheadMinutes: options.maxLookaheadMinutes,
+    });
+    ensureNotAborted(ctx?.signal);
+    return result;
+  } catch (error) {
+    const aborted = error?.name === 'AbortError';
+    return adapterErrorEnvelope(
+      command,
+      action,
+      aborted ? 'AUTOPM_LOOP_SCHEDULER_ABORTED' : 'AUTOPM_LOOP_SCHEDULER_FAILED',
+      aborted
+        ? 'AutoPM loop scheduler command was aborted before producing a complete result.'
+        : 'AutoPM loop scheduler command failed before producing a complete result.',
+      { reason: error instanceof Error ? error.message : String(error) },
+      { json: parsed.json },
+    );
+  }
+}
+
+export async function executeAutoPmLoopCommand(command = 'loop', args = '', options = {}, ctx = {}) {
+  return executeInternalAutoPmLoopToolCommand(command, args, options, ctx);
+}
+
+export function createInternalAutoPmLoopToolCommandHandler(options = {}) {
+  return async function internalAutoPmLoopToolCommandHandler(command, args, ctx) {
+    return executeInternalAutoPmLoopToolCommand(command, args, options, ctx);
+  };
+}
+
+export function createAutoPmLoopCommandHandler(options = {}) {
+  return createInternalAutoPmLoopToolCommandHandler(options);
+}
+
+export function loopCommandCompletions(prefix = '') {
+  const trimmed = String(prefix ?? '').trim().toLowerCase();
+  const completions = [
+    { value: 'list', label: 'list', description: 'List AI scheduled jobs with titles, bodies, and next trigger times' },
+  ];
+  return completions.filter((completion) => completion.value.toLowerCase().startsWith(trimmed));
+}